Accessibility
The commitments, how they are checked and what is not covered yet.
What we commit to
The target is WCAG 2.2 level AA for every component. This is a goal for the components, not a certificate: an app built from them can still fail if it is used badly (missing labels, headings out of order, colour overrides).
- Native first. A native element, then a Radix primitive, then hand-written ARIA. Never a
divwithonClick. - Keyboard. Every interactive part is reachable and operable from the keyboard. Escape closes overlays and focus returns to the trigger. Nothing traps focus except modal dialogs, which are meant to.
- Names. Every control has an accessible name. Icon-only buttons and controls without a visible label (OtpInput, Rating, Slider, SegmentedControl) require an
aria-labelin their types. - Errors.
Fieldsetsaria-invalidandaria-describedbyand announces the message;Formadds a summary that links to each field. - Colour is never the only signal. Badges, alerts and errors carry a word as well.
- Target size. Interactive targets are meant to be at least 24 by 24 CSS pixels (WCAG 2.2, 2.5.8). This is a rule in
AGENTS.md; it is not checked by a script.
Keyboard patterns
- Buttons, links
- Enter, and Space for buttons.
- Dialogs, popovers, menus
- Escape closes. Focus moves in on open and back to the trigger on close.
- Menus, tabs, radio groups, toolbars
- Arrow keys move between items, Home and End jump. Only one item is a Tab stop. This comes from Radix.
- Combobox, Select
- Arrow keys move through options, Enter picks, Escape closes.
- Slider
- Arrows step, Home and End jump, PageUp and PageDown take larger steps.
- Calendar
- Arrows move by day and week, Home and End go to the ends of the week, PageUp and PageDown change month.
If you run axe against an open menu or select, it reports aria-hidden-focus on the app root. Radix hides the page behind the menu with aria-hidden and keeps focus trapped in the menu, so no user can reach the hidden content; axe only forgives this for aria-modal dialogs. It is a known false alarm of the Radix pattern, not a Monoline bug. scripts/audit-examples.mjs lists it as KNOWN.
The exact behaviour of each component is listed in the Accessibility section of its page, from meta.json, and each item is covered by a test.
Focus ring and motion
Focus uses one shared rule in base.css: :focus-visible draws a 2px outline in --accent with a 3px offset. Components must not remove it. Under prefers-reduced-motion: reduce the same file turns off all animations and transitions. Components in the effects category are exempt from the shared rule but must respect the preference themselves. In your own code, the useReducedMotion hook reads the preference.
Contrast rules and npm run check
npm run check runs packages/css/scripts/check.mjs, which computes WCAG contrast ratios from the token files and fails the build when one is too low. For each of the three themes it requires:
- 4.5:1 for foreground, muted, danger, warning and ok text on the background.
- 4.5:1 for white text on the surface colour.
- For every theme and accent pair: 4.5:1 for accent text on the background and for the on-accent text on the accent fill, and 3:1 for the accent itself on the background (the focus ring and marks, which need 3:1 under WCAG 1.4.11).
The same script fails if a component stylesheet contains a raw hex colour, so every colour passes through a checked token. npm run check then runs the type check and the tests. This checks tokens, not your pages: custom colours you add (see the Theme builder, which shows a ratio) are yours to verify.
How components are tested
Each component has a test file with behaviour tests written with Testing Library and @testing-library/user-event (real key presses and clicks, found by role and name) and one vitest-axe test. A shared test, all-demos.test.tsx, renders every demo on this site once and runs axe on it, so a broken example fails before it ships.
Be aware of what axe can and cannot do here. It runs in jsdom, which has no layout and no real colours, so the shared axe helper turns off the color-contrast and region rules. Contrast is covered by the token check above, not by axe. axe finds about a third of accessibility problems at best; it does not judge whether a label makes sense or a focus order is logical.
Known limits
- No manual screen reader testing has been done yet. Nobody has tried these components with NVDA, JAWS, VoiceOver or TalkBack. Names, roles and states are as good as the specs and automated tests can show, which is not the same as a good experience. Treat the accessibility notes as intent.
- No automated check of target size, zoom to 400%, text spacing overrides or forced-colours mode.
- Right-to-left support is being worked on; see the i18n guide.
- Some built-in English strings cannot be translated yet (listed in the i18n guide).
- Pages built from the Blocks category are examples. Heading levels and landmarks depend on where you place them.
If you find a barrier, an issue with the component name, the browser, the assistive technology and the steps is the most useful thing you can send.