Color Contrast Testing — Complete Guide

In this tutorial, you will learn about Color Contrast Testing. We cover key concepts, practical examples, and best practices to help you master this topic.

Color contrast testing involves measuring the contrast ratio between foreground text and background colors against WCAG thresholds (4.5:1 for AA normal text, 3:1 for large text) using tools like Colour Contrast Analyser and contrast checking APIs.

What You'll Learn

You will measure contrast ratios, use contrast checking tools, test non-text elements like icons and focus indicators, and verify designs meet WCAG AA and AAA contrast requirements.

Why It Matters

Insufficient contrast is the most common Accessibility issue on the web. If users cannot read your text, they cannot use your site. Legal complaints frequently cite contrast failures as a primary violation.

Real-World Use

A designer specifies light gray text (#999) on a white background for secondary labels. The contrast ratio is 2.8:1, failing WCAG AA. A contrast test catches this before the design is implemented, saving development rework.

Contrast Testing Flow

flowchart TD
  A[Select Foreground] --> B[Select Background]
  B --> C[Calculate Ratio]
  C --> D{4.5:1 for AA?}
  D -->|Yes| E{Large Text?}
  E -->|Yes| F{3:1 for AA?}
  E -->|No| G[Pass AA]
  D -->|No| H[Fail AA]
  F -->|Yes| G
  F -->|No| H
  G --> I{7:1 for AAA?}
  I -->|Yes| J[Pass AAA]
  I -->|No| K[Pass AA only]

Testing Contrast

Use a contrast checking tool to measure ratios. Enter hex values for foreground and background colors.

<!-- Contrast test candidate -->
<p style="color: #666; background: #f5f5f5;">
  This text has a contrast ratio of approximately 3.7:1 -- fails AA.
</p>
<p style="color: #333; background: #f5f5f5;">
  This text has a contrast ratio of approximately 8.6:1 -- passes AAA.
</p>

/* Testing with CSS custom properties */
:root {
  --text-primary: #1a1a1a;
  --bg-primary: #ffffff;
  /* Check: contrast ratio ~15:1, passes AAA */

  --text-secondary: #666666;
  /* Check: contrast ratio against white ~4.6:1, passes AA */
}

// Programmatic contrast checking
function getContrastRatio(hex1, hex2) {
  const l1 = getRelativeLuminance(hex1);
  const l2 = getRelativeLuminance(hex2);
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);
  return (lighter + 0.05) / (darker + 0.05);
}

function getRelativeLuminance(hex) {
  const rgb = hexToRgb(hex);
  const vals = rgb.map(c => {
    const s = c / 255;
    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * vals[0] + 0.7152 * vals[1] + 0.0722 * vals[2];
}

console.log(getContrastRatio('#333', '#fff')); // ~12.6:1

Common Mistakes

• Testing only text contrast, ignoring non-text elements
• Using color picker values without accounting for opacity
• Testing only the default state, not hover/focus/active states
• Forgetting that gradients and images affect perceived contrast
• Assuming high contrast equals good accessibility
• Not testing placeholder text separately
• Ignoring contrast requirements for focus indicators

Practice and Challenge

Practice 1: Use Colour Contrast Analyser to test five color pairs on your site. Practice 2: Find a failing contrast pair and suggest an alternative color. Practice 3: Test a focus indicator color against its potential backgrounds. Practice 4: Check contrast for non-text elements like icons and borders. Practice 5: Test the same colors at different sizes (normal vs large text).

Challenge: Create a color palette with 10 color pairs that all pass WCAG AA for normal text. For each pair, document the exact hex values and contrast ratio. Also note which pairs pass AAA.

FAQ

Mini Project

Build a contrast testing script that accepts a CSS file, parses all color declarations, computes contrast ratios against a specified background, and outputs a report of all pairs that fail WCAG AA and AAA thresholds.

What's Next

Zoom Testing covers testing pages at 200 percent zoom and with browser zoom tools.