WCAG Contrast Ratio for Text

Real-World Examples

Testing & Standards

Full token audit script — tests all text/surface pairs and flags failures

type TokenPair = { name: string; fg: string; bg: string; min: number; role: string };

function luminance(hex: string): number {
  const rgb = hex.replace('#', '').match(/.{2}/g)!.map(v => {
    const n = parseInt(v, 16) / 255;
    return n <= 0.03928 ? n / 12.92 : Math.pow((n + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2];
}

function ratio(fg: string, bg: string): number {
  const a = luminance(fg);
  const b = luminance(bg);
  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
}

/* Define your design tokens here */
const textTokens = [
  { name: 'fg-default',  hex: '#111827' },
  { name: 'fg-muted',    hex: '#6B7280' },
  { name: 'fg-subtle',   hex: '#9CA3AF' },
  { name: 'fg-link',     hex: '#2563EB' },
  { name: 'fg-error',    hex: '#B91C1C' },
  { name: 'fg-success',  hex: '#047857' },
];

const surfaceTokens = [
  { name: 'bg-white',    hex: '#FFFFFF' },
  { name: 'bg-gray-50',  hex: '#F9FAFB' },
  { name: 'bg-card',     hex: '#F3F4F6' },
  { name: 'bg-error',    hex: '#FEF2F2' },
];

const roleMinimums: Record<string, number> = {
  'fg-default': 7,     // body text — target AAA
  'fg-muted': 4.5,     // secondary text — must pass AA
  'fg-subtle': 4.5,    // captions — must pass AA (or mark decorative)
  'fg-link': 4.5,      // links
  'fg-error': 4.5,     // error messages
  'fg-success': 4.5,   // success messages
};

console.log('Token Pair Audit Report');
console.log('='.repeat(70));

let failures = 0;

for (const fg of textTokens) {
  for (const bg of surfaceTokens) {
    const score = ratio(fg.hex, bg.hex);
    const min = roleMinimums[fg.name] || 4.5;
    const pass = score >= min;
    if (!pass) failures++;
    console.log(
      `${pass ? '✓' : '✗'} ${fg.name} on ${bg.name}: ${score.toFixed(2)}:1 (need ${min}:1)${
        pass ? '' : ' ← FIX'
      }`
    );
  }
}

console.log('='.repeat(70));
console.log(`${failures} failure(s) found across ${textTokens.length * surfaceTokens.length} pairs`);

/* Link contrast check — SC 1.4.1 requires links to be
   distinguishable from surrounding text by ≥3:1 OR non-color cue */
const linkVsBody = ratio('#2563EB', '#111827');
console.log(
  `
Link vs body text: ${linkVsBody.toFixed(2)}:1 ${
    linkVsBody >= 3 ? '(PASS — distinguishable)' : '(FAIL — add underline)'
  }`
);

Copy and paste into your project — free to use.

Pro Tips

• ▸Do not approve a theme from a static mood board. Test real roles: paragraph, caption, button, error, success, focus, and link. Mood boards hide contrast failures because they show fragments, not full screens.
• ▸Avoid using opacity for important text. A 60% black label on white may look neat in Figma but becomes fragile on low-quality screens and tinted backgrounds. Convert opacity to a resolved hex value and test that.
• ▸For brand hues that fail as button backgrounds, darken the background token or switch to an outline button. Do not shrink the text or lower the font weight — both make the problem worse.
• ▸Check hover, active, disabled, and focus states separately. Many teams pass the default state and fail the interaction state. A button that scores 5:1 at rest might drop to 3.2:1 on hover with a lighter fill.
• ▸Thin font weights (300, 200) need higher contrast ratios than WCAG minimums suggest. WCAG does not penalize thin weights, but real-world readability drops sharply. Use 7:1 minimum for any text below font-weight 400.
• ▸Links must be distinguishable from surrounding body text by either 3:1 contrast ratio OR a non-color cue (underline, bold, icon). Most brand blues score around 2.5:1 against dark body text — add an underline to pass SC 1.4.1.
• ▸Placeholder text is the most commonly failed token. Designers make placeholders light gray for aesthetics, but if the placeholder conveys required format information (e.g., 'YYYY-MM-DD'), it must pass 4.5:1. Move format hints to helper text below the field instead.
• ▸Dark mode is a separate audit. Light mode passing does not mean dark mode passes. Build a separate token matrix and test independently. See [WCAG Contrast Checker for Dark Mode](/wcag-contrast-checker-for-dark-mode/) for the full dark mode workflow.
• ▸Pre-ship text contrast checklist: (1) All body text ≥7:1 on actual surfaces (2) Muted text ≥4.5:1 including on gray/tinted backgrounds (3) Links distinguishable from body by ≥3:1 or underline (4) Hover/active/focus states tested independently (5) Error/success text passes on their tinted backgrounds (6) Placeholder text either ≥4.5:1 or marked decorative (7) Dark mode tokens audited separately (8) Font weights below 400 boosted to 7:1 minimum (9) Real device check in outdoor sunlight (10) Windows High Contrast mode verified.
• ▸Use OKLCH lightness to build text scales systematically. Body text at L=15, muted at L=45, subtle at L=55. Each step down in lightness produces a predictable drop in contrast ratio. See [Accessible Color Token System](/accessible-color-token-system/) for the full token architecture.

Developer Perspective