How to Document WCAG Contrast Checks Step by Step

A documented WCAG contrast check should capture the exact foreground and background colors, the displayed contrast ratio, the applicable AA/AAA result such as the 4.5:1 AA minimum for normal text, the tested size and state, and every adjustment made.

Documenting a check is more than recording that a color pair passed. A useful entry lets another reviewer identify the tested component, reproduce the result, understand which WCAG threshold applied, and see what changed after a failure. The Color Contrast Checker supplies the ratio and pass/fail results; your documentation process supplies the context around that calculation.

That distinction is important because the checker accepts two colors. It does not scan a webpage, identify the font size of an element, determine whether an image or gradient changes behind the text. Those details must be recorded separately.

What belongs in a contrast check record

A complete record should preserve enough information to distinguish the original design from the approved result. Use a consistent log so entries from different pages and contributors can be reviewed together.

Record field	What to include	Why it matters
Page or component	URL, route, component name, and element description	Identifies exactly what was tested
Interaction state	Default, hover, focus, active, selected, or disabled	Different states can use different colors
Foreground color	The text color as an exact hex value	Preserves the color that was actually evaluated
Background color	The effective background color as an exact hex value	Makes the tested pair reproducible
Text details	Text size, weight, and normal or large classification	Determines which threshold applies
Contrast result	The exact ratio displayed by the checker	Records the calculated result
Conformance result	The relevant AA or AAA pass/fail badge	Shows the outcome of the applicable check
Adjustment	The original pair, revised pair, and changed design token or style	Explains how a failure was resolved
Ownership	Tester, reviewer, date, and design or code version	Establishes when and by whom the result was approved

Do not overwrite a failed initial result with the successful revision. Keep both entries so the log shows the original risk, the decision made, and the final tested value. If a check covers several states, create a separate row for each pair rather than combining unlike results.

Document a check in the WCAG contrast checker

Follow this sequence for each foreground and background combination that needs a documented result.

1. Identify the element and its state. Record the page, component, text or interface purpose, font size, weight, and state being tested. The checker does not supply this context, so note it before entering colors. If the element has several states, document each distinct color pair separately.
2. Record the intended foreground color. Note the text color as a hex value from the relevant style, component, or design token. If transparency is involved, resolve the effective displayed color before testing and document that resolution separately.
3. Set the foreground in the checker. Open the Color Contrast Checker and choose the text color with the color picker or type its hex value into the foreground control.
4. Set the background in the same way. Use the color picker or enter the background hex value. The checker evaluates the pair as foreground and background, although the resulting WCAG ratio is symmetrical; labeling the fields correctly still matters for your documentation.
5. Read the exact result. Record the displayed contrast ratio and the pass/fail badges. Do not round the ratio in the log, because a rounded value can hide a difference between two nearby results.
6. Identify the applicable threshold. Compare the displayed result with the requirement for normal text, large text, or a UI component and graphical object. The checker reports the relevant thresholds, but you must classify the content because it does not read the page's typography or element role.
7. Adjust a failing pair and check it again. If the result does not meet the required level, change either the foreground or background in the design and enter the revised color into the checker. Continue until the displayed badge shows that the selected level is met.
8. Write the complete entry. Record the final ratio, applicable badge, revised colors, and the action taken in your documentation system. Add the tester, reviewer, date, and version, then repeat the process for any remaining states or components.

The checker performs its calculations locally in the browser, so the colors do not need to be uploaded. That supports private palette testing. Use the displayed ratio, pass/fail results, and tested color pair in your documentation system to keep a durable record.

Choose the threshold before recording a pass

WCAG uses different contrast thresholds depending on the content. Record the category before judging the badge so that a valid result for large text is not mistaken for one for normal text.

Content category	WCAG AA	WCAG AAA	Classification detail
Normal text	At least 4.5:1	At least 7:1	Text that does not meet the large-text definition
Large text	At least 3:1	At least 4.5:1	At least 18pt regular or 14pt bold
UI components and graphical objects	At least 3:1	Not separately defined	Includes relevant icons, form-field borders, and focus indicators

