Skip to content

Accessibility

Floor: WCAG 2.2 Level AA. Of the 55 audited text pairings (11 foregrounds × 5 grounds), 50 meet AA and 38 reach AAA. The five AA failures are all color.ink.faint, which is scoped to decorative, disabled and large text only.

Pairings are stated as token paths, not literal hex. A hex written into this page is a copy that drifts; a token path resolves.

Ratios recomputed 2026-09-22 from tokens/tokens.json, against the neutral ground ladder and the standard status set. AAA ≥ 7.0, AA ≥ 4.5, — = large text only (≥ 3.0), fail = below 3.0.

Foreground color.ground.0 color.ground.1 color.ground.surface-1 color.ground.surface-2 color.ground.surface-3
color.ink.bright 19.80 AAA 19.03 AAA 18.10 AAA 17.04 AAA 15.72 AAA
color.ink.base 16.91 AAA 16.25 AAA 15.46 AAA 14.56 AAA 13.42 AAA
color.ink.muted 11.37 AAA 10.93 AAA 10.39 AAA 9.79 AAA 9.03 AAA
color.ink.dim 7.46 AAA 7.17 AAA 6.82 AA 6.42 AA 5.92 AA
color.ink.faint 3.53 — 3.40 — 3.23 — 3.04 — 2.81 fail
color.amber.base 9.89 AAA 9.51 AAA 9.04 AAA 8.51 AAA 7.85 AAA
color.amber.dim 6.03 AA 5.80 AA 5.51 AA 5.19 AA 4.79 AA
color.status.success 11.36 AAA 10.92 AAA 10.38 AAA 9.78 AAA 9.02 AAA
color.status.warning 12.93 AAA 12.43 AAA 11.82 AAA 11.13 AAA 10.26 AAA
color.status.info 9.24 AAA 8.88 AAA 8.45 AAA 7.96 AAA 7.34 AAA
color.status.error 7.16 AAA 6.88 AA 6.54 AA 6.16 AA 5.68 AA
  • color.ink.faint is not body copy. It clears the 3:1 large-text floor on four grounds and fails it on color.ground.surface-3. Decorative, disabled, or large text only — and not large text on color.ground.surface-3.
  • color.status.error reaches AAA on color.ground.0 alone. On every raised surface it is AA. Fine for labels, borders and iconography; do not set long-form reading copy in it.
  • color.amber.dim is AA everywhere and AAA nowhere. It is the pressed and hover state of the accent, not a paragraph colour.
  • The status colours are not identity colours. Every state carries a word or an icon, so nothing depends on hue alone (SC 1.4.1).
  • Text on a filled accent is color.ink.on-accent, never white. It measures 9.89 / 11.36 / 12.93 / 7.16 / 9.24 on amber, success, warning, error and info.

There is no light theme. The few surfaces that are genuinely light and outside the brand’s control (the email signature, invoices, print) use color.mark.dark for text and color.amber.on-light for the accent, because color.amber.base is 2.00:1 on white.

Element Tokens Ratio Level
Body text color.email.body on color.email.container 15.46 AAA
Headings color.ink.bright on color.email.container 18.10 AAA
Links and h2 underline color.semantic.accent.email on color.email.container 9.04 AAA
CTA label color.component.cta.text on color.component.cta.bg 9.89 AAA
Footer fine print color.email.fine on color.email.bg 7.46 AAA
Signature link color.amber.on-light on white 5.49 AA
Signature name color.mark.dark on white 17.04 AAA

Use the focus.* group. The ring is focus.ring, which references color.semantic.accent.primary (amber), at focus.width (2px) with focus.offset (2px), and focus.offset-colour is the spacer between component and ring. It measures 9.89:1 on color.ground.0, well clear of the 3:1 the criteria require.

Two rules that are easy to get wrong:

  1. shadow.focus-halo is not a focus indicator. It is a 10% wash of the accent, measuring about 1.15:1 against the grounds. It may sit behind a real ring as extra affordance; it may never be the ring.
  2. Always pair the ring with outline: 2px solid transparent; outline-offset: 2px. Forced-colors and Windows High Contrast drop box-shadow entirely; the transparent outline is what survives and gets repainted by the OS.

A visible ring is not enough if the sticky header covers the element that has just taken focus. components/bundle.css sets html { scroll-padding-top: 6.5rem } against a header that renders about 5.4rem tall, so a focused target scrolls clear of the bar. A consumer who changes the header height must keep scroll-padding-top in step; the rule belongs on html because the browser reads scroll padding from the scrolling element. The mobile nav panel is capped at the viewport minus the header and scrolls, and is visibility: hidden when shut so its links leave the tab order.

color.line.input (~35% white) composited over the five grounds measures 3.12 / 3.19 / 3.21 / 3.21 / 3.16, passing on all five. The tightest ground is color.ground.0 at 3.12, not the lightest surface: a white alpha line gains contrast as the ground lifts and then loses it again, so the headroom is thinnest at the bottom of the ladder. These are the figures npm run validate recomputes from the recorded convention.

A control that carries a visible text label does not additionally need a 3:1 boundary; the criterion’s Understanding document exempts it. Ghost buttons are compliant on their label contrast alone.

A glass surface composites over the canvas, so it lands darker than the opaque surface it stands in for; text on color.glass.surface over color.ground.0 reads at least as well as on color.ground.surface-1. Glass over imagery or over the hero grid is not covered by that: test per placement. shadow.phosphor and shadow.phosphor-text are decorative and carry no meaning; a glow never substitutes for the focus ring.

Underline body links (never colour alone). Meaningful link text (never “click here”). lang set on documents. role="presentation" on layout tables. Alt text on all logos. A scrolling table wrapper carries tabindex="0", role="region" and an aria-label. Respect prefers-reduced-motion for anything animated — and note that the atmosphere layers (atmosphere.grain, atmosphere.scanline) are static overlays, so the correct signal for those is prefers-reduced-transparency, not reduced-motion.