Accessibility

Contrast Matrix

Every meaningful foreground/background pairing in SubstrateUI, audited against WCAG AA thresholds in both light and dark mode.

Sourcescripts/audit-contrast.ts

SubstrateUI ships with every color pairing verified: 37 of 37 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: 7/30/2026, 4:25:06 AM. Run npm run audit:contrast to regenerate.

Core

Pairing	Sample	Required	Light	Dark
foreground / background	Aa	4.5:1	15.46:1 PASS	17.50: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	13.49:1 PASS	9.54:1 PASS
muted-foreground / muted	Aa	4.5:1	5.52:1 PASS	5.75:1 PASS
muted-foreground / background	Aa	4.5:1	6.32:1 PASS	7.76:1 PASS
accent-foreground / accent	Aa	4.5:1	7.55:1 PASS	8.44:1 PASS
destructive-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	15.46:1 PASS	17.50:1 PASS
foreground / surface-page	Aa	4.5:1	16.69: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	13.49:1 PASS	17.50:1 PASS
foreground / surface-interactive	Aa	4.5:1	13.49: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	8.08:1 PASS
status-warning-text / status-warning-surface	Aa	4.5:1	7.22:1 PASS	11.51:1 PASS
status-error-text / status-error-surface	Aa	4.5:1	6.42:1 PASS	7.71:1 PASS
status-info-text / status-info-surface	Aa	4.5:1	5.86:1 PASS	8.04:1 PASS
status-success / status-success-surface	Aa	3:1	3.24:1 PASS	6.83:1 PASS
status-warning / status-warning-surface	Aa	3:1	3.19:1 PASS	9.94:1 PASS
status-error / status-error-surface	Aa	3:1	3.92:1 PASS	5.13:1 PASS
status-info / status-info-surface	Aa	3:1	3.37:1 PASS	6.22:1 PASS
status-success / background	Aa	3:1	3.53:1 PASS	7.91:1 PASS
status-warning / background	Aa	3:1	3.11:1 PASS	11.99:1 PASS
status-error / background	Aa	3:1	4.27:1 PASS	5.69:1 PASS
status-info / background	Aa	3:1	3.71:1 PASS	7.02:1 PASS

Secondary Fill

Pairing	Sample	Required	Light	Dark
secondary-fill-foreground / secondary-fill	Aa	4.5:1	6.76:1 PASS	11.46:1 PASS
secondary-fill-border / background	Aa	3:1	4.94:1 PASS	5.63:1 PASS
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	3.91:1 PASS	7.76:1 PASS
border-strong / background	Aa	3:1	9.54:1 PASS	7.76:1 PASS
ring / background	Aa	3:1	4.45:1 PASS	6.01:1 PASS
border / card	Aa	3:1	4.40:1 PASS	6.45:1 PASS
status-success / status-success-surface	Aa	3:1	3.24:1 PASS	6.83:1 PASS
status-warning / status-warning-surface	Aa	3:1	3.19:1 PASS	9.94:1 PASS
status-error / status-error-surface	Aa	3:1	3.92:1 PASS	5.13:1 PASS
status-info / status-info-surface	Aa	3:1	3.37:1 PASS	6.22:1 PASS
status-success / background	Aa	3:1	3.53:1 PASS	7.91:1 PASS
status-warning / background	Aa	3:1	3.11:1 PASS	11.99:1 PASS
status-error / background	Aa	3:1	4.27:1 PASS	5.69:1 PASS
status-info / background	Aa	3:1	3.71:1 PASS	7.02:1 PASS