Using a Color Contrast Checker to Meet WCAG AA

The mid-gray #767676 on white has a contrast ratio of 4.54:1. One step lighter, #777777, comes out at 4.48:1. The first passes WCAG AA for body text and the second fails, and nobody can see the difference between them.

A color contrast checker takes two colors and returns a ratio. The hard part is choosing which two colors to put in, because the ones in the design file are often not the ones a user sees.

How the ratio is calculated

WCAG defines contrast through relative luminance, the light a color emits on a linear scale from 0 (black) to 1 (white). Each sRGB channel is converted to a linear value, and the three are weighted: green accounts for about 72 percent of luminance, red about 21 percent and blue about 7 percent.

The ratio is then (L1 + 0.05) / (L2 + 0.05), where L1 is the lighter color's luminance and L2 the darker one's. The 0.05 accounts for ambient light reflecting off a screen. Results run from 1:1, the same color twice, to 21:1, black on white. The order of the two colors doesn't matter: white on navy and navy on white give the same number.

Hue has no direct effect. A saturated orange and a gray with the same luminance score identically, which surprises designers who expect a vivid color to stand out. White text on #f97316, a bright orange, is 2.80:1 and fails. Black on the same orange is 7.49:1.

The AA thresholds

Three success criteria set the main contrast minimums, and two of them apply at Level AA.

Content	Criterion	AA	AAA
Body text	1.4.3 / 1.4.6	4.5:1	7:1
Large text	1.4.3 / 1.4.6	3:1	4.5:1
UI components and meaningful graphics	1.4.11	3:1	none

Large text means at least 18 point, or 14 point bold. In CSS pixels that is roughly 24px regular or 18.66px bold. A 20px heading at regular weight is not large text and needs 4.5:1.

1.4.11 Non-text Contrast covers what identifies a control and its state: the border of a text input, the outline of a checkbox, the thumb of a toggle, the focus indicator, and the parts of a chart or icon someone needs to read it. The 3:1 is measured against the adjacent colors. An input marked only by a pale gray border on a white page fails it, even when the text typed inside passes. A field whose fill itself has 3:1 against the page can get by with a fainter border, because the fill identifies it.

The text thresholds have not changed since WCAG 2.0. Non-text contrast arrived in 2.1, and 2.2 added a 3:1 comparison for focus indicators at AAA, covered in the WCAG 2.2 overview.

What the contrast rules exempt

Not everything on the page has to meet the minimums. 1.4.3 groups its exceptions under incidental text and logotypes, which in practice covers:

• Disabled controls. Text and borders of an inactive button or field are exempt. The exemption covers controls that really can't be used, not ones styled as quiet secondary actions.
• Decoration. Text or graphics that are purely decorative, or not visible to anyone.
• Incidental text. Text in a photo that happens to be there, like a street sign in the background.
• Logos. Text that is part of a logo or brand name.

Placeholder text is not exempt. It's text, and the user often needs it to know what goes in the field. Light gray placeholders are one of the most frequent 1.4.3 failures, along with the gray secondary text under a heading and the timestamp in a list row.

Getting the right pair into the checker

Most contrast failures in a shipped product were never in the design file. They come from a pair that was never checked because nobody wrote it down. These are the cases worth testing directly.

Text on a tinted surface. #6b7280, a common secondary-text gray, passes on white at 4.83:1. Put it on a card filled with #f3f4f6 and it drops to 4.39:1, a fail.

Transparency. A checker that takes hex values can't read rgba or opacity. Black text at 50 percent opacity on white renders as #808080, which is 3.95:1. Work out the color that ends up on screen, by sampling it with an eyedropper from a screenshot or by blending the values, and check that.

Text over images and gradients. The ratio has to hold against the worst part of the background the text actually covers. On a hero photo that is usually the brightest patch behind the headline. A solid band behind the text fixes the ratio when the image is swapped later, and a dark overlay limits how far it can move.

