Background and foreground colors do not have sufficient contrast: how to fix it

Quick answer: This audit fails when text contrast is too low. WCAG AA requires a 4.5:1 contrast ratio for normal body text and 3:1 for large text and UI components. Fix it by checking color pairs in DevTools or the WebAIM checker and adjusting colors until the ratio passes.

This Lighthouse audit fails when text or interactive elements don't meet WCAG color contrast requirements. About 1 in 12 men and 1 in 200 women have some form of color vision deficiency, and everyone reads better when contrast is high.

TL;DR

• What: Text doesn't meet WCAG AA contrast ratio (4.5:1 for normal text, 3:1 for large/UI text).
• Why it matters: Low contrast is unreadable for users with low vision and harder for everyone in bright sunlight or on low-quality displays.
• Fix: Darken text or lighten backgrounds until the ratio passes. Use a contrast checker.

What does the color-contrast audit check?

Lighthouse computes the contrast ratio between every text element and its computed background. Ratios are based on WCAG 2.1's algorithm (luminance contrast).

What are common color-contrast offenders?

1. Light gray text (#999, #aaa) on white backgrounds
2. Placeholder text in form fields
3. Disabled buttons still showing readable-looking labels
4. White text on light backgrounds (often in image overlays)
5. Brand-colored text when the brand color is mid-saturation

How do I fix color contrast?

1. Run your colors through a checker

• WebAIM Contrast Checker
• Chrome DevTools → Elements → Styles → click any color swatch → AA/AAA indicators

2. Common before/after pairs

/* WRONG: 2.85:1, fails AA */
.muted { color: #999999; background: #ffffff; }

/* RIGHT: 4.54:1, passes AA */
.muted { color: #767676; background: #ffffff; }

/* WRONG: placeholder is invisible */
input::placeholder { color: #cccccc; }

/* RIGHT */
input::placeholder { color: #6b7280; }

3. Build a tonal palette that hits ratios

Modern design systems (Tailwind, Radix Colors, OKLCH-based palettes) provide named colors at consistent perceptual lightness. Use a "step 600" or "step 700" of a hue for body text on a light background, those steps are tuned to hit 4.5:1+.

4. Don't rely on color alone

If your only way to indicate "error" is red text, color-blind users miss the signal. Pair color with an icon, label, or shape.

<!-- WRONG: only color conveys the error -->
<p style="color: red">Password is too short</p>

<!-- RIGHT: icon + color + label -->
<p class="error">
  <svg aria-hidden="true">...</svg>
  Error: Password is too short
</p>

What color-contrast pitfalls should I avoid?

• Don't trust your eyes, what looks "fine" on your high-end retina screen can be unreadable in sunlight or on a budget laptop. Use the checker.
• Don't fix only the failing audit, Lighthouse samples a few elements; check the whole design system.
• Don't break brand consistency carelessly, if a brand color fails contrast, pair it with white text on the brand bg (or darken the brand for text-only use). Talk to design.

How do I verify color contrast passes?

1. Re-run Lighthouse.
2. Use the axe DevTools extension, it'll list every contrast failure with the exact ratios.
3. Test in grayscale (DevTools → Rendering → Emulate vision deficiencies → "Achromatopsia") to ensure information isn't conveyed by color alone.

Related audits

• Image alt attributes, non-visual content for users with low vision
• Document does not have a main landmark, assistive tech navigation
• Heading order, document outline

Audit your URL at https://lighthouse-md.com.