WCAG color contrast checker: how to test your colours and fix failures
A WCAG color contrast checker takes two colours, text and background, and returns a ratio. Level AA needs at least 4.5 to 1 for normal text and 3 to 1 for large text (18 point, or 14 point bold) and for user interface parts such as button borders and form field outlines. The free options are WebAIM's Contrast Checker, the contrast tools built into Chrome DevTools and Firefox, and extensions such as WAVE and axe DevTools. This guide shows how to use them, gives worked ratios for common brand colours and explains how to fix a failure without changing your look.
WCAG color contrast checkers compared
| Tool | Cost | What it does | Best for |
|---|---|---|---|
| WebAIM Contrast Checker | Free | Enter two hex colours, get the ratio and pass or fail for AA and AAA | Testing a pair and finding a darker shade |
| Chrome or Edge DevTools | Free | Click text in the Inspector; the colour picker shows the ratio and a safe line | Real colours on the live page, including gradients |
| Firefox accessibility inspector | Free | Highlights every contrast failure on a page | Whole-page view |
| WAVE or axe DevTools | Free extensions | Flags contrast errors among other errors | One-page scan |
| Colour tools in design apps | Free to paid | Check while designing | New brand palettes |
| Site Record | $499 once | Lists each failing colour pair on up to 25 pages with a replacement | Getting the fixes written |
Tools from their public pages, checked 2026-11-15. Ratios below we computed with the WCAG formula.
The WCAG contrast numbers you need
- Normal text, Level AA: 4.5 to 1 (success criterion 1.4.3).
- Large text, AA: 3 to 1. Large means 18 point (24 pixels) or bigger, or 14 point (about 18.7 pixels) bold or bigger.
- User interface parts and graphics, AA: 3 to 1 against neighbouring colours (criterion 1.4.11, added in WCAG 2.1). That covers input borders, checkbox outlines, focus indicators and icons that carry meaning.
- Level AAA: 7 to 1 for normal text and 4.5 to 1 for large text (1.4.6). Optional, and not what most agreements ask for.
- Exempt: pure decoration, logos and text in a disabled button.
The ratio runs from 1 to 1 (same colour) to 21 to 1 (black on white). It is based on relative luminance, not on how a colour looks to you, so a bright orange can fail on white even though it looks bold.
How to check colour contrast, step by step
- Find the two hex codes. In Chrome, right-click text, choose Inspect and look at the colour and background in the Styles panel.
- Enter them in a checker such as WebAIM's, or use the picker in DevTools, which shows the ratio next to the colour.
- Note the text size. The same pair can pass as large text and fail as normal text.
- Check text over images. Test the lightest and the darkest part of the picture behind the words; add a solid or semi-solid panel if it fails.
- Check states. Hover, focus, visited and disabled-looking links often use different colours.
- Check buttons and form borders against the page for the 3 to 1 rule.
- Record the before and after ratios with the date.
Worked examples: common colours on white
| Text or button colour | On white | AA normal text (4.5) | AA large text or UI (3) |
|---|---|---|---|
| #999999 grey | 2.85 to 1 | Fail | Fail |
| #888888 grey | 3.54 to 1 | Fail | Pass |
| #777777 grey | 4.48 to 1 | Fail, just | Pass |
| #767676 grey | 4.54 to 1 | Pass, just | Pass |
| #595959 grey | 7.00 to 1 | Pass (also AAA) | Pass |
| #6c757d grey (a common framework "muted" colour) | 4.69 to 1 | Pass | Pass |
And for white text on a coloured button:
| Button colour | White text on it | Result for normal text | Darker option that passes |
|---|---|---|---|
| #f4a261 orange | 2.06 to 1 | Fail | Use dark text (#000 or #1a1a1a) on it |
| #ff6b35 orange | 2.84 to 1 | Fail | Darken toward a burnt orange, then re-test |
| #17a2b8 teal | 3.04 to 1 | Fail; passes for large text only | A deeper teal, re-tested |
| #28a745 green | 3.13 to 1 | Fail | #0a7c5a gives 5.19 to 1 |
| #2a7de1 blue | 4.10 to 1 | Fail | #1a5fb4 gives 6.29 to 1 |
| #e63946 red | 4.17 to 1 | Fail | #c0392b gives 5.44 to 1 as text on white |
The lesson: many popular "friendly" brand colours fail with white text. The fix is usually a darker shade, or dark text on the light colour, not a new brand.
How to fix a contrast failure without losing your brand
- Darken the text, not the whole design. Moving grey body text from #999 to #595959 passes at every size.
- Flip the button. A light brand colour with dark text can pass where white text fails.
- Keep the brand colour for large or decorative use and use a darker shade for small text and links.
- Add a border of 3 to 1 contrast around a pale input or button.
- Put text on a panel when it sits on a photo.
- Change it once. On WordPress and Shopify these colours live in the theme settings or a few CSS variables, so one edit fixes every page. Platform notes: WordPress accessibility audit and ADA compliance for Shopify.
What a colour contrast checker cannot do
Checkers test the pair you give them. They struggle with gradients, text over photos, semi-transparent overlays, and colours that change on hover or in dark mode. They also cannot judge whether colour is the only way you give information, such as a red error with no text or icon, which is its own WCAG rule (1.4.1). After the tool, look at the page with the brightness down and squint; if a link or price disappears, test it again by hand. A full scan checks many other things too; see ADA website compliance checker.
Contrast and the lawsuits: why this is the first fix
Low contrast is the most frequently reported error type in large annual scans of home pages, such as the WebAIM Million study, and it is easy for an automated tool to detect. That makes it cheap for anyone testing your site to find, and cheap for you to fix. We are not lawyers and this is not legal advice; if you have a demand letter, see an attorney. For the full list of first checks, use the ADA compliant website checklist.
A worked example: fixing a restaurant home page
A café home page has three contrast problems. The menu link text is #999999 on white: 2.85 to 1, a fail. The "Order" button is white on #f4a261 orange: 2.06 to 1, a fail. The small date line under each news item is #777777 on white: 4.48 to 1, a near miss. The owner changes the menu links and date line to #595959 (7.00 to 1), and switches the button text from white to near-black, which fixes the button without changing the orange. The design looks almost the same and three error types are gone. Total time: ten minutes in the theme's colour settings.
Text over photos and gradients
Hero banners are where contrast fails most often and where checkers help least, since the background changes under the words. Test the words against the lightest part of the image behind them. If it fails, use one of three fixes: a solid colour panel behind the text, a dark overlay over the image (try 40–60% black), or moving the text to a plain area. Do not rely on a text shadow alone; checkers do not count it. Text in images, such as a menu saved as a JPG, fails a different rule and cannot be fixed with colour; the real text must be on the page.
Focus outlines, links and states
The 3 to 1 rule for interface parts means a keyboard focus outline should contrast with the page by at least 3 to 1, and so should the edge of a button or field when the border is the only thing showing it is there. Links inside a paragraph need more than colour to stand out: either underline them or give them 3 to 1 contrast against the surrounding text plus a second cue on hover and focus. Check hover, focus and visited states separately, since themes often style each with a different colour. The wider list of keyboard and focus checks is in the free checker guide.
Frequently asked questions
What contrast ratio does WCAG require?
4.5 to 1 for normal text and 3 to 1 for large text and interface parts at Level AA; 7 to 1 and 4.5 to 1 at AAA.
What counts as large text?
18 point (24 pixels) or larger, or 14 point (about 18.7 pixels) bold or larger.
Do logos and decorative images need to pass?
No. Logos and purely decorative elements are exempt. Text that conveys information is not.
Do placeholders and disabled buttons count?
Placeholder text is real text and should pass 4.5 to 1. Disabled controls are exempt, but make them obvious another way.
Is white text on a light blue button OK?
Test it. Many mid blues fall just under 4.5 to 1, such as #2a7de1 at 4.10 to 1. A darker shade like #1a5fb4 passes at 6.29 to 1.
Which free checker should I use?
WebAIM's Contrast Checker for a pair; Chrome DevTools for colours on the live page; WAVE or axe for a whole page.
Sources
- W3C, WCAG 2.1: success criteria 1.4.3 Contrast (Minimum), 1.4.6 Contrast (Enhanced), 1.4.11 Non-text Contrast.
- WebAIM, Contrast Checker and "The WebAIM Million" (checked 2026-11-15).
- University at Buffalo and State of Illinois colour contrast guides (checked 2026-11-15).
- Ratios computed by us with the WCAG relative-luminance formula.