These values follow the W3C WCAG 2.1 minimum-contrast guidance. Large text is regular text at least 18pt, equivalent to 24px, or bold text at least 14pt, approximately 18.66px. See Color Contrast by Text Size: Which WCAG Threshold Applies? for help determining the category from an existing design.

A pass badge only has a clear meaning after you attach the text size, weight, and element purpose to the entry. For example, do not record only “passed AA” for a button label. Record that it is normal text, identify its size and weight, and then record the ratio and badge.

For a form border, icon, or focus indicator, use the separate non-text requirement rather than treating it as normal text. Also distinguish WCAG contrast from other accessibility checks: a passing ratio does not prove that the interface is operable, that labels are meaningful, or that color is not being used as the only way to communicate information.

Turn the result into a reusable audit entry

A fixed sentence structure makes logs easier to scan and compare. Use a format such as:

Example entry: Page or component: [location]; state: [state]; text size and weight: [details]; foreground: [hex]; background: [hex]; ratio shown: [exact ratio]; applicable result: [badge]; initial outcome: [pass or fail]; adjustment made: [change]; final tested pair: [hex values]; tester, reviewer, date, and version: [details].

This template distinguishes what the checker calculated from what your team decided. The checker supplies the ratio and pass/fail badges. Your record supplies the reason for testing, the applicable content category, the implementation action, and the approval status.

Use stable terminology for your internal statuses, such as “pass as tested,” “pass after revision,” “fail—open issue,” or “manual review required.” These are documentation labels, not extra outputs from the checker. Define them once so a later reviewer can distinguish an unresolved failure from a check that was intentionally classified under a different criterion.

When a revision fixes the issue, preserve the original and final foreground and background values. If the change came from a shared CSS variable or design token, record its name and the version in which it changed. That prevents a later palette update from making the old approval appear to apply to a color that was never tested.

Handle cases a two-color ratio cannot settle

The checker measures luminance contrast between one solid foreground color and one solid background color. It does not measure hue differences, and two visibly different colors can still have inadequate brightness contrast. A passing ratio also does not mean that color is the only indication of an error, selection, or required action; pair color with text, icons, or other cues where appropriate.

• Gradients: Test the lightest and darkest background points where the text appears. Record both tested pairs because one ratio cannot represent the entire gradient.
• Semi-transparent layers: Resolve the effective color after layering and test that effective pair. Keep the transparency or overlay details in the log.
• Text over images: Check representative points around the text, especially areas with the lightest and darkest backgrounds. The checker does not extract colors from an image automatically.
• Placeholders and disabled states: Record these as separate checks and apply the requirement appropriate to their role. Their presence in the log does not automatically mean the same text threshold applies to every state.
• Thin decorative fonts: Record the weight and visual treatment, and apply manual review even when a numerical threshold is met. The luminance calculation cannot judge every readability concern.

For any of these cases, the checker remains useful for testing each resolved color pair. The surrounding manual review is what connects the calculation to the final rendered experience.

Review and close the documentation

Before marking an entry complete, confirm that another person could repeat it without asking for missing information. Check that the page and state are identified, both hex values are present, the text category is justified, the exact ratio is written down, and the recorded badge matches that category.

• Confirm that the final colors match the implementation being released.
• Keep failed results linked to the design change that resolved them.
• Identify which reviewer approved the classification and final pair.
• Schedule rechecks when brand colors, typography, or component tokens change.

A passing pair is evidence for that tested combination, not proof that an entire page passes. A complete audit trail makes that scope explicit and helps the team focus follow-up work on untested states, dynamic backgrounds, and unresolved failures.

A concise final handoff can therefore state: “The foreground and background colors for the named component and state were entered in the Color Contrast Checker, the displayed ratio and applicable badge were recorded, any failing pair was revised and rechecked, and the final implementation was approved against the stated WCAG category.”

For a deeper look, see Does an RGB Complement Guarantee Accessible Contrast?.