States. Hover, focus, active, selected, visited and error states are new pairs. A link that passes at rest can fail on hover if the hover color is lighter. A selected tab with white text on a mid-blue fill needs checking against that fill, not the page.

Dark mode. Gray text that passed on white has no guaranteed relationship to the same token's dark-mode value. #757575 on a #121212 background is 4.07:1 and fails. #808080 on the same background is 4.74:1 and passes.

Brand colors on buttons. Mid-saturation blues, greens and oranges are where white-on-color buttons fail. White on #3b82f6 is 3.68:1; white on #2563eb is 5.17:1. White on #22c55e, a bright success green, is 2.28:1.

How common is color blindness, and is contrast the same problem?

Red-green color vision deficiency affects about 8 percent of men and 0.5 percent of women of Northern European descent. Rates are lower in most other populations. Low vision, aging eyes and screens in sunlight affect far more people than that.

Color blindness is mostly covered by a different criterion, 1.4.1 Use of Color, which says color can't be the only way information is conveyed. A form that marks invalid fields only with a red border fails 1.4.1 no matter how much contrast the red has. Add an icon or a text message. A color contrast checker won't catch this, since it measures luminance and doesn't know what the color is supposed to mean.

Where the WCAG formula is weak

The WCAG 2 contrast formula is known to misjudge some pairs. It tends to overrate contrast for dark colors, so some dark-on-dark combinations pass while being hard to read, and it ignores font weight and size beyond the large-text cutoff. A thin 300-weight font at 4.6:1 passes and can still be hard to read.

APCA, the Accessible Perceptual Contrast Algorithm, was developed as a possible contrast method for WCAG 3. It accounts for which color is the text and which is the background, and for font size and weight. WCAG 3 is still a working draft, its contrast method isn't settled, and APCA scores are not a conformance requirement for anything today.

Building contrast into a design system

Checking screen by screen misses every pair nobody screenshotted. Deciding the pairs at the token level catches them:

1. List every text token and every surface token it can appear on, including tinted cards, banners and both themes.
2. Run each pair through a color contrast checker and record the ratio next to the token.
3. Mark which pairs are allowed for body text (4.5:1), which only for large text or icons (3:1), and which are not allowed at all.
4. Check the border and focus tokens against every surface they sit on, at 3:1.
5. Re-run the table whenever a brand color or surface changes.

For step 2, the TYPENORM contrast checker takes two hex values and grades the pair as AAA, AA, AA large-text only, or fail. It's free, and signed-in users keep a history of what they've checked.

Automated online accessibility testing tools also flag contrast, by reading computed styles from the rendered page. They catch most plain text-on-solid failures. They often miss text over images, gradients and overlapping elements, and they only test the states present when they run, so hover and focus need a manual check. The other criteria these tools cover, and the ones they can't, are collected in the accessibility hub.

FAQ

What contrast ratio does WCAG AA require? 4.5:1 for normal text, 3:1 for large text (18pt, or 14pt bold), and 3:1 for user interface components and meaningful graphics.

Where does the 4.5:1 contrast ratio come from? It is the WCAG 2 minimum for body text at Level AA, unchanged since WCAG 2.0 and carried into 2.1 and 2.2. W3C's Understanding document says it compensates for the loss in contrast sensitivity typical of vision around 20/40.

What does a color contrast checker actually measure? The ratio between the relative luminance of two colors, using the WCAG formula. It doesn't account for font weight, transparency, background images or what the color means.

Does a 4.49:1 ratio pass? No. The thresholds are minimums, and a ratio just under 4.5:1 doesn't meet them.

Do disabled buttons need to meet contrast requirements? No. Inactive user interface components are exempt from both 1.4.3 and 1.4.11.

What contrast does AAA require? 7:1 for normal text and 4.5:1 for large text. Non-text contrast stays at 3:1, though 2.4.13 Focus Appearance adds a 3:1 requirement for focus indicators at AAA.

Source: W3C — Understanding Success Criterion 1.4.3: Contrast (Minimum).