How to fix color contrast issues

WCAG 2.2 success criterion 1.4.3 Contrast (Minimum) sets the AA bar:

• 4.5:1 for normal text against its background.
• 3:1 for large text (≥ 24px, or ≥ 18.66px bold).
• 3:1 for meaningful graphics and UI component boundaries (1.4.11).

The ratio compares the relative luminance of the text colour and the colour directly behind it.

Run the free scan above. Every element that fails contrast is outlined and reported with its measured ratio and the colours involved. Watch especially for: muted "secondary" text, placeholder text, link colours on coloured backgrounds, sale/notification badges, and disabled-looking buttons that are actually active.

The same scan often flags skipped heading levels as well. Unlike contrast, those are a best-practice warning rather than a WCAG failure, so fix contrast first.

This is not a failure and not a pass. It is axe reporting that it could not measure the element at all, so the result is incomplete and a human has to decide. You will see it with a reason attached:

• "due to a background gradient" — the text sits on a gradient, so the contrast changes across the element.
• "due to a background image" — the backdrop is a photo, and the pixels under the text are unknown to a static check.
• "because it is overlapped by another element" — something is painted on top, commonly a scrim over a hero image.
• "because of alpha transparency" — a translucent colour that has to be composited over whatever is beneath it.
• "due to a pseudo element" — the backdrop comes from ::before or ::after.

Most tools stop here and leave you a list to check by hand, which is why a big site can finish a scan with hundreds of unresolved contrast items and no idea which ones are real.

The measurement that matters is the worst case, not the average. Text legible over the pale end of a gradient and invisible over the dark end is a real failure, so sample the least favourable point rather than a midpoint.

• Gradients: test every colour stop and the stretches between them. A blend of two colours can be darker than either end, so dark text can pass at each stop and still fail part of the way across.
• Background images: sample the actual pixels beneath the text. A photo that is bright in one corner and dark in another can pass and fail within one heading.
• Overlays: composite the translucent layer over what is behind it first, then measure. A 60% black scrim over a light photo gives a very different number from the scrim alone.

Our scanner does the first three automatically and reports a real pass or fail instead of leaving them incomplete. Where it cannot be sure, it says so rather than guessing: cross-origin images that cannot be read back, backgrounds fixed to the viewport, pseudo-element backdrops, and overlays painted by an element that is not an ancestor of the text. An unresolved item always stays "needs review" and is never counted as a pass, because a false pass is exactly the fake-compliance badge this tool exists to argue against.

To check a single gradient or photo by hand, paste the CSS or load the image into the image and gradient contrast checker. It runs in your browser and shows the lowest-contrast point.

• Darken the text or lighten the background until it clears 4.5:1. A contrast checker tells you the exact ratio.
• Don't rely on colour alone for links. Keep underlines, or give links a 3:1 difference from body text plus a non-colour cue on hover and focus.
• Fix it in CSS or your theme settings, not with an overlay widget. Overlays can't reliably correct contrast and don't make you compliant.
• Re-scan after changes to confirm the ratio now passes.