wcag-color-contrast

Overview

WCAG 2.2 specifies four color-contrast Success Criteria (wcag22):

Large text per WCAG 2.2 (wcag22): 18pt+ regular OR 14pt+ bold (24px / 18.66px in browsers default; 19px+ if bold).

When to use

• Designing a new color palette / design tokens.
• Reviewing a component's CSS for contrast violations.
• Setting up bulk-checking of design tokens via tooling.
• Authoring per-component a11y checklists (paired with wcag-checklist-builder).
• Configuring per-rule severity in axe-a11y / pa11y-a11y.

Contrast ratios

Text (SC 1.4.3 - Level AA)

Exceptions per wcag22:

• Pure decoration (text in a logo, "lorem ipsum" filler).
• Inactive UI elements (disabled buttons - though the disabled state should still have visible-but-low-contrast text).
• Logotypes - brand text within a logo.
• Incidental text (text within an image of running text where the image isn't an essential conveyance of information).

Text (SC 1.4.6 - Level AAA)

The enhanced version doubles down: 7:1 normal, 4.5:1 large. Use this for accessibility-first products (educational platforms, public-sector services).

UI components and graphics (SC 1.4.11 - Level AA, NEW in 2.1)

Visual presentation of UI components and graphical objects must have 3:1 contrast against adjacent colors. This applies to:

• Form input borders.
• Focus indicators (per wcag-keyboard-navigation SC 2.4.7).
• Icon buttons that don't have text labels.
• Visual state indicators (toggle switches, checkboxes).
• Required-field indicators that rely on color alone.

Content on Hover or Focus (SC 1.4.13 - Level AA)

Tooltips, dropdowns, and other content that appears on hover/focus must satisfy three conditions:

Most "tooltip" libraries fail one of these - typically Hoverable (pointer leaves trigger → tooltip dismisses → can't read it).

Measuring contrast

The WCAG contrast formula uses relative luminance (per wcag22 formula):

ratio = (L1 + 0.05) / (L2 + 0.05)

where L1 is the relative luminance of the lighter color and L2 of the darker. Ratios run from 1:1 (identical colors) to 21:1 (black on white).

You don't compute it manually - use a tool:

Common ratios for canonical color pairings

The "just-passes" boundary #767676 is a design pitfall - small font-rendering shifts on Windows ClearType can drop the perceived contrast below 4.5:1. Aim for ≥5:1 in practice.

Design token bulk checking

When the project has a design-token system (e.g. --color-text-primary: #1a1a1a), check token combinations en masse:

// scripts/check-contrast.js
const { getContrast } = require('polished');

const tokens = require('../tokens/colors.json');

const TEXT_PAIRS = [
  ['--color-text-primary', '--color-bg-default'],
  ['--color-text-secondary', '--color-bg-default'],
  ['--color-text-on-primary', '--color-bg-primary'],
  ['--color-link', '--color-bg-default'],
  ['--color-error', '--color-bg-default'],
];

const violations = [];
for (const [fg, bg] of TEXT_PAIRS) {
  const ratio = getContrast(tokens[fg], tokens[bg]);
  if (ratio < 4.5) {
    violations.push({ fg, bg, ratio: ratio.toFixed(2) });
  }
}

if (violations.length > 0) {
  console.error('Contrast violations:', violations);
  process.exit(1);
}

Wire into CI per a11y-violation-gate.

Common failures

Anti-patterns

References

• wcag22 - WCAG 2.2 SCs 1.4.3, 1.4.6, 1.4.11, 1.4.13.
• WebAIM Contrast Checker - https://webaim.org/resources/contrastchecker/
• WCAG contrast formula (luminance) - https://www.w3.org/TR/WCAG22/#dfn-relative-luminance
• wcag-keyboard-navigation - for SC 2.4.7 focus-indicator contrast.
• axe-a11y - runtime contrast checker.
• a11y-violation-gate - CI gate for contrast (and other) violations.