Accessibility
The system aims at WCAG 2.2, level AA, for everything it ships: tokens, components and patterns. What it can guarantee is built in and tested on every build; what only an app can know is written down as rules.
Who does what
| The system | Contrast of every color pair, focus rings, target sizes, keyboard behavior, roles and states of every component, reduced motion. |
|---|---|
| The app | Page titles and headings, the language of the page, the names it gives to components (labels, button text, chart labels), error messages that say how to fix the error, and the order of content. |
Contrast
Every text level meant to be read, placeholders included, reaches 4.5:1 on every surface that carries text, in both themes (WCAG 1.4.3). Control boundaries, the focus ring and marks such as checkboxes and chart alerts reach 3:1 (1.4.11). Disabled text is exempt from both; the system still keeps it at 3:1 so it can be read.
The 125 pairs below are a contract in the tokens package, lib/accessibility.ts. The token tests
measure each one in both themes on every build, and a change that breaks one fails the build. Each row shows the
lowest ratio across its backgrounds, measured now. Every text level on every surface is in the matrix of
Color.
| Foreground | On | Minimum | Lowest, light | Lowest, dark |
|---|---|---|---|---|
text.strong |
Every text surface | 4.5:1 | 13.6:1 | 9.8:1 |
text.default |
Every text surface | 4.5:1 | 10.1:1 | 9.3:1 |
text.secondary |
Every text surface | 4.5:1 | 7.9:1 | 7.0:1 |
text.muted |
Every text surface | 4.5:1 | 7.3:1 | 4.7:1 |
text.tertiary |
Every text surface | 4.5:1 | 4.6:1 | 4.5:1 |
text.placeholder |
Every text surface | 4.5:1 | 4.6:1 | 4.5:1 |
text.meta |
surface.card, surface.page, surface.raised, surface.menu, surface.hover |
4.5:1 | 5.1:1 | 4.5:1 |
text.accent |
surface.card, surface.page, surface.raised, surface.menu, surface.hover, surface.selected |
4.5:1 | 4.5:1 | 5.1:1 |
text.danger |
surface.card, surface.page, surface.raised, surface.menu, surface.hover, surface.selected |
4.5:1 | 4.5:1 | 4.6:1 |
text.warning |
surface.card, surface.page, surface.raised, surface.menu, surface.hover, surface.selected |
4.5:1 | 4.5:1 | 6.1:1 |
text.strong |
Every notice: the neutral container, and each tint over card and page | 4.5:1 | 13.4:1 | 9.0:1 |
text.default |
Every notice: the neutral container, and each tint over card and page | 4.5:1 | 9.9:1 | 8.6:1 |
text.accent |
success.container over surface.card, success.container over surface.page |
3:1 | 4.2:1 | 5.2:1 |
text.warning |
warning.container over surface.card, warning.container over surface.page |
3:1 | 4.3:1 | 5.2:1 |
text.danger |
danger.container over surface.card, danger.container over surface.page |
3:1 | 4.0:1 | 5.0:1 |
text.inverse |
surface.inverse |
4.5:1 | 11.6:1 | 11.9:1 |
accent.inverse |
surface.inverse |
4.5:1 | 7.9:1 | 4.7:1 |
on.accent |
accent |
4.5:1 | 4.5:1 | 5.2:1 |
on.accent-tonal |
accent.tonal |
4.5:1 | 12.9:1 | 7.4:1 |
on.emphasis |
danger.solid |
4.5:1 | 4.5:1 | 4.5:1 |
border.control |
surface.card |
3:1 | 3.1:1 | 3.3:1 |
focus |
surface.card, surface.page, surface.menu, surface.container |
3:1 | 3.6:1 | 5.4:1 |
accent |
surface.card, surface.page |
3:1 | 4.2:1 | 6.2:1 |
danger |
surface.card, surface.page |
3:1 | 4.1:1 | 4.3:1 |
chart.primary |
surface.card |
3:1 | 4.4:1 | 6.2:1 |
chart.secondary |
surface.card |
3:1 | 20.4:1 | 12.1:1 |
Focus
-
Every control shows a ring when it is reached from the keyboard (2.4.7):
focus.width2 px, atfocus.offset2 px, incolor.focus, which keeps 3:1 against every surface it can sit on. A ring is never removed without another visible indicator in its place. -
Pointer clicks draw no ring;
:focus-visibledecides, as the browser does for its own controls. - Nothing covers what has focus (2.4.11). On phones and tablets the top bar is sticky, so the page keeps room for it above anything scrolled into view; menus and tooltips open beside their trigger, never over it.
- A modal dialog moves focus in and returns it to what opened it; nothing else moves focus on its own.
Target size
- WCAG 2.2 asks for targets of at least 24 × 24 px (2.5.8). Controls are 28 or 36 px tall, and spaced so that neighbors never overlap.
-
On touch screens every control’s hit area grows to 48 × 48 px,
layout.touch-target, without changing how it looks. Labels of checkboxes and switches are part of the target.
Motion
-
Under
prefers-reduced-motion, every component stops moving things across the screen: menus, dialogs, sheets and toasts appear in place, and shapes change without traveling. Short fades and color changes remain, so state changes are still visible. - Nothing animates on load, nothing flashes, and nothing moves on its own for more than a moment.
Keyboard
- Everything that works with a pointer works with a keyboard (2.1.1), in the order the page is read.
- Tab moves between controls; arrow keys move inside a group of options, a menu or a chart, as the platform does. Each component page lists its keys under Accessibility.
- Only a modal dialog keeps focus inside it, by design, and Escape always leaves it (2.1.2).
Screen readers
- Native first. Buttons, checkboxes, switches, radios, fields and dialogs are the browser’s own elements, so their roles and states are right in every screen reader. Base UI supplies the rest (menus, tooltips, toasts) following the WAI-ARIA patterns.
- Every control has a name. Icon buttons require one; icons are hidden; repeated buttons say what they act on.
- Never color alone (1.4.1). States are written; legends name every color; charts list their values in words.
- Changes are announced. Toasts arrive in a polite live region, and a card announces what its step buttons change: the day, the due date, the month.
- Regions. Each card of the overview is a region named by its title, so the overview can be read card by card.
Reflow and text
- Pages reflow down to 320 px without scrolling sideways (1.4.10). Long code and wide tables scroll inside their own block, which can be focused and scrolled from the keyboard.
- Text sizes are in the type roles and scale with the browser’s text size (1.4.4); nothing is set to stop zoom.
- Cards in the overview grid have one of four heights. With very large text or extra text spacing (1.4.12) nothing is cut: content that no longer fits scrolls inside the card, between its header and footer, and can be scrolled from the keyboard.
How it is checked
- On every build, automatically: the 125 contrast pairs in both themes; every component rendered and checked with axe in its tests.
- Before every release, by hand and with scripts: every page of this site at 360, 390, 430, 834, 1024 and 1440 px, light and dark, with every code block open, checked for anything that scrolls the page sideways; a keyboard pass through every component; VoiceOver on iOS and macOS through every component; text at 200%.
Known limits
- The Sonar-DB dashboard is audited on its own, once it is built on these tokens and components; this site covers the system, the patterns and their live examples.