Skip to main content

Developer guide

Check color contrast in the interface people actually use

By MultiZest · · 4 min read

Two colors can look attractive together and still make a small label difficult to read. Contrast checks are most helpful when applied to the real foreground, background and text size. Start with the pair a visitor must read, then inspect the states and layout where that pair changes.

The practical takeawayUse the unrounded contrast result for the relevant criterion, test real states and backgrounds, and review keyboard access and other accessibility requirements separately.

Identify the foreground and actual background

For body copy, use the text color and the panel beneath it. For a button label, use the label color and button fill. Do not substitute the page background when the text actually sits on a colored component. The checker compares two opaque HEX colors, so enter the final visible pair.

Transparency, overlays and background images can change that final pair. A CSS color declared with opacity may not look like the same fully opaque HEX value. Inspect the rendered interface and use the composited colors or a testing workflow that accounts for the actual background.

Choose the criterion for the size and purpose

Under WCAG 2.x, ordinary text needs at least 4.5:1 for AA and 7:1 for AAA. Large text needs 3:1 for AA and 4.5:1 for AAA. Large means at least 18-point regular text or 14-point bold text under the criterion, not simply a heading tag or a visually important label.

Essential non-text interface components generally use a 3:1 threshold against adjacent colors, subject to the criterion’s scope and exceptions. Use the official explanation to determine applicability. A ratio cannot decide by itself whether a decorative icon or a specific state carries essential information.

Text criterionMinimum ratio
AA normal text4.5:1
AA large text3:1
AAA normal text7:1
AAA large text4.5:1

Use the result without rounding away a failure

Black on white has a contrast ratio of 21:1. A common gray such as #777777 on white is about 4.48:1 and falls just below the 4.5:1 AA threshold for normal text. The visual difference near a boundary can be small, which is why the pass decision uses the underlying unrounded value.

Try a slightly darker text color or a lighter background and check again. Often a modest adjustment preserves the design while improving readability. Then preview realistic text at its actual size; a large bold sample alone can hide the difficulty of a small paragraph.

Review hover, focus and message states

Buttons, links and fields may change colors when hovered, focused, disabled or invalid. Review the states that convey information, not only the default screenshot. A pale error message can be harder to read precisely when someone needs help completing a form.

Do not use color as the only signal. Pair an error color with descriptive text, and provide visible keyboard focus that can be recognized in the surrounding layout. These checks involve more than the two-color text ratio but belong in the same practical interface review.

Treat gradients as changing backgrounds

A gradient can place a dark background behind the first word and a light background behind the last. Testing one end does not establish readability throughout the text. Identify the least favorable region beneath essential content, including where wrapping moves the text on a phone.

A solid panel or backing behind the copy may be simpler to maintain than a complex gradient that must work beneath every responsive line. Use the gradient generator for the background declaration, then test the actual component. This two-color checker does not automatically analyze an entire gradient or photograph.

Put the result inside a wider accessibility review

Contrast helps readability, but a readable interface can still exclude someone who cannot operate its controls. Check labels, keyboard navigation, focus order, errors, alternatives for visual information and zoom behavior. Test the task rather than treating a collection of color passes as certification.

Keep the tested colors and relevant states with the design record. Recheck when a theme, font size or component changes. A passing pair is useful evidence about one criterion in one context, and that practical limit is more honest than claiming the entire page is accessible from a single measurement.

Try the tools used in this guide

Sources and further reading

Continue reading