How to fix color-contrast issues

Why low contrast fails

Text has to stand out from whatever sits behind it. When the two colours are too close in lightness, people with low vision, colour-vision deficiencies, or simply a cheap monitor in a bright room can't read it. WCAG 2.1 success criterion 1.4.3 (Contrast Minimum, Level AA) turns that intuition into a measurable threshold, which is exactly why automated tools can check it reliably — and why it's the single most common issue our scanner reports.

The numbers you need to hit

Contrast is expressed as a ratio between the text colour and its background, from 1:1 (identical) to 21:1 (pure black on pure white). To pass Level AA:

• Normal text needs a ratio of at least 4.5:1.
• Large text — 24px, or 18.66px (14pt) if bold — needs at least 3:1.
• The same 3:1 minimum applies to meaningful graphics and UI component borders under 1.4.11.

You don't compute this by eye. Any browser's DevTools colour picker shows the ratio, and our report gives you the measured value for each failing element.

A worked fix

Say your buttons use a light grey label on a mid-grey fill. It looks tasteful and fails badly:

/* #9aa0a6 on #c8ccd0 → contrast ratio 1.6:1 — fails AA */
.button {
  background: #c8ccd0;
  color: #9aa0a6;
}

The cheapest fix is almost always to darken the text rather than redesign the component. Push the label toward the ink end until the ratio clears 4.5:1:

/* #1f2328 on #c8ccd0 → contrast ratio 9.1:1 — passes AA */
.button {
  background: #c8ccd0;
  color: #1f2328;
}

The traps people fall into

Contrast bugs cluster in a few predictable places. Placeholder text and disabled states are often deliberately faint — placeholders still need to pass if they convey information, so don't rely on them as labels. Text over images changes contrast pixel by pixel; add a solid or gradient scrim behind it rather than hoping the photo stays dark. Brand colours are frequent offenders: a logo colour that works as a big shape rarely works as 14px body text, so keep a darker "text" variant of each brand colour in your design tokens. Finally, watch hover and focus states — a link that passes at rest can fail once it lightens on hover.

How our scanner detects it

For every text node, we read the computed foreground colour and walk up the DOM to find the effective background, then calculate the WCAG contrast ratio and compare it against the 4.5:1 / 3:1 threshold for that element's size and weight. Where the background is an image or a gradient we can't resolve to a single colour, we don't guess — we flag the element for manual review instead of passing or failing it. That's the honest-coverage principle in action: a number when we're sure, a human check when we're not.