Skip to content
flyingsalmon

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.

RatioPairWhereVerdict
17.20:1--foreground on --backgroundBody text and headings on the page (18.25:1 on white)Clears AA and AAA.
7.01:1--muted-foreground on --backgroundDescriptions, placeholders, helper text (7.44:1 on white)Clears AA and AAA.
5.48:1--muted-foreground on --accentMuted text on a row under the pointerClears AA.
14.14:1--secondary-foreground on --secondarySecondary button and badge textClears AA and AAA.
11.96:1--accent-foreground on --accentHighlighted menu rows, ghost buttons under the pointerClears AA and AAA.
4.93:1--primary-text on --backgroundOrange as text (5.23:1 on white)Clears AA.
5.17:1 to 6.23:1Status fills and their textSuccess, warning, errorEach 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.

RatioPairWhereWhy it stays
3.59:1--primary-foreground on --primaryWhite on orange-600Every 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-trackProgress and stepper fillThe 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 stepAn indicator mark on a highlighted row, a calendar day under the pointer, or the range bandOrange-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 chipThese 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 whiteChart seriesThe 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 wellSlider fillThe 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:

KeyDescription
TabShift+TabMove focus to the next or previous control. A field and an interactive adornment inside it are two stops, field first.
EnterSpaceActivate a button, toggle a checkbox or switch, open a select or menu.
ArrowUpArrowDownMove through the options of a menu, select, combobox list, radio group, or tabs.
EscapeClose 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

  • Do
    Check 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.
  • Do
    Give 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.
  • Do
    Pair colour with words or a shape wherever colour carries meaning.A reader who cannot tell the hues apart still gets the message.
  • Don’t
    Remove 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’t
    Make a component usable by pointer only.Every action needs a path that works with Tab, Enter, Space, and the arrow keys.

  • Colours

    Every token and the step behind it.
  • Principles

    Why feedback persists until it is seen.
  • Motion

    The durations and loops the system uses.