Contrast Checker Guide

workflow

The Precision Cliff: Why "4.5:1" On Your Screen Can Still Be A Failure

Testing & Standards

Contrast matrix auditor — 4-decimal precision, alpha compositing, and a ship-floor margin

// Contrast matrix auditor — run against your design system tokens
// Checks every foreground token against every surface it could appear on.
//
// Three things this does that most checkers do not:
//   1. Compares at full float precision, never a rounded display value
//   2. Composites alpha tokens before measuring them
//   3. Enforces a ship floor above the raw WCAG threshold

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[]) {
  // WCAG requires "at least" the threshold and does not round. A one-decimal
  // readout hides up to 0.05 of error, so #777777 on white (4.4781:1) displays
  // as 4.5 and fails. MARGIN pushes the accept line clear of that ambiguity.
  const AA = 4.5, AA_LARGE = 3, AAA = 7, MARGIN = 0.1;
  const results: { pair: string; ratio: string; aa: string; aaa: string; ship: string; fix?: string }[] = [];

  for (const text of texts) {
    for (const surface of surfaces) {
      const ratio = contrastRatio(text.hex, surface.hex);
      // Compare the raw float. Never compare a toFixed() string.
      const aa = ratio >= AA ? 'PASS' : ratio >= AA_LARGE ? 'LARGE ONLY' : 'FAIL';
      const aaa = ratio >= AAA ? 'PASS' : 'FAIL';
      const ship = ratio >= AA + MARGIN ? 'OK' : ratio >= AA ? 'TOO CLOSE' : 'BLOCK';
      const fix = ratio < AA + MARGIN
        ? `Darken ${text.name} or lighten ${surface.name} — need ${(AA + MARGIN - ratio).toFixed(4)} more ratio`
        : undefined;
      results.push({
        pair: `${text.name} on ${surface.name}`,
        ratio: ratio.toFixed(4) + ':1',   // 4 decimals, not 2
        aa, aaa, ship, fix
      });
    }
  }

  const blocked = results.filter(r => r.ship === 'BLOCK');
  const tooClose = results.filter(r => r.ship === 'TOO CLOSE');

  console.table(results.filter(r => r.ship !== 'OK'));
  console.log(`\n${results.filter(r => r.aa === 'PASS').length}/${results.length} pairs pass raw AA`);
  console.log(`${blocked.length} pairs FAIL — fix before shipping`);
  console.log(`${tooClose.length} pairs pass but sit inside ${MARGIN} of the line — these are the ones a rounded display will lie about\n`);
  return results;
}

// --- Alpha tokens must be composited before measuring ---
// Ant Design ships colorTextDescription as rgba(0,0,0,0.45). Measured as its
// declared #000000 it reports 21:1. Composited on white it is #8C8C8C = 3.36:1,
// a clear SC 1.4.3 failure for description text.
function composite(overlayHex: string, alpha: number, backdropHex: string): string {
  const o = hexToRgb(overlayHex);
  const b = hexToRgb(backdropHex);
  const mix = o.map((c, i) => Math.round(c * alpha + b[i] * (1 - alpha)));
  return '#' + mix.map(c => c.toString(16).padStart(2, '0')).join('').toUpperCase();
}

const alphaTokens = [
  { name: 'antd colorTextDescription', overlay: '#000000', alpha: 0.45, on: '#FFFFFF' },
  { name: 'antd colorTextDescription', overlay: '#000000', alpha: 0.45, on: '#F9FAFB' },
];

console.table(alphaTokens.map(t => {
  const effective = composite(t.overlay, t.alpha, t.on);
  const real = contrastRatio(effective, t.on);
  return {
    token: t.name,
    surface: t.on,
    composited: effective,
    declaredReports: contrastRatio(t.overlay, t.on).toFixed(2) + ':1',
    realRatio: real.toFixed(4) + ':1',
    verdict: real >= 4.5 ? 'AA pass' : 'AA FAIL',
  };
}));

// 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 24px, or 18.66px bold. Never use for body copy. WCAG defines large text in points (18pt/14pt bold), which is 24px/18.66px in CSS — not 18px/14px, a misreading that hands the relaxed ratio to sizes needing 4.5:1. 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.
• ▸
  Never accept a displayed 4.5 as a pass. One decimal place hides up to 0.05 of error, and WCAG does not round. #777777 on white reads 4.5 and is really 4.4781:1 — a failure. Set your team's shipping floor at 4.60:1 so the display can never mislead you.
• ▸
  Compute alpha tokens before you measure them. Ant Design ships description text as rgba(0,0,0,0.45), which composites to #8C8C8C on white and scores 3.36:1 — a clear AA failure. Any tool reading the declared #000000 reports 21:1. Flatten first, measure second.
• ▸
  Audit tokens per surface, never in isolation. Tailwind gray-500 passes on white (4.83:1) and fails on gray-100 (4.39:1). 'Is this token accessible?' has no answer without naming the background. Use gray-600 (#4B5563) as the muted default; it clears 4.5:1 on all eight common light surfaces.
• ▸
  Re-audit after any surface change, not just text changes. Bootstrap's $primary passes on white by 0.001 (4.5014:1). Move that link onto bg-light and it fails. Lightening a text token is obvious; tinting a panel is the change that breaks compliance silently.