Accessible Color Tokens — WCAG-Compliant Color System

Designing Accessible Color Tokens

Accessibility is not an afterthought when building a design token system. By embedding contrast requirements directly into your token structure, you guarantee that every component built with these tokens meets WCAG guidelines.

The On-Color Pattern

The most effective pattern pairs every background color with a guaranteed-contrast foreground color:

:root {
  --colors-primary: #2563eb;
  --colors-on-primary: #ffffff;      /* 8.6:1 ratio */

  --colors-surface: #f4f4f5;
  --colors-on-surface: #18181b;      /* 16.5:1 ratio */

  --colors-error: #dc2626;
  --colors-on-error: #ffffff;        /* 4.6:1 ratio */
}

WCAG Contrast Requirements

• AA Normal text (4.5:1): Body text, labels, input values
• AA Large text (3:1): Headings 18px+ or bold 14px+
• AAA Normal text (7:1): Enhanced accessibility target

Testing Token Pairs

For each token pair, calculate the contrast ratio:

Background	Foreground	Ratio	AA	AAA
--primary #2563eb	--on-primary #fff	8.6:1	Pass	Pass
--surface #f4f4f5	--on-surface #18181b	16.5:1	Pass	Pass
--warning #ffc107	--on-warning #000	14.8:1	Pass	Pass

Interactive State Tokens

Don't forget hover, focus, and disabled states. Each needs its own contrast-verified token pair:

:root {
  --colors-primary-hover: #1d4ed8;
  --colors-on-primary-hover: #ffffff; /* 11.2:1 */
  --colors-primary-disabled: #93c5fd;
  --colors-on-primary-disabled: #1e3a5f; /* 5.1:1 */
}

Automated Verification

Include a CI step that validates all token pairs against WCAG thresholds. Tools like axe-core or custom scripts can parse your token file and flag any pair that falls below 4.5:1.