Accessibility
Accessibility rules the design system follows.
Target
The design system targets WCAG 2.2 level AA.
- Text contrast of at least 4.5:1. Borders and focus rings of at least 3:1.
- A visible focus indicator on every interactive element.
- Full keyboard support, following the WAI-ARIA Authoring Practices patterns.
- Targets of at least 24 by 24 CSS pixels.
- Motion turns off when the visitor asks for reduced motion.
Contrast check
Every build checks 334 text and border pairs in both themes. 0 fail. A failing pair stops the build. These are the lowest results:
| Theme | Kind | Foreground | Background | Contrast |
|---|---|---|---|---|
| Light | Text | content.tertiary | surface.2 | 5.06:1 (needs 4.5:1) |
| Light | Border | signal.positive.low.border | surface.1 | 4.35:1 (needs 3:1) |
| Dark | Text | content.tertiary | surface.4 | 4.72:1 (needs 4.5:1) |
| Dark | Border | signal.negative.low.border | surface.1 | 3.51:1 (needs 3:1) |
Disabled text and borders are exempt, as WCAG allows. So are decorative borders: border.secondary and border.subtle. The token table shows the result for each token.
How components are tested
Each component gets an interaction test and an automated accessibility check (axe). Automated checks find only part of the problems, so each component page also lists what to check with a screen reader.
Guidance
- Text needs at least 4.5:1 contrast, and borders and icons that carry meaning need 3:1. The token build checks this.
- Never use color alone to show meaning. Add text or an icon.
- Every input needs a label. Placeholder text is not a label. Hide a label visually only when the purpose is obvious from context.
- Click targets are at least 24×24 px.
- Design the focus state and the keyboard order, not only the mouse flow.
- Link and button text should make sense on its own. Avoid "Click here".