Low-contrast text affects approximately 300 million people with color vision deficiencies and countless others reading in bright sunlight or on older displays.

What's Happening

Lighthouse flags text where the contrast ratio between foreground and background colors doesn't meet WCAG 2 AA thresholds. Normal text requires a ratio of 4.5:1, while large text (18pt or 14pt bold) needs 3:1. This audit uses axe-core to calculate the luminance difference between your text and its background.

Diagnose

1. Open DevTools and run Lighthouse accessibility audit
2. Expand "Background and foreground colors do not have a sufficient contrast ratio"
3. Click any flagged element to highlight it in the DOM
4. Use the Elements panel to inspect the computed color and background-color
5. In DevTools, click the color swatch next to any color value to open the color picker, which shows the current contrast ratio

Fix

1. Adjust Text Color

Darken light text or lighten dark text until you reach the required ratio.

/* Before: 2.5:1 ratio - fails */
.subtitle {
  color: #999999;
  background: #ffffff;
}

/* After: 4.6:1 ratio - passes */
.subtitle {
  color: #767676;
  background: #ffffff;
}

2. Adjust Background Color

Sometimes changing the background is more practical than changing text.

/* Before: fails on white background */
.highlight {
  color: #ffc107;
  background: #ffffff;
}

/* After: passes with darker background */
.highlight {
  color: #ffc107;
  background: #1a1a1a;
}

3. Use CSS Custom Properties

Create accessible color scales that guarantee contrast.

:root {
  --text-primary: #1f2937;    /* 12.6:1 on white */
  --text-secondary: #4b5563;  /* 7.5:1 on white */
  --text-muted: #6b7280;      /* 5.0:1 on white */
}

.card {
  color: var(--text-secondary);
  background: #ffffff;
}

Framework Examples

export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      neutral: 'slate'
    }
  }
})

Verify the Fix

1. Re-run Lighthouse and confirm the audit passes
2. Test with the DevTools color picker - it shows a checkmark when contrast is sufficient
3. Use browser extensions like axe DevTools for real-time contrast checking
4. Test in different lighting conditions on various devices

Common Mistakes

• Using placeholder text colors for real content — Placeholder styling (#aaa) is intentionally low contrast; don't apply it to actual content
• Ignoring text over images — Text on image backgrounds often fails; add a semi-transparent overlay or text shadow
• Fixing only the hover state — Both default and hover states must pass contrast requirements
• Relying solely on color to convey meaning — Users with color blindness need additional indicators like icons or underlines

Related Issues

Color contrast issues often appear alongside:

• Meta Viewport — Both affect users with vision impairments
• Target Size — Small, low-contrast buttons are doubly hard to use
• Link Name — Low-contrast links are even harder to identify as clickable

Test Your Entire Site

Color contrast issues often hide in footers, captions, and secondary content that gets overlooked during manual review. Unlighthouse scans every page of your site automatically, catching contrast failures across your entire domain so nothing slips through to production.

Related

• All Accessibility Issues
• Accessibility Overview