Contrast Checker Guide

workflow

Testing & Standards

Automated contrast matrix audit — test every token pair in your design system

// Contrast matrix auditor — run against your design system tokens
// Checks every foreground token against every surface it could appear on
// Output: pass/fail table + specific fix suggestions

interface Token { name: string; hex: string; role: 'text' | 'surface' | 'border'; minSize?: string }

const textTokens: Token[] = [
  { name: 'fg-primary',   hex: '#1F2937', role: 'text' },
  { name: 'fg-secondary', hex: '#6B7280', role: 'text' },
  { name: 'fg-muted',     hex: '#9CA3AF', role: 'text' },
  { name: 'fg-link',      hex: '#2563EB', role: 'text' },
  { name: 'fg-error',     hex: '#B91C1C', role: 'text' },
  { name: 'fg-success',   hex: '#047857', role: 'text' },
  { name: 'fg-on-primary',hex: '#FFFFFF', role: 'text' },
];

const surfaceTokens: Token[] = [
  { name: 'bg-white',     hex: '#FFFFFF', role: 'surface' },
  { name: 'bg-gray-50',   hex: '#F9FAFB', role: 'surface' },
  { name: 'bg-gray-100',  hex: '#F3F4F6', role: 'surface' },
  { name: 'bg-card',      hex: '#FFFFFF', role: 'surface' },
  { name: 'bg-error',     hex: '#FEF2F2', role: 'surface' },
  { name: 'bg-success',   hex: '#ECFDF5', role: 'surface' },
  { name: 'bg-primary',   hex: '#2563EB', role: 'surface' },
  { name: 'bg-dark',      hex: '#111827', role: 'surface' },
];

function hexToRgb(hex: string): [number, number, number] {
  const n = parseInt(hex.slice(1), 16);
  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
}

function luminance(r: number, g: number, b: number): number {
  const [rs, gs, bs] = [r, g, b].map(c => {
    c = c / 255;
    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
}

function contrastRatio(fg: string, bg: string): number {
  const [r1, g1, b1] = hexToRgb(fg);
  const [r2, g2, b2] = hexToRgb(bg);
  const l1 = luminance(r1, g1, b1);
  const l2 = luminance(r2, g2, b2);
  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
}

function auditTokenMatrix(texts: Token[], surfaces: Token[]) {
  const results: { pair: string; ratio: string; aa: string; aaa: string; fix?: string }[] = [];
  
  for (const text of texts) {
    for (const surface of surfaces) {
      const ratio = contrastRatio(text.hex, surface.hex);
      const aa = ratio >= 4.5 ? 'PASS' : ratio >= 3 ? 'LARGE ONLY' : 'FAIL';
      const aaa = ratio >= 7 ? 'PASS' : 'FAIL';
      const fix = ratio < 4.5 
        ? `Darken ${text.name} or lighten ${surface.name} — need ${(4.5 - ratio).toFixed(1)} more ratio`
        : undefined;
      results.push({
        pair: `${text.name} on ${surface.name}`,
        ratio: ratio.toFixed(2) + ':1',
        aa, aaa, fix
      });
    }
  }
  
  console.table(results.filter(r => r.aa !== 'PASS'));
  console.log(`\n${results.filter(r => r.aa === 'PASS').length}/${results.length} pairs pass AA`);
  console.log(`${results.filter(r => r.aa === 'FAIL').length} pairs FAIL — fix these before shipping\n`);
  return results;
}

// Run the audit
auditTokenMatrix(textTokens, surfaceTokens);

Copy and paste into your project — free to use.

Pro Tips

• ▸
  Always test the actual background, not white. If your card uses bg-gray-50 (#F9FAFB), a text token that passes on white at 4.6:1 might fail on gray-50 at 4.3:1. The difference is small but the pass/fail line is absolute.
• ▸
  Flatten alpha before checking. Text at rgba(0,0,0,0.6) on white computes to #666666, which scores 5.7:1. But rgba(0,0,0,0.6) on gray-100 computes to #5E5E5E at 6.1:1. The contrast checker needs the computed flat color, not the alpha value.
• ▸
  Check hover states explicitly. Many primary buttons pass at default (4.5:1) but fail on hover because the fill lightens. A common pattern: blue-600 text on white passes, but blue-500 on hover fails at 3.9:1.
• ▸
  Use the APCA Lc column as a future-proofing signal. If a pair passes WCAG 2 at 4.5:1 but scores below Lc 75, it will likely fail under WCAG 3.0. Fix it now while the cost is low.
• ▸
  Build a contrast matrix, not spot checks. Every text token x every surface it can appear on = one matrix. Audit the matrix quarterly. New tokens get added to the matrix before they ship.
• ▸
  Integrate contrast into your PR template. Add a checkbox: All new/changed color tokens pass contrast audit. This single line catches 80% of regressions because it forces the developer to actually check.
• ▸
  Keep a restricted-tokens list. Some tokens pass only for large text (3:1 to 4.49:1). Document them with a usage constraint: fg-muted: minimum 18px or 14px bold. Never use for body copy. The design system enforces this.
• ▸
  Run automated checks on EVERY page, not just the homepage. In my 25-site audit, 60% of failures were on secondary pages (settings, help docs, empty states) that nobody manually reviewed.