Color & design

Test Color Contrast Before and After a UI Change

Create repeatable contrast fixtures, test state changes and shared tokens, verify the delivered fix, and keep manual checks alongside automated results.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Turn a contrast finding into a repeatable test

A contrast test should make it possible to detect whether a known problem returns. Start with the original component, its state, the two final colors and the applicable threshold. Record the failure before changing the design. Without that baseline, a later pass may concern a different state or a different element rather than the issue the change was intended to repair.

Use both a numerical fixture and an implemented-component check. The fixture verifies the color calculation; the component check verifies that the delivered page actually uses those colors. A token test can pass while a more specific CSS rule overrides the text color. Conversely, a temporary developer-tools edit can look correct without changing the source that users receive.

Create a failing and passing button-label pair

Consider ordinary-sized white text on a button with background #0284c7. In the local checker, #ffffff against #0284c7 is about 4.10:1 and fails ordinary-text AA. Changing the background to #0369a1 raises the ratio to about 5.93:1 and passes. Keep both fixtures so a check proves it can distinguish a failure from a pass.

The tool updates its ratio when either color changes and evaluates the unrounded result against its thresholds. After changing a control, confirm the output corresponds to the new pair; an unchanged stale result is not evidence about the new colors. Record the actual values with the result rather than relying only on the visual preview, which can make nearby shades difficult to distinguish.

Verify the source and the rendered state

Apply the passing background through the intended component token or stylesheet rule. Reload the page and inspect the computed foreground and background of the real button. Confirm that a hover or focus selector does not restore the old failing color. If a disabled variant exists, keep its behavior and classification separate from active states rather than using one screenshot for all variants.

Test the button at its smallest supported text size. A layout change that turns a large label into ordinary text changes the threshold even if the colors stay identical. Include a long translated or user-generated label where that content is supported, because wrapping can reveal an overlay or background relationship not visible in a short demonstration label.

Track every component affected by a shared token

A shared color repair can improve one page while changing dozens of other components. Maintain a list of permitted foreground-on-surface combinations for the token. If the button fill also appears behind an icon or selected tab, review those uses under their actual roles. A token name is an implementation convenience, not evidence that every use has the same contrast requirement.

For separate light and dark themes, store and test both relationships. Do not assume an ordinary-text color that passes on white will also pass on a dark surface. State-specific combinations belong in the same record so that a later theme change does not silently introduce an untested hover, error or selected-state pair.

Use automated checks with explicit limits

An automated test can assert a ratio for known colors or inspect a rendered page with an accessibility engine. It still needs a correct model of the background and text role. Gradients, photographs, blending and complex overlays can require manual review. Track those cases as unresolved or separately verified instead of treating “no automated issue reported” as a universal pass.

Preserve full precision for threshold comparisons. A computed value of 4.499 does not satisfy a 4.5 requirement even if a display rounds it to 4.50. Use a comfortably passing replacement when the design allows it, and name the contrast algorithm in the test. Different perceptual models do not share interchangeable numerical thresholds.

Check meaning, focus and practical readability

Use the keyboard through the repaired component and inspect its focus indication. A passing label ratio does not prove that the focus ring is visible against the surrounding surfaces. Confirm that errors, selections and status changes have cues beyond hue alone. Read the actual text at its intended size, especially if a thin typeface makes the component look fainter than its source colors suggest.

Keep a concise before-and-after record: original pair and failure, source change, new pair and pass, component states reviewed and remaining manual cases. The W3C text-contrast explanation and Chrome’s inspection workflow support the interpretation and implementation checks. This record makes a future regression visible without claiming that one successful color test covers the whole interface.