Contrast for accessibility (WCAG AA recap)

The numbers from A5, applied to design tokens

(Quick recap from HTML A5 lesson 4 — now we apply it through tokens.)

WCAG AA requires:

• Body text: 4.5:1 contrast against background.
• Large text (18pt+ regular or 14pt+ bold): 3:1.
• UI elements (buttons, focus rings): 3:1.

When you build a token palette, ensure every --text value passes against every --bg value:

:root {
  --bg: white;
  --text: oklch(0.20 0 0);        /* dark gray — passes 7:1 against white */
  --text-muted: oklch(0.50 0 0);  /* mid gray — passes 4.5:1 (just) */
  --text-disabled: oklch(0.65 0 0); /* light gray — FAILS body, passes large only */
}

Be honest about what disabled colors are FOR. --text-disabled is meant for disabled UI controls where 3:1 is the floor.

Tool tips

• Chrome DevTools color picker → shows the contrast ratio + AA/AAA pass.
• axe DevTools extension → flags every contrast violation across the page.
• WebAIM Contrast Checker → compute manually.

Dark mode contrast

In dark mode, contrast is BETWEEN dark and light. Pure black (#000) on near-black surface (#0D1117) fails. Use:

• Dark mode body bg: oklch(0.18 0 0) (≈ #1c1c1c)
• Dark mode body text: oklch(0.95 0 0) (≈ #f2f2f2)

That pair = 12:1 contrast. Passes AAA.

Brand-color contrast

.btn-primary { background: var(--primary); color: var(--primary-fg); }

Make sure --primary-fg (the text COLOR shown on the primary background) passes 4.5:1 against --primary. White-on-blue (#3B82F6) passes (4.5:1 exactly). White-on-yellow fails — needs dark text.