Accessibility

What Chassis CSS gives you for free, what's still your responsibility, and how the token-driven color system makes contrast guarantees possible.

Chassis CSS provides a foundation for building accessible web applications: a token-driven color system designed in contrast pairs, interactive components built around relevant ARIA roles and attributes, support for prefers-reduced-motion, and utilities for visually-hidden content. The framework gives you a strong starting point — but accessibility ultimately depends on the markup, semantics, and content choices you make in your own code.

What Chassis provides

Contrast-aware color palettes

Every Chassis context palette is built from token pairs designed to meet WCAG 2.2 contrast ratios for body text (4.5:1) and large text or UI components (3:1). When a component reads --cx-fg-main against --cx-bg-main from the same context, it inherits that contrast guarantee — for both light and dark modes.

This guarantee holds for the default Chassis brand. If you swap in a custom token build, the responsibility moves to the token authors: as long as your token pairs maintain those ratios, the framework propagates them through every component automatically. See the Color System for how the layered palette is structured.

That said, always test with real content. Long-form text, dense data tables, and custom component combinations can produce contrast situations the generic palette tokens don't anticipate.

Interactive components

Chassis's interactive components — modals, dropdowns, tooltips, popovers, accordions, tabs, and so on — are designed to work for touch, mouse, and keyboard input. They use relevant WAI-ARIA roles and attributes so assistive technologies can interpret them correctly.

The components are deliberately generic. Authors typically need to add component-specific ARIA roles, properties, and labels to convey the precise nature and purpose of the component in context — for example, aria-label on icon-only buttons, aria-describedby for help text on form fields, aria-current on active navigation items. The component documentation calls out these additions where they apply.

Reduced motion

Chassis CSS respects the prefers-reduced-motion media feature. When a user signals a preference for reduced motion at the OS level, Chassis disables most CSS transitions (modal open/close, carousel slides, accordion expand/collapse) and slows down animations that carry meaning (loading spinners, progress indicators).

When prefers-reduced-motion: no-preference is in effect — the user has not opted out — Chassis enables scroll-behavior: smooth for in-page navigation. To disable smooth scrolling globally, set $enable-smooth-scroll: false before importing Chassis.

For content that should be available to assistive technologies but invisible on screen, use the .visually-hidden class:

<p class="fg-danger">
  <span class="visually-hidden">Danger: </span>
  This action is not reversible.
</p>

For interactive controls that should appear when focused — typical "skip to main content" links — use .visually-hidden-focusable. The control is invisible until it receives focus, at which point it becomes visible for sighted keyboard users:

<a class="visually-hidden-focusable" href="#content">Skip to main content</a>

.visually-hidden-focusable is a standalone class — don't combine it with .visually-hidden.

What's still your responsibility

The framework can't make decisions about your content for you. Producing an accessible page requires you to:

Write semantic HTML. Use <button> for buttons, <a> for links, headings in order, lists for lists. Chassis styles work on any element, but assistive technology relies on the element type to convey meaning.
Provide text alternatives. Every meaningful image needs alt text; icon-only buttons need aria-label or visually-hidden text; SVG decorative graphics need aria-hidden="true".
Manage focus. When opening a modal, focus moves to it; when closing, focus returns to the trigger. Chassis's interactive plugins handle the common cases, but custom components are your responsibility.
Test with real assistive technology. Screen readers, voice control, switch input, and keyboard-only navigation all reveal issues that automated tools miss.
Verify contrast in custom components. The token-driven contrast guarantees apply to the default Chassis brand and to custom components that consume body color variables. Hardcoded colors break the guarantee.

Conformance

The overall accessibility of any project built with Chassis CSS depends on the markup, content, scripting, and additional styling you author. When implemented carefully, it's possible to build websites and applications with Chassis CSS that meet WCAG 2.2 (A/AA/AAA), Section 508, and similar standards.