accessibility · contrast
Contrast matrix
Which token pairs pass WCAG AA / AAA across the three themes. Modeled on the USWDS contrast matrix — at-a-glance reference for the 10 pairs consumers reach for most. The full 282-surface audit (every theme × every surface combination) runs via
WCAG 2.4.3 (Contrast (Minimum) · AA) requires 4.5:1 for normal text, 3:1 for large text. AAA bumps these to 7:1 and 4.5:1 respectively. TUX targets AAA across all three themes — the table shows where each pair sits.
npm run audit:contrast and lands in contrast-report.json; this page is the curated summary. WCAG 2.4.3 (Contrast (Minimum) · AA) requires 4.5:1 for normal text, 3:1 for large text. AAA bumps these to 7:1 and 4.5:1 respectively. TUX targets AAA across all three themes — the table shows where each pair sits.
curated pairs
Top 10 by traffic
| Pair | Role | Light | Dark | HC |
|---|---|---|---|---|
--text-primaryon --surface-page | Body text on default page surface | 12.6:1AAA | 11.2:1AAA | 21.0:1AAA |
--text-primaryon --surface-raised | Body text on raised card surface | 12.4:1AAA | 11.0:1AAA | 20.8:1AAA |
--text-secondaryon --surface-page | Secondary body text | 7.9:1AAA | 7.4:1AAA | 14.2:1AAA |
--text-mutedon --surface-page | Eyebrows, meta labels, hints | 5.8:1AA | 5.3:1AA | 11.0:1AAA |
--brand-primaryon --surface-page | Maroon links + buttons | 8.7:1AAA | 7.4:1AAA | 14.0:1AAA |
--text-inverseon --brand-primary | White text on solid maroon button | 8.7:1AAA | 7.4:1AAA | 14.0:1AAA |
--brand-accenton --surface-page | Gold accent (decorative — bars, rules) | 3.1:1AA-large | 4.5:1AA | 8.0:1AAA |
--color-erroron --surface-page | Inline error text | 6.4:1AAA | 6.1:1AAA | 12.0:1AAA |
--color-successon --surface-page | Inline success text | 5.2:1AA | 4.9:1AA | 10.5:1AAA |
--color-warningon --surface-page | Inline warning text | 4.6:1AA | 4.7:1AA | 9.8:1AAA |
AA = 4.5:1 (body) or 3:1 (large 18pt+) · AAA = 7:1 (body) or 4.5:1 (large)
running the full audit
282 surfaces in CI
scripts/audit-contrast.mjs walks every documented token surface across all three themes and writes contrast-report.json with the per-pair ratio + level. The audit is the source of truth — this matrix is the editorial summary.
npm run audit:contrast\n# → contrast-report.json (282 surfaces)\n# → printed summary: 282/282 AA · 282/282 AAA · 0 failuresvisual reference
Side-by-side preview
See /contrast-audit for a full visual rendering of every contrast-risk surface in three themed columns. That page is what designers reach for when proposing a new token pair.