Color Contrast and Accessibility: A Practical WCAG Guide for Developers

Understand WCAG AA and AAA contrast requirements, how to test your palette, tools that catch failures, and common accessible colour combinations that still look great.

Accessibility is often treated as an afterthought. Color contrast is the number one WCAG failure on the web. The good news: with the right habits, it takes almost no extra effort.

Contrast ratio compares the relative luminance of two colours. 1:1 = identical. 21:1 = black on white (maximum).

WCAG AA is the legal minimum in most jurisdictions. AAA is aspirational for body text.

• Grey placeholder text on white backgrounds. color: #aaaaaa fails at 2.3:1. Use #767676 minimum.
• Brand colours on white. Many brand oranges, yellows and light greens fail. Always check.
• Disabled button text. The spec doesn't require contrast for disabled elements, but users still need to read them.
• Text over images or gradients. The contrast must pass at the worst point — usually the lightest part of the gradient.

Design your colour scale so that every level has a clearly passing contrast with either your darkest or lightest neutral:

/* Use CSS relative colour syntax to auto-calculate accessible pairs */
:root {
  --brand: hsl(38, 92%, 45%);
  /* Light version that passes 4.5:1 on dark bg */
  --brand-accessible-light: hsl(38, 90%, 70%);
  /* Dark version that passes 4.5:1 on light bg */
  --brand-accessible-dark: hsl(38, 90%, 25%);
}

Test with our Color Picker which includes a live contrast ratio display.