How to Audit Text Contrast on a Real Web Page
Find the actual foreground and surface, test interactive states, fix a failure and record evidence that another person can reproduce.
Updated : Rebuilt as a practical page-audit workflow; corrected point/pixel confusion and automated-check limitations.
A pasted HEX pair is only as useful as the colors you extracted. A design file may show one surface while the shipped component inherits another. Start with one real element in the browser, record its state, and identify the colors that actually meet there.
1. Make an inventory by role
- •Begin with body text, navigation, form labels, placeholder text and helper messages.
- •Repeat the check for hover, keyboard focus, selected, error and dark-mode states.
- •Record a page URL and a recognizable element label. Keep unpublished or personal information out of publicly shared links.
For a form, write down the label, input value, hint and error message separately. They may use different tokens even though they sit in the same component. A passing label does not establish that a pale helper message passes.
2. Inspect computed colors
Use browser developer tools to inspect the element. Record the computed text color, font size and weight, and identify the visible background beneath it. Check ancestor opacity and overlays. Avoid sampling the antialiased fringe of a letter as though it were the intended foreground; it contains a mixture of text and background.
For ordinary opaque colors, translate RGB to HEX if needed and enter the values in the checker. For gradients and images, inspect the changing background where the text appears. A single sampled point cannot stand in for the whole word or every responsive crop.
3. Test and preserve a failing example
A reproducible text and background example.
Same pair, larger text.
#9CA3AF / #FFFFFF
A pale helper-text example. The computed result below makes the failure reproducible without depending on a screenshot.
2.538841:1 WCAG contrast; 49.7710 Lc APCA.
Normal-text AA: Fail. Large-text AA: Fail. Labels apply to text contrast only.
Reproduce this pair and try a fixUse the contrast checker to load these exact values. Its result link stores the two colors, so a reviewer can reopen the same calculation.
4. Make one deliberate change
Keep the background fixed and apply a suggested foreground. Review the new text beside surrounding body copy, links and disabled content. Then paste the exported CSS into the real component and inspect its computed style again. Token aliases, specificity and opacity can otherwise leave the shipped appearance different from the tested pair.
Increasing font size is an option only when that size fits the content hierarchy. Do not mark small text as large because it is visually prominent. Use the size and weight in the rendered page to choose the requirement.
5. Store a small regression record
- •Element and state: checkout form, email hint, default state.
- •Inputs: #9CA3AF text on #FFFFFF; record the final replacement after fixing.
- •Requirement: normal-text AA, 4.5:1.
- •Evidence: the computed ratio, result URL, tested viewport and a note about opacity or imagery.
6. Add automation with human review
An automated scan can catch many straightforward failures after CSS changes. It can also skip uncertain backgrounds or leave cases for manual review. Treat an absence of automated violations as one input, not a certificate. Revisit image backgrounds, canvas content, overlays, focus appearance and color-only meaning yourself.