WCAG Contrast Requirements: Testing Text and UI States

A color pair can pass in a palette file and fail in the interface. Opacity, background images, hover treatments, and font size can all change the conditions being evaluated. Text contrast testing therefore needs a repeatable method for identifying the actual foreground, the actual background, and the requirement that applies to the rendered text.

Establish the text contrast requirement

For WCAG 2.2 Level AA, ordinary text requires a contrast ratio of at least 4.5:1. Large-scale text requires at least 3:1. The large-text definition is at least 18 point, or at least 14 point when bold; in common CSS conversions those correspond to 24px and approximately 18.67px respectively. Do not confuse 18 CSS pixels with 18 points.

Use the contrast checker to enter the foreground and background colors and compare the resulting ratio with the applicable threshold. Evaluate the intended pairing, not just each color in isolation. A brand blue can be suitable on white and unsuitable on a dark panel.

Consult WCAG Contrast Minimum for the formal conditions and exceptions. A ratio below the threshold does not pass because the difference is visually subtle: 4.49:1 is not 4.5:1. Keep enough margin to avoid fragile pairings during later design changes.

Measure the colors that are actually rendered

Identify inherited opacity, semitransparent backgrounds, overlays, and blending. A white label with reduced opacity over a photograph is not simply white against the original photograph. Its displayed color depends on compositing, and the background can vary across the text area.

For a gradient or image, inspect the weakest region behind the text. Testing a convenient dark corner does not establish that every word remains readable. A stable opaque panel or sufficiently strong scrim often makes the relationship more dependable than trying to approve one screenshot of variable imagery.

.hero-copy {
color: #ffffff;
background: #172554;
padding: 1.5rem;
}
.secondary-copy {
color: #475569;
/* Keep the text opaque; choose a deliberate foreground. */
}

When testing ordinary solid colors, use the specified color values rather than sampling antialiased edge pixels from a screenshot. Antialiasing mixes glyph edges with their surroundings and can create misleading measurements. Screenshots remain useful for understanding layout and compositing, but they are not always a reliable source of the original foreground value.

Use the color converter to translate equivalent color formats when your design file and CSS use different notations. Conversion organizes the data; it does not make two colors more accessible or replace the contrast calculation.

Inventory every text-bearing state

Start with body copy, headings, labels, help text, placeholders, links, badges, notifications, and button labels. Then check hover, focus, active, selected, visited where applicable, and error states. A component's default appearance is only one part of its contrast behavior.

Placeholder text is not exempt simply because it is temporary. If it conveys text users need to perceive, assess it under the relevant requirement. It also does not replace a persistent label. Likewise, secondary copy is not an exception just because the visual hierarchy intentionally makes it quieter.

WCAG includes exceptions for text in inactive user interface components, incidental text, and logotypes under the relevant criterion. Apply these carefully. A button styled as disabled but still available is not genuinely inactive. Essential instructions placed beside a disabled field do not automatically inherit an exception.

Document each approved pair with its surface and state. A token named muted is insufficient because it says nothing about which backgrounds it supports. Prefer a relationship such as secondary text on default surface, along with the actual values and measured ratio.

Separate text contrast from other requirements

A passing text ratio does not establish that a control boundary, focus indicator, or chart mark meets its own requirements. Non-text contrast has different conditions and exceptions. Evaluate the information needed to identify a control or understand a graphic independently from the text inside it.

Links within paragraphs also need attention beyond their ratio against the page. If color alone distinguishes links from surrounding text, additional conditions apply. An underline is usually a robust way to provide a non-color cue without relying on users detecting a subtle hue change.

For Level AAA, the enhanced text contrast criterion generally raises the thresholds to 7:1 for ordinary text and 4.5:1 for large-scale text. Make the target explicit in acceptance criteria. Do not report an AA failure because a design misses AAA, or claim enhanced conformance because only one heading meets the higher ratio.

The WCAG Use of Color explanation helps distinguish hue-dependent communication from contrast. These concerns overlap in practice but should remain separate checks so one passing measurement does not conceal another failure.

Create a repeatable review and remediation process

When a pair fails, adjust the foreground or background deliberately and recheck every dependent state. Increasing font size solely to qualify for the lower threshold may damage the layout or change the content hierarchy. Prefer a color solution that supports the actual reading task.

For a product with many themes, build an inventory of approved semantic pairings rather than a spreadsheet of unrelated colors. Test light mode, dark mode, user-selected themes, and high-contrast variants. A component that inherits its surface needs checks in each place where it is actually used.

Automated scanners can find many solid-color failures, but complex backgrounds and hidden states still need human review. Record any cases the scanner could not determine. An incomplete result is a request for inspection, not a pass.

Use WAI Easy Checks for complementary visual review and keep contrast findings with other accessibility tests. Recheck after typography changes, theme updates, and new background imagery. Contrast compliance is a relationship maintained through change, not a permanent property attached to a hex value.

Key takeaways

• Apply 4.5:1 or 3:1 according to the actual large-text definition.
• Measure rendered pairings, including compositing and variable backgrounds.
• Inventory text across interaction states, not only default screens.
• Keep text, non-text, and color-only communication checks separate.
• Document approved foreground and surface relationships for regression testing.