Fixing Colour Contrast Failures

The contrast ratios WCAG sets

Contrast is expressed as a ratio between the relative luminance, roughly the brightness, of two colours. It runs from 1:1, the same colour on itself, to 21:1, black on white. Hue does not enter the calculation, which is why a red and a green of similar brightness can look different to most people and still fail.

WCAG does not allow rounding. A pair measuring 4.48:1 fails 4.5:1, even though it looks nearly identical to a passing pair. Grey #777777 on white is 4.48:1 and fails; #767676 on white is 4.54:1 and passes.

What is exempt

• Text in logos and brand names.
• Text and controls that are disabled and cannot be used.
• Purely decorative text, and text that is part of a photo with other significant visual content, such as a shop sign in a street scene.
• Text that is invisible to everyone.

Placeholder text is not exempt. If it is visible and conveys information, it must meet 4.5:1 like any other text.

The pairs that fail most often

A handful of patterns account for most contrast findings on small business sites. Ratios below are measured on a white background.

The last row is worth noticing: #6b7280 passes on white at 4.83:1 but fails on a near-black background. A colour does not pass or fail on its own; only a pair does.

How to measure contrast yourself

In the browser

In Chrome and Edge, inspect a piece of text, then click the small colour swatch next to its color value in the Styles pane. The colour picker shows the contrast ratio against the background it detects, with pass or fail marks for AA and AAA, and draws lines on the colour area showing where the thresholds fall. Dragging the colour below the line gives you a passing shade immediately. Firefox's Accessibility Inspector can also check contrast for the selected element and scan a page for contrast issues.

With a calculator

Any contrast calculator that follows the WCAG formula will do: enter the foreground and background hex codes. This is useful for brand guidelines and design files before anything is built.

When the background is not a flat colour

Checkers struggle with gradients, background images, semi-transparent overlays and text positioned over other elements. For these, measure against the lightest part of the background behind light text, or the darkest part behind dark text. If the text still passes at its worst point, it passes.

The formula, for developers

// Relative luminance of an sRGB colour, then the WCAG ratio
function lum(hex) {
  const [r, g, b] = [0, 2, 4].map(i => {
    const c = parseInt(hex.slice(i + 1, i + 3), 16) / 255;
    return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
function ratio(a, b) {
  const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
}
ratio('#767676', '#ffffff'); // about 4.54

The fix, step by step

Building a palette that passes by design

The lasting fix is a colour system where every text colour is paired with the backgrounds it may appear on, and each pairing is known to pass. A small set of named variables is enough for most sites:

:root {
  --bg: #ffffff;
  --text: #1f2937;          /* about 14.7:1 on white */
  --text-muted: #6b7280;    /* 4.83:1 on white */
  --brand: #ff6b35;         /* decorative and large text only */
  --brand-strong: #c2410c;  /* buttons with white text, 5.18:1 */
  --border-input: #8a8a8a;  /* 3.45:1 on white */
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #111827;
    --text: #f3f4f6;
    --text-muted: #9ca3af;  /* 6.99:1 on #111827 */
    --border-input: #9ca3af;
  }
}
.btn-primary { background: var(--brand-strong); color: #ffffff; }
input, select, textarea { border: 1px solid var(--border-input); }

Write the approved pairs into your brand guidelines, with their ratios, so designers, developers and agencies all use the same ones. When a new colour is proposed, it is checked against the backgrounds it will sit on before it is used.

Platform notes

WordPress. Block themes define their palette in theme.json and expose it in Appearance, Editor, Styles. Change the palette there and blocks that use palette colours update everywhere. Blocks where an editor picked a custom colour keep that colour, so search for them after changing the palette. The block editor warns when an editor picks a low contrast text and background combination in some blocks; treat that warning seriously. Page builders keep their own global colour settings, which need changing separately.

Shopify. Most current themes use colour schemes set in the theme editor, each with a background, text, button and button label colour. Fix the scheme rather than individual sections. Apps that add announcement bars, pop-ups and review widgets usually have their own colour settings in the app.

Custom and framework sites. Utility frameworks such as Tailwind make it easy to pick grey shades by number; agree which shades are allowed for text on which backgrounds. Automated accessibility tests in your test suite can catch many contrast regressions in components before they ship, though not text over images.

Contrast is not the only visual check

• Do not rely on colour alone. WCAG 1.4.1, Use of Color, at level A, means information shown by colour must also be available another way. Links within paragraphs are usually underlined for this reason, and error fields need an icon or message as well as a red border.
• Text size and weight. Very thin font weights look fainter than their measured ratio suggests. If a light weight reads poorly, use a heavier weight or darker colour even if it technically passes.
• Visitors who change colours. Some people use Windows contrast themes or browser extensions that override colours. Test that your site still works in forced colours mode, particularly icons and focus outlines drawn with backgrounds or shadows.

Focus outlines are covered in more detail in fixing focus indicators. For a broader walk through the checker's findings, see the Accessibility Guide.