How to fix low-contrast colors without replacing your palette

A failed contrast check does not mean your favorite color is unusable. It means that specific foreground, background, and intended text size need another decision.

Reviewed 7 October 2026 · 4 min read

1. Identify the actual pair

Write down the foreground and the surface directly behind it. A button label is checked against the button fill, not the page. Text in a card is checked against the card surface. If the background contains an image, gradient, or transparency, one solid-color check is not enough.

For normal text, the WCAG AA threshold is 4.5:1. Large text has a 3:1 threshold, with the size definition described in our methodology. Do not increase the displayed result by rounding: values below the threshold fail. W3C’s contrast-minimum guidance is the source for those rules.

2. Try a role change before a color change

A light accent that fails as text on a light page may work as a background for a dark label. In Cobalt & citrus, the accent #D5EC59 against the page #F5F6F0 is 1.21:1. Black text on that accent is 15.97:1.

You have kept the original accent and changed its job. This is often the most direct way to preserve a visual direction without forcing a pale brand color to serve as the main reading color.

3. Test the label color

White is a common button-label choice, but it does not always pass. On medium gray #777777, white scores 4.48:1 while black scores 4.69:1. Check both candidates rather than choosing by habit.

The studio derives black or white labels for its primary and accent fills, based on whichever produces the higher ratio. For body text, it preserves your chosen color until you explicitly ask for an adjustment.

4. Review a repair against every intended surface

In the studio, choose “Review contrast repairs.” It proposes changes across both themes while holding your page and surface colors, original brand, and any locked roles. The review names each changed role and shows its old and new hex values. Apply the proposal only when the tradeoff fits your design; one undo restores the whole previous project.

The search tests 1,001 lightness positions in OKLCH, reduces chroma for out-of-gamut candidates, rounds to an actual 8-bit sRGB hex, and rechecks the contrast. Among passing candidates it selects the smallest Euclidean Oklab distance in that sampled search. This is not the globally closest possible color, nor a guarantee that hue stays numerically identical after rounding and gamut mapping. Oklab’s author explains the color space.

Text, secondary text and links are checked on both page and surface, at the selected 4.5:1 or 7:1 target. Borders and offset focus rings use 3:1. Black or white labels are checked on both default and hover button fills. A valid role stays unchanged.

Some constraints conflict: a single text color cannot reach 7:1 on both pure black and pure white. If your chosen surfaces or locks prevent a repair, the review lists the remaining failures. Change the surfaces, unlock a role, or use separate foreground roles in your real design. The tool does not silently move a locked color or claim an unresolved pair passes.

5. Check meaning and states

Readable words are only one part of the problem. If a warning is communicated only with orange, add a clear message. If two chart series differ only by color, consider labels, patterns, or line styles. If a focus outline disappears into the page, give it a distinct treatment and check the applicable adjacent colors.

W3C’s use-of-color guidance and non-text contrast guidance cover these separate concerns. Passing the studio matrix does not establish that a chart is safe for every form of color-vision difference.

6. Export, then inspect the real interface

Copy the paired-theme CSS or Tailwind v4 tokens, save an editable project JSON, or export the contrast report. Confirm the actual site uses those values in the expected places, including hover and selected states. If your stylesheet adds opacity, overlays, or blending, the exported solid-color result no longer describes the final rendered pair.

Keep a small record of the pairs you intend to use. The palette detail pages do this for the original combinations; your customized studio export supplies role names so those decisions remain easier to follow.

Our examples use original palette values and the WCAG 2.2 calculation. Full methodology and primary sources.