WCAG Contrast Checker for Buttons

Real-World Examples

Testing & Standards

Button state contrast auditor — test all states in one pass

/**
 * Button Accessibility Auditor
 * Tests label, boundary, and focus ring contrast for all button states.
 * Run in browser console or Node.js.
 */

function sRGBtoLinear(c: number): number {
  const v = c / 255;
  return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
}

function relativeLuminance(hex: string): number {
  const rgb = hex.replace('#', '').match(/.{2}/g)!.map(h => parseInt(h, 16));
  return 0.2126 * sRGBtoLinear(rgb[0]) + 0.7152 * sRGBtoLinear(rgb[1]) + 0.0722 * sRGBtoLinear(rgb[2]);
}

function contrastRatio(hex1: string, hex2: string): number {
  const l1 = relativeLuminance(hex1);
  const l2 = relativeLuminance(hex2);
  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
}

interface ButtonState {
  name: string;
  fill: string;
  label: string;
  surface: string;
  ring?: string;
}

interface AuditResult {
  state: string;
  labelRatio: string;
  labelPass: boolean;
  boundaryRatio: string;
  boundaryPass: boolean;
  ringRatio: string | null;
  ringPass: boolean | null;
  overall: 'PASS' | 'FAIL';
}

function auditButton(states: ButtonState[]): AuditResult[] {
  return states.map(s => {
    const labelR = contrastRatio(s.label, s.fill);
    const boundaryR = contrastRatio(s.fill, s.surface);
    const ringR = s.ring ? contrastRatio(s.ring, s.surface) : null;

    const labelPass = labelR >= 4.5;
    const boundaryPass = boundaryR >= 3.0;
    const ringPass = ringR !== null ? ringR >= 3.0 : null;

    return {
      state: s.name,
      labelRatio: labelR.toFixed(2) + ':1',
      labelPass,
      boundaryRatio: boundaryR.toFixed(2) + ':1',
      boundaryPass,
      ringRatio: ringR ? ringR.toFixed(2) + ':1' : null,
      ringPass,
      overall: labelPass && boundaryPass && (ringPass !== false) ? 'PASS' : 'FAIL',
    };
  });
}

// Example: audit a primary button through all states
const primaryButton: ButtonState[] = [
  { name: 'default',  fill: '#2563EB', label: '#FFFFFF', surface: '#FFFFFF', ring: '#93C5FD' },
  { name: 'hover',    fill: '#1D4ED8', label: '#FFFFFF', surface: '#FFFFFF', ring: '#93C5FD' },
  { name: 'active',   fill: '#1E40AF', label: '#FFFFFF', surface: '#FFFFFF' },
  { name: 'focus',    fill: '#2563EB', label: '#FFFFFF', surface: '#FFFFFF', ring: '#1D4ED8' },
  { name: 'disabled', fill: '#BFDBFE', label: '#6B7280', surface: '#FFFFFF' },
];

console.table(auditButton(primaryButton));

Copy and paste into your project — free to use.

Pro Tips

• ▸Test all six states independently: default, hover, active, focus, disabled, and loading. A single passing screenshot of the default state proves nothing about the component's accessibility.
• ▸Hover should darken the fill, never lighten it. If your designer insists on a lighter hover, switch to darkening the label or adding an inner shadow instead of changing the fill lightness.
• ▸Do not use opacity as your only disabled treatment. Add text that explains why the action is unavailable. Screen readers need the explanation; sighted users need it too.
• ▸For outline/ghost buttons, check the border against the surface (≥3:1) AND the label against the surface (≥4.5:1). The fill is transparent so it does no contrast work.
• ▸Focus rings should be a different hue from the button fill. Same-hue rings at reduced opacity almost always fail. A 2px solid ring in a complementary dark color is the safest pattern.
• ▸Keep danger/warning fills darker than designers prefer. Bright red (#EF4444) fails with white text. Use #B91C1C or darker — it looks more serious AND passes contrast.
• ▸Pre-ship button accessibility checklist: (1) Label ≥4.5:1 on default fill (2) Label ≥4.5:1 on hover fill (3) Fill ≥3:1 vs surface in all states (4) Focus ring ≥3:1 vs surface with ≥2px area (5) Disabled state never used for required info (6) Loading state has aria-label (7) All states tested on both light and dark surfaces (8) Outline variants: border ≥3:1 vs surface (9) Tested in Chrome CVD simulator (10) Keyboard-tabbed through the full flow.
• ▸For design token enforcement: define button.fill.primary, button.on-fill.primary, and button.ring.primary as linked tokens. CI should reject any PR where the trio fails the 3-check rule. See [Accessible Color Token System](/accessible-color-token-system/) for implementation patterns.

Developer Perspective