🧰 ToolPicoAll Tools →
HomeBlog › Why Does My Text Fail WCAG Contrast?

Why Does My Text Fail WCAG Contrast? A Practical Fix Guide

If an accessibility audit flagged your gray text or a low-contrast button, the fix is usually a small lightness adjustment, not a full redesign. Here's how the WCAG contrast ratio actually works, why "readable to me" isn't the same as "passes AA," and how to find a compliant color fast.

In this guide

Why does a color pair fail contrast?

Quick answer: A color pair fails when the calculated WCAG contrast ratio falls below the required threshold for its text size — usually because the two colors are too close in relative luminance (perceived brightness), even if they look visually distinct on your screen.

WCAG measures contrast using the relative luminance of each color, a value derived from the sRGB channels with gamma correction and the standard weights 0.2126 for red, 0.7152 for green, and 0.0722 for blue. The ratio between the lighter and darker luminance produces a number from 1:1 to 21:1. Monitors, lighting conditions, and your own eyesight can make a low-contrast pair look "fine" while the actual number sits well under the required minimum.

Common trap: Light-gray-on-white text (a popular "subtle" design choice) is one of the most frequent contrast failures found in real audits, because gray desaturates the perceived difference in luminance far more than it looks like it should.

A color contrast checker removes the guesswork: paste in your foreground and background colors (hex, rgb, hsl, or with alpha for semi-transparent overlays) and get the exact ratio plus an automatic suggested shade if the pair fails.

What's the real difference between AA and AAA?

Quick answer: AA is the baseline most sites are expected to meet — 4.5:1 for normal text, 3:1 for large text. AAA is the enhanced level — 7:1 and 4.5:1 respectively — and is recommended for especially important content rather than required site-wide.

Most legal accessibility requirements (and most design systems) target AA. AAA is meaningfully stricter and can be hard to satisfy with brand colors that lean pastel or mid-tone, so many teams reserve AAA for things like health disclaimers, legal notices, or primary body copy on content-heavy pages.

Content typeAAAAA
Normal text4.5:17:1
Large text (18pt+/24px+, or 14pt+ bold)3:14.5:1
UI components / icons3:1not defined

Example (illustrative, not a guarantee for your exact pixels): a hypothetical dark slate heading at roughly #1f2333 on a white card background lands around 14.8:1 — comfortably above both AA and AAA. A lighter slate at #7d8299 on the same white would sit closer to 3.6:1, which passes for a large bold heading but fails for normal body text. Always verify your own exact hex values rather than relying on lookalike examples.

Does a big heading need the same contrast as small text?

Quick answer: No — WCAG lowers the bar for large text (18pt/24px normal weight, or 14pt/18.66px bold) to 3:1 for AA, because bigger glyphs are inherently easier to read even at lower contrast, and UI components like button borders and icons share this same 3:1 minimum.

This is why a bold 20px section title can visually sit right next to a 14px paragraph and pass at a noticeably lower ratio — they're held to different thresholds by design. It also means checking only your body text isn't enough; buttons, form outlines, and icon-only controls need their own separate 3:1 check against whatever they're sitting on.

How do I know a color pair is colorblind-safe?

Quick answer: Contrast ratio alone doesn't guarantee a pair is distinguishable for colorblind users — you also need to preview the pair under protanopia, deuteranopia, tritanopia, and achromatopsia simulation, and avoid relying on color alone to convey meaning (like red vs. green status dots).

Two colors can post a high numeric contrast ratio and still be hard to tell apart for someone with red-green colorblindness, because hue and luminance aren't the same thing. The safer pattern is to pair color with a second signal — an icon, a label, an underline — so the information doesn't disappear if the color difference collapses for a given viewer.

Check your exact colors in seconds

Enter your foreground and background, see the WCAG ratio, AA/AAA pass/fail, an APCA score, a live preview, and a colorblindness simulation — free, no signup.

Try the free Color Contrast Checker →

Frequently asked questions

What contrast ratio do I actually need for body text?

For normal-size body text, WCAG AA requires at least 4.5:1 between the text color and its background. That's the level most sites should target. WCAG AAA raises the bar to 7:1 for the same text, which is stricter and not always practical for a full design system.

Why does my gray text fail even though it looks readable to me?

Light and medium grays often look fine on a bright monitor in good lighting but fail the math because contrast is measured by relative luminance, not by how the color "feels". A common example: medium gray #767676 on white barely clears AA at roughly 4.54:1, so a slightly lighter gray like #999999 would already fail. Always check the number instead of trusting your eyes.

Does a large heading need the same contrast as body text?

No. WCAG defines "large text" as 18pt (about 24px) and up at normal weight, or 14pt (about 18.66px) and up if bold. Because bigger characters are easier to distinguish, the AA threshold for large text drops to 3:1 instead of 4.5:1. A bold 20px heading can pass at a lower ratio than a 14px paragraph next to it.

Do buttons and icons need to pass contrast too?

Yes. WCAG also covers UI components and graphical objects, like button borders, form field outlines, and icons that convey meaning — these need at least a 3:1 contrast ratio against their adjacent background, separate from the text-contrast rules.

How do I fix a color pair that fails?

The fastest fix is to shift the lightness of one color (usually the text) up or down until the ratio clears your target threshold, while keeping the hue close to your original brand color. A color contrast checker that suggests an accessible shade automatically saves the trial-and-error of adjusting values by hand.

Related guides

Methodology note: The examples above are illustrative and use example hex values to explain how thresholds behave — they are not a substitute for testing your own site's exact colors. This guide is for general informational purposes and is not legal accessibility advice; consult WCAG's official documentation or an accessibility professional for compliance-critical projects.