WCAG Contrast Checker Tool

Real-World Examples

Testing & Standards

Automated contrast audit — token matrix plus semi-transparent compositing

// Automated contrast audit — paste your tokens and get a full report
const textTokens = {
  'fg.default': '#1F2937',
  'fg.muted': '#6B7280',
  'fg.link': '#2563EB',
  'fg.error': '#B91C1C',
  'fg.success': '#047857',
  'fg.placeholder': '#9CA3AF',
};

const surfaceTokens = {
  'bg.white': '#FFFFFF',
  'bg.gray50': '#F9FAFB',
  'bg.card': '#F3F4F6',
  'bg.dark': '#111827',
};

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

function contrast(hex1, hex2) {
  const [l1, l2] = [luminance(hex1), luminance(hex2)];
  return ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05));
}

// Run the full matrix
console.table(
  Object.entries(textTokens).flatMap(([textName, textHex]) =>
    Object.entries(surfaceTokens).map(([bgName, bgHex]) => ({
      text: textName,
      surface: bgName,
      ratio: contrast(textHex, bgHex).toFixed(2),
      pass: contrast(textHex, bgHex) >= 4.5 ? 'AA ✓' : 'FAIL ✗',
    }))
  )
);

// --- The part most tools skip: composite alpha layers first ---
const toRgb = (hex) => hex.replace('#', '').match(/../g).map(c => parseInt(c, 16));
const toHex = (n) => Math.round(n).toString(16).padStart(2, '0');

// result = overlay * alpha + backdrop * (1 - alpha), per channel
function composite(overlay, alpha, backdrop) {
  const o = toRgb(overlay), b = toRgb(backdrop);
  return '#' + o.map((c, i) => toHex(c * alpha + b[i] * (1 - alpha))).join('');
}

// Audit every scrim / tooltip / glass panel against its REAL backdrop
const alphaLayers = [
  { name: 'hero scrim 40%',   text: '#FFFFFF', overlay: '#000000', alpha: 0.40, backdrop: '#E5E7EB' },
  { name: 'hero scrim 60%',   text: '#FFFFFF', overlay: '#000000', alpha: 0.60, backdrop: '#E5E7EB' },
  { name: 'tooltip 70%',      text: '#FFFFFF', overlay: '#111827', alpha: 0.70, backdrop: '#FFFFFF' },
  { name: 'glass card 60%',   text: '#374151', overlay: '#FFFFFF', alpha: 0.60, backdrop: '#3B82F6' },
  { name: 'dark glass muted', text: '#6B7280', overlay: '#FFFFFF', alpha: 0.50, backdrop: '#111827' },
];

console.table(alphaLayers.map(l => {
  const effective = composite(l.overlay, l.alpha, l.backdrop);
  const real = contrast(l.text, effective);
  return {
    layer: l.name,
    compositedBg: effective.toUpperCase(),
    declared: contrast(l.text, l.overlay).toFixed(2), // what naive tools report
    real: real.toFixed(2),
    pass: real >= 4.5 ? 'AA ✓' : 'FAIL ✗',
  };
}));

Copy and paste into your project — free to use.

Pro Tips

• ▸
  Never trust a single tool. Run your tokens through at least 2 methods: one automated (axe-core in CI) and one manual (Contrast Checker with your actual hex values). Automated tools miss semi-transparent layers and forced states.
• ▸
  Test on the worst screen, not the best. Your MacBook Pro has wide gamut and perfect backlight uniformity. Your users have 6-year-old ThinkPads with TN panels in fluorescent-lit offices. If contrast looks tight on your good screen, it fails on their bad one.
• ▸
  Build a 'danger token' list. In every design system, 2–3 tokens sit right at the AA boundary (4.5:1 to 5:1). Flag these in your documentation so no one uses them below 16px or on tinted surfaces without re-checking.
• ▸
  Schedule quarterly audits. Contrast regresses silently: a designer tweaks a gray, an engineer swaps a surface token, a brand refresh lightens the palette. Put a recurring calendar event to re-run the 28-pair matrix.
• ▸
  Check adjacent color for links. WCAG SC 1.4.1 says links that are not underlined must have 3:1 contrast against surrounding body text — not just against the background. This catches blue links in dark-gray body copy that pass background contrast but fail adjacent-text contrast.