Accessibility

Accessibility is a release gate, not a later pass. These are the rules every component is built to.

Semantics first

• Interactive parts are native elements: <button>, <a href>, <input>, <select>. When a native element can't do the job, the component follows the matching WAI-ARIA Authoring Practices pattern (tabs, listbox, combobox, dialog, slider, menu).
• Overlays, menus and selects are built on Radix UI primitives, which handle focus trapping, aria-expanded, aria-controls and dismiss behaviour.
• Every control has an accessible name: a visible <label>, aria-label or aria-labelledby. Icon-only buttons always carry a label.
• Purely decorative layers (glows, particles, background grids) are hidden with aria-hidden so they don't add noise to a screen reader.

Keyboard

• Everything you can do with a pointer, you can do with a keyboard.
• Composite widgets use a single tab stop and arrow keys inside, as the matching ARIA pattern describes.
• Focus is always visible. Components use focus-visible rings drawn from --ring, never outline: none on its own.
• Dialogs return focus to the element that opened them.

Motion

• Every animated component checks prefers-reduced-motion. Under reduced motion, looping effects stop and entrances become a simple fade or appear at once.
• Nothing flashes more than three times a second.
• Auto-playing movement that lasts more than five seconds can be paused.

See Motion and reduced motion for how to keep this true in your own code.

Colour and contrast

• Body text keeps a contrast ratio of at least 4.5:1, large text and UI boundaries at least 3:1, in light and dark.
• State is never shown by colour alone. Errors carry text, selected items carry a check or weight change.
• The theme customizer checks contrast for every token pairing before you install a theme.

How it is checked

• Lint: eslint-plugin-jsx-a11y runs on every file in CI.
• End-to-end: Playwright loads pages and runs axe-core. Serious and critical violations fail the build.
• Unit tests: component tests assert roles, names and keyboard behaviour with Testing Library.

The quality page summarises these checks, and the verified table shows, for every registry item, whether it has tests, docs and a demo.

What automated checks miss

Automated tools catch only part of the problem. A pass means axe and our tests found nothing, not that a screen reader user has tried every flow. The tests don't judge whether focus order makes sense in your page, whether your labels are meaningful, or whether your content is clear. After you change a component, the checks describe our version, not yours, so test the screens you ship with a keyboard and a screen reader.