Accessible Contrast Palette with CSS Variables

Building an Accessible Contrast Palette

Accessibility is not an afterthought — it is a design requirement. WCAG 2.1 defines minimum contrast ratios: 4.5:1 for normal text (Level AA) and 7:1 for enhanced contrast (Level AAA). Your CSS variable palette should encode these constraints.

Pairing Strategy

Map each background shade to a guaranteed-contrast text shade:

:root {
  /* backgrounds + guaranteed text pairings */
  --bg-light:   #ffffff;  /* text: --text-dark (21:1) */
  --bg-surface: #f4f4f5;  /* text: --text-dark (18.1:1) */
  --bg-dark:    #18181b;  /* text: --text-light (17.4:1) */

  --text-dark:  #18181b;
  --text-light: #fafafa;
  --text-muted: #71717a;  /* on --bg-light: 5.7:1 ✓ AA */
}

Documenting Contrast Ratios

Embed contrast information as CSS comments:

:root {
  --primary-500: #3b82f6;  /* on white: 3.1:1 ✗ (use for large text only) */
  --primary-700: #1d4ed8;  /* on white: 6.4:1 ✓ AA */
  --primary-800: #1e40af;  /* on white: 8.5:1 ✓ AAA */
}

Common Pitfalls

1. Muted text too light — Gray-400 on white often fails AA. Use at least gray-500 (5:1+).
2. Colored text on colored bg — Blue text on dark-blue background may look distinct but fail contrast.
3. Focus indicators — Focus rings need 3:1 contrast against adjacent colors (WCAG 2.4.11).
4. Dark mode assumptions — White text on dark backgrounds is not always sufficient; check each pairing.

Automated Testing

Use tools like axe-core or Chrome Lighthouse to audit contrast. Define your palette with accessibility in mind from the start, and these audits become confirmations rather than surprises.

Semantic Tokens for Accessibility

Create explicit accessible pairings:

:root {
  --text-on-primary: #ffffff;    /* on --primary-600: 4.9:1 ✓ */
  --text-on-success: #ffffff;    /* on --success-600: 4.6:1 ✓ */
  --text-on-error:   #ffffff;    /* on --error-600: 4.5:1 ✓ */
}