Contrast Matrix
Every meaningful foreground/background pairing in SubstrateUI, audited against WCAG AA thresholds in both light and dark mode.
SubstrateUI ships with every color pairing verified: 26 of 26 pairings pass WCAG AA contrast requirements. Normal text requires 4.5:1; large text and essential UI elements require 3:1. Translucent surfaces are composited against their parent surface before measurement — the numbers below reflect what users actually see on screen.
Last audited: 4/5/2026, 5:11:08 PM. Run npm run audit:contrast to regenerate.Core
| Pairing | Sample | Required | Light | Dark |
|---|---|---|---|---|
| foreground / background | Aa | 4.5:1 | 16.69:1 PASS | 16.72:1 PASS |
| card-foreground / card | Aa | 4.5:1 | 17.38:1 PASS | 14.53:1 PASS |
| popover-foreground / popover | Aa | 4.5:1 | 17.38:1 PASS | 12.97:1 PASS |
| primary-foreground / primary | Aa | 4.5:1 | 7.04:1 PASS | 5.09:1 PASS |
| secondary-foreground / secondary | Aa | 4.5:1 | 15.46:1 PASS | 12.97:1 PASS |
| muted-foreground / muted | Aa | 4.5:1 | 6.32:1 PASS | 5.75:1 PASS |
| muted-foreground / background | Aa | 4.5:1 | 6.83:1 PASS | 7.42:1 PASS |
| accent-foreground / accent | Aa | 4.5:1 | 7.55:1 PASS | 7.93:1 PASS |
| primary-foreground / destructive | Aa | 4.5:1 | 4.89:1 PASS | 4.69:1 PASS |
Sidebar
| Pairing | Sample | Required | Light | Dark |
|---|---|---|---|---|
| sidebar-foreground / sidebar | Aa | 4.5:1 | 17.38:1 PASS | 15.46:1 PASS |
| sidebar-primary-foreground / sidebar-primary | Aa | 4.5:1 | 7.04:1 PASS | 5.09:1 PASS |
| sidebar-accent-foreground / sidebar-accent | Aa | 4.5:1 | 7.55:1 PASS | 7.24:1 PASS |
Surfaces
| Pairing | Sample | Required | Light | Dark |
|---|---|---|---|---|
| foreground / surface-ground | Aa | 4.5:1 | 16.69:1 PASS | 16.72:1 PASS |
| foreground / surface-page | Aa | 4.5:1 | 17.38:1 PASS | 15.46:1 PASS |
| foreground / surface-raised | Aa | 4.5:1 | 17.38:1 PASS | 14.53:1 PASS |
| foreground / surface-sunken | Aa | 4.5:1 | 15.46:1 PASS | 16.72:1 PASS |
| foreground / surface-interactive | Aa | 4.5:1 | 15.46:1 PASS | 12.97:1 PASS |
Status
| Pairing | Sample | Required | Light | Dark |
|---|---|---|---|---|
| status-success-text / status-success-surface | Aa | 4.5:1 | 5.70:1 PASS | 7.55:1 PASS |
| status-warning-text / status-warning-surface | Aa | 4.5:1 | 6.78:1 PASS | 10.70:1 PASS |
| status-error-text / status-error-surface | Aa | 4.5:1 | 6.42:1 PASS | 7.27:1 PASS |
Amber Button
| Pairing | Sample | Required | Light | Dark |
|---|---|---|---|---|
| raw-warm-900 / raw-amber-500 | Aa | 4.5:1 | 6.76:1 PASS | 6.76:1 PASS |
| raw-warm-950 / raw-amber-400 | Aa | 4.5:1 | 11.46:1 PASS | 11.46:1 PASS |
UI Elements
| Pairing | Sample | Required | Light | Dark |
|---|---|---|---|---|
| border / background | Aa | 3:1 | 4.22:1 PASS | 7.42:1 PASS |
| border-strong / background | Aa | 3:1 | 10.30:1 PASS | 7.42:1 PASS |
| ring / background | Aa | 3:1 | 4.81:1 PASS | 5.75:1 PASS |
| border / card | Aa | 3:1 | 4.40:1 PASS | 6.45:1 PASS |