What does a color contrast checker do?

A color contrast checker calculates the contrast ratio between a foreground and background color using the WCAG relative luminance formula, then compares it to the WCAG thresholds: 4.5:1 for normal text, 3:1 for large text and UI components, and 7:1 for AAA. It tells you whether a color pair passes, not where that pair is used on your site.

How do I fix a color contrast failure?

Measure the rendered text and background colors, then swap to an existing token that passes, adjust the failing token's value, or change the background. Fix it at the token level so every element using that pair is fixed at once, then retest in the same viewport, theme, and state.

Do disabled buttons need to meet contrast requirements?

No. WCAG 2.2 SC 1.4.3 exempts text that is part of an inactive user interface component, as well as pure decoration and logos. Placeholder text and helper text are not exempt, even when they are styled to look muted.

Why does my automated scan miss some contrast failures?

Automated tools cannot reliably compute contrast for text over background images, CSS gradients, pseudo-element backgrounds, or elements overlapped by other elements. Deque documents that the axe-core color-contrast rule does not report on text with a background image. Check those cases manually.

What should a color contrast bug report include?

Include the page URL, viewport, theme and state, the element's CSS selector, the computed text and background colors, the font size and weight, the measured and required ratio with the WCAG success criterion, a screenshot, a severity, and a suggested fix named as a design token.

Color Contrast

How to Fix Color Contrast Failures: From Audit to Bug Report

Last updated: September 24, 2026

To fix a color contrast failure, measure the rendered text and background colors, compare the ratio to the WCAG threshold (4.5:1 for normal text, 3:1 for large text and UI components), then change the design token, not the one-off hex value. Record the element selector, both colors, the measured ratio, and the viewport and state in the bug report so the fix can be verified against the same conditions.

For the WCAG requirements and a comparison of checker tools, see our color contrast checker guide. To test a single color pair, use the free color contrast checker.

What a Color Contrast Checker Actually Measures

WCAG 2.2 defines contrast ratio as (L1 + 0.05) / (L2 + 0.05), where L1 is the relative luminance of the lighter color and L2 of the darker one. Normal text needs 4.5:1 (SC 1.4.3). Large text, meaning 18pt (24px) or 14pt bold (about 18.5px bold), needs 3:1. UI components and meaningful icons need 3:1 against adjacent colors (SC 1.4.11). AAA text needs 7:1 (SC 1.4.6). Thresholds are not rounded: 4.499:1 does not meet 4.5:1. Text in disabled components, decoration, and logos is exempt.

Where Contrast Failures Hide in Real UIs

Light gray captions: #9CA3AF on #FFFFFF measures 2.54:1 and fails 4.5:1.
White text on a mid-green success button: #FFFFFF on #22C55E measures 2.28:1 and fails even as large text.
White text on a bright red error badge: #FFFFFF on #EF4444 measures 3.76:1, which fails for normal text.
Pale input borders: #D1D5DB on #FFFFFF measures 1.47:1 and fails 3:1 non-text contrast.
A light-mode token in dark mode: #6B7280 passes on white at 4.83:1 but fails on #111827 at 3.67:1.

How to Find and Fix Contrast Failures: Step by Step

Check token pairs in Figma. Check every text token against every surface it can sit on, including component states and dark mode.
Scan the live build. Run an automated scan at each breakpoint. Automated tools such as the axe-core color-contrast rule do not report on text over background images, so check images and gradients manually.
Read the computed CSS colors. Read the computed text color, walk up the ancestors to the first solid background, account for opacity and alpha, and use the contrast ratio Chrome DevTools shows in the inspect tooltip and Color Picker.
Write a reproducible bug report. Include URL, viewport, theme and state, selector, both computed colors, font size and weight, measured vs required ratio with the WCAG criterion, a screenshot, a severity, and a suggested fix named as a token.
Fix the token. Swap to an existing passing token (#9CA3AF to #6B7280 goes from 2.54:1 to 4.83:1 on white), adjust the failing token (white on #16A34A is 3.30:1, on #15803D it is 5.02:1), or change the background.
Verify against the same conditions. Retest the same element, viewport, theme, and state, then rescan other pages that use the token.

Running This Workflow With OverlayQA

OverlayQA is a design QA and website feedback tool. Its accessibility audit runs axe-core checks plus AI review on the live page, in the browser extension for localhost and staging or from the dashboard for any public URL. Each contrast violation carries the WCAG success criterion, a severity, the element's CSS selector, and what was measured against what is required. Element capture records a screenshot, selector, computed CSS values, URL, viewport, and browser details, and issues export to Jira, Linear, Notion, Asana, or Trello with two-way sync.

How to Build Contrast Checks Into Design Reviews

Publish the passing text-on-surface token matrix next to your tokens.
Add WCAG 2.2 AA contrast in light and dark themes to your Definition of Done.
Review hover, focus, error, and selected states, not just default screens.
Scan every release candidate on staging and manually check text over images.
Tag contrast issues with the failing token and fix the token behind most of them.

Frequently Asked Questions

What does a color contrast checker do?: A color contrast checker calculates the contrast ratio between a foreground and background color using the WCAG relative luminance formula, then compares it to the WCAG thresholds: 4.5:1 for normal text, 3:1 for large text and UI components, and 7:1 for AAA. It tells you whether a color pair passes, not where that pair is used on your site.
How do I fix a color contrast failure?: Measure the rendered text and background colors, then swap to an existing token that passes, adjust the failing token's value, or change the background. Fix it at the token level so every element using that pair is fixed at once, then retest in the same viewport, theme, and state.
Do disabled buttons need to meet contrast requirements?: No. WCAG 2.2 SC 1.4.3 exempts text that is part of an inactive user interface component, as well as pure decoration and logos. Placeholder text and helper text are not exempt, even when they are styled to look muted.
Why does my automated scan miss some contrast failures?: Automated tools cannot reliably compute contrast for text over background images, CSS gradients, pseudo-element backgrounds, or elements overlapped by other elements. Deque documents that the axe-core color-contrast rule does not report on text with a background image. Check those cases manually.
What should a color contrast bug report include?: Include the page URL, viewport, theme and state, the element's CSS selector, the computed text and background colors, the font size and weight, the measured and required ratio with the WCAG success criterion, a screenshot, a severity, and a suggested fix named as a design token.