How to Fix a Failing Color Contrast Pair

Choose what must stay fixed

A contrast failure does not tell you which design decision to change. A brand-colored button may need to keep its fill, while its label can change. A shared text token may need to stay consistent while a card surface changes. Set that constraint before trying new values so a local fix does not silently alter every component that uses the same token.

In the contrast checker, “Color to adjust” identifies the side that may change. Foreground means text; background means the color directly behind it. The other input stays fixed when you apply a suggestion. Swapping the inputs preserves the ratio but changes which role you are editing.

Open the checker and compare passing adjustments →

Pick the target for the content

A target of 3:1 is not enough for a normal-sized button label. The large-text decision depends on the lettering, not the size of the button around it. Likewise, selecting 7:1 addresses a color ratio; it does not certify the component or page against every WCAG requirement.

Work through gray on white

Start with foreground #777777 and background #FFFFFF. The unrounded ratio is approximately 4.478089, which fails 4.5:1. Keep the background fixed and choose the 4.5:1 target. Mixing the foreground toward black produces #767676 as the first passing sampled value; its ratio is approximately 4.542225. Apply it and check that the background still reads #FFFFFF.

.body-copy {
  color: #767676;
  background-color: #FFFFFF;
}

The ratio shown to two decimals is a reading aid. A pair such as #81737A on white displays 4.50:1 but its unrounded result is below 4.5. The checker evaluates each candidate after rounding its RGB channels to bytes, then compares the full ratio with the target. Copy the resulting hex rather than a rounded intermediate HSL value.

Understand the suggestions

The adjustment search samples 255 equal mix steps toward black and 255 toward white in gamma-encoded sRGB. It returns the first passing quantized sample on each feasible path. A darker and a lighter option can both work; compare them in your design. These are bounded mixing suggestions, not the nearest colors in a perceptual color space, and they can change hue or saturation.

If the current pair already passes the selected target, no change is suggested. With a middle-luminance fixed color, 7:1 can be impossible in either direction: neither black nor white reaches it, so no opaque sRGB color can. For example, fixing #777777 gives only about 4.69:1 with black and 4.48:1 with white. Change the fixed color or reconsider the chosen target instead of endlessly nudging the other side.

Review the result in context

1. Apply one suggestion and inspect the actual text at its intended size and weight. Aim above the minimum when your design allows it.
2. Recheck every surface that shares the adjusted token, including hover, focus and responsive layouts.
3. Use the palette matrix when the same text appears on several flat backgrounds.
4. For gradients, images or transparency, obtain the final rendered adjacent colors and test the least contrasting area separately. The inputs here are opaque flat colors.

Check button text, boundaries and focus separately →