Accessibility
Everything is reachable from the keyboard, focus is always visible, and contrast is measured and recorded.
Two requirements are fixed. Every component has a visible focus state and a full keyboard path. Contrast is a strong default: WCAG AA, with a few named exceptions below, each with its reason. A component ships below AA only in a case listed on this page.
Contrast
Text pairs
Text needs 4.5:1 against its background. These are the system’s pairs.
| Ratio | Pair | Where | Verdict |
|---|---|---|---|
| 17.20:1 | --foreground on --background | Body text and headings on the page (18.25:1 on white) | Clears AA and AAA. |
| 7.01:1 | --muted-foreground on --background | Descriptions, placeholders, helper text (7.44:1 on white) | Clears AA and AAA. |
| 5.48:1 | --muted-foreground on --accent | Muted text on a row under the pointer | Clears AA. |
| 14.14:1 | --secondary-foreground on --secondary | Secondary button and badge text | Clears AA and AAA. |
| 11.96:1 | --accent-foreground on --accent | Highlighted menu rows, ghost buttons under the pointer | Clears AA and AAA. |
| 4.93:1 | --primary-text on --background | Orange as text (5.23:1 on white) | Clears AA. |
| 5.17:1 to 6.23:1 | Status fills and their text | Success, warning, error | Each pair clears AA. |
Where a component ships below AA
These pairs are below the bar and are kept deliberately. The reason is part of the record.
| Ratio | Pair | Where | Why it stays |
|---|---|---|---|
| 3.59:1 | --primary-foreground on --primary | White on orange-600 | Every orange fill carries white: the default button, the badge, the pressed chip, and the selected calendar numeral. Dark text on orange reads muddy, and white scores higher under APCA (Lc 68 against Lc 49). Hover steps to orange-700, where white holds 5.23:1. |
| 2.65:1 | --progress-fill on --progress-track | Progress and stepper fill | The fill is under the 3:1 bar for non-text against its track, and clears it at 3.38:1 against the page. The track is 1.28:1 on the page, so an empty bar stays visible without a border. |
| 2.65:1 and 2.11:1 | --indicator on orange-200 and its hover step | An indicator mark on a highlighted row, a calendar day under the pointer, or the range band | Orange-600 lands on the same orange-200 the highlight uses. The mark is a small accent next to text that holds full contrast. |
| 1.28:1 | --accent ring on --background (1.36:1 on white) | Focus and press ring of outline, secondary, and ghost buttons and an unpressed toggle group chip | These ring in the colour their hover washes to, so the ring and the hover read as one family. The label inside stays at full text contrast. |
| 1.47:1 to 2.89:1 | --chart-1 to --chart-5 on white | Chart series | The pale hues are told apart by their label and position, never by their edge against the card. Near-black text on slots two to five holds 9.20:1 or more. |
| 1.48:1 | --slider-fill on the slider well | Slider fill | The fill repeats what the thumb and the description already say. The thumb border clears 3:1 at 3.13:1 on the well, and the description names the current step. |
Keyboard
Every control is reachable by Tab and operable without a pointer. Components follow the pattern their role has on the platform, so the keys you expect work. The common keys:
| Key | Description |
|---|---|
| TabShift+Tab | Move focus to the next or previous control. A field and an interactive adornment inside it are two stops, field first. |
| EnterSpace | Activate a button, toggle a checkbox or switch, open a select or menu. |
| ArrowUpArrowDown | Move through the options of a menu, select, combobox list, radio group, or tabs. |
| Escape | Close the top floating surface: a menu, select list, date picker panel, dialog, or drawer. A notice never takes Escape, because that key belongs to dialogs. |
Each component page lists the keys it adds, including the ones that do nothing.
Focus
Focus is always visible, and it shows on keyboard focus (:focus-visible) so a mouse click does not leave a ring behind. Fields and form controls ring in --indicator. Anything else rings in --ring, near-black, which stands out against every surface. An invalid field rings in --destructive.
A dialog traps focus while it is open and returns it to the trigger when it closes. A notice never takes focus, so it cannot interrupt what you are typing.
Not by colour alone
A state is never carried by colour only. A switch shows on and off by position and track. An invalid field shows its message in words. A group colour always comes with a text label.
Usage rules
- DoCheck every new text pair at 4.5:1 and every graphic that carries meaning at 3:1.Those are the WCAG AA bars for text and for non-text elements.
- DoGive every icon-only control a name a screen reader can say.The icon is all a sighted user gets, and a screen reader has nothing else to read.
- DoPair colour with words or a shape wherever colour carries meaning.A reader who cannot tell the hues apart still gets the message.
- Don’tRemove or hide a focus ring.A keyboard user then cannot tell where they are. Restyle the ring if it clashes, but keep it visible.
- Don’tMake a component usable by pointer only.Every action needs a path that works with Tab, Enter, Space, and the arrow keys.