How to Fix Colour Contrast Errors (WCAG 1.4.3)
WCAG 1.4.3 requires text to have enough contrast against its background: at least 4.5:1 for normal text and 3:1 for large text. This guide shows how to find every failing element, choose compliant colours, update them at the source (theme settings or CSS variables), and confirm that the automated check passes.

Why it matters
Low-contrast text is among the most common accessibility failures. It is hard to read for people with low vision or colour-vision deficiency, for older users, and for anyone reading a phone in sunlight. It also creates legal exposure under the ADA, the European Accessibility Act (enforced since June 2025) and similar laws.
Lighthouse runs the same contrast rule in its Accessibility score, so leaving it unfixed lowers a metric that clients and stakeholders track. Readable text also keeps visitors on the page longer and makes CTAs easier to act on.
What you need
Step-by-step fix
List every failing element with axe
Open the page in Chrome, then open DevTools (F12) and go to the axe DevTools tab. Run Scan all of my page and filter to the Elements must meet minimum color contrast ratio thresholds issue. Each result shows the foreground colour, background colour, font size, weight and the actual ratio.
Alternatively, run Lighthouse (DevTools > Lighthouse > Accessibility), which uses the same rule. Scan your homepage, one template of each type (product, article, category) and any page with a form.
npx @axe-core/cli https://example.com https://example.com/blog/ --rules color-contrast
Work out the target ratio for each element
Apply the thresholds the check uses:
- Normal text: at least 4.5:1.
- Large text: at least 3:1. Large means at least 24px regular, or at least 18.66px (14pt) bold (font-weight 700 or more).
- Ratios are not rounded, so 4.49:1 fails.
- Disabled controls, purely decorative text and logotypes are exempt.
Note any element axe marks as Needs review rather than failed. These are usually text over background images, gradients or overlapping elements, where you must check the contrast manually.
Pick compliant colours in DevTools
In the Elements panel, select a failing element. In the Styles pane, click the colour swatch next to color. The colour picker shows Contrast ratio with AA and AAA lines drawn on the colour field.
Drag below the AA line to get the nearest compliant shade that keeps the same hue. Write down the new hex value for each colour pair. Common safe swaps on white backgrounds:
- Grey text: use #767676 (4.54:1) or darker.
- Links: use #2563EB (5.17:1) instead of a light blue.
- White text on a button: the button background must be dark enough to reach 4.5:1 against #FFFFFF.
Fix the colours at the source, not per element
Change the colour where it is defined: in theme settings, design tokens or CSS custom properties. Avoid adding overrides on individual elements. That way every component that uses the colour is fixed at once, and new pages inherit compliant values.
Search your stylesheet for the old hex values to catch hard-coded copies.
:root {
/* was #9CA3AF (2.54:1 on white) */
--color-text-muted: #6B7280; /* 4.83:1 */
/* was #60A5FA (2.54:1) */
--color-link: #2563EB; /* 5.17:1 */
--color-btn-bg: #1D4ED8; /* white text 6.70:1 */
}
body { color: #1F2937; }
.muted, .meta, footer { color: var(--color-text-muted); }
a { color: var(--color-link); }
.btn-primary { background: var(--color-btn-bg); color: #FFFFFF; }Remove opacity tricks and fix text over images
axe measures the colour that actually renders. 4)`, blends with the background and often fails even if the base colour looks dark. Replace these with solid hex colours.
For hero text on photos, add a solid or semi-opaque overlay behind the text so the effective background is predictable. Then check the lightest part of the image under the text manually.
.hero { position: relative; }
.hero::before {
content: "";
position: absolute; inset: 0;
background: rgba(0, 0, 0, 0.55); /* darkens photo behind white text */
}
.hero__content { position: relative; color: #FFFFFF; }
/* replace */
.caption { opacity: 0.6; }
/* with */
.caption { color: #4B5563; }Check forms, badges and third-party widgets
Review the places that are easy to miss: form labels and helper text, error messages, 'Sale' badges, cookie banners, chat widgets, footer legal text and breadcrumb separators. Third-party widgets often have a colour setting in their vendor dashboard. If one doesn't, override its CSS or ask the vendor to fix it, because failures inside embedded widgets still count against your page.
Re-run the scan and confirm zero failures
Clear any caching or CDN layer, then reload the pages you scanned in step 1. Run axe DevTools or Lighthouse again and confirm the color-contrast rule reports no violations. Manually check every item that was marked Needs review.
Add the axe CLI command to your CI pipeline or release checklist so new components don't bring the problem back.
npx @axe-core/cli https://example.com --rules color-contrast --exit
Platform-specific notes
WordPress (block themes)
Go to Appearance > Editor > Styles > Colors to change palette, text, link and button colours site-wide. These are saved to theme.json (settings.color.palette) or global styles. For classic themes, use Appearance > Customize > Colors or Additional CSS. Page-builder plugins such as Elementor have their own Global Colors under Site Settings.
Shopify
Go to Online Store > Themes > Customize > Theme settings > Colors. In Online Store 2.0 themes like Dawn, each colour scheme defines text, background, button and button-label colours. Fix the scheme, not individual sections, and check every scheme that is actually assigned to a section.
Wix
Open the Editor, then Site Design (or Theme Manager) > Colors, and adjust the theme colour slots that text uses. Wix's Accessibility Wizard (Settings > Accessibility) flags some contrast issues, but it is not exhaustive, so verify with axe on the published site.
Webflow
Update colours in the Variables panel, or in the Style panel on the relevant classes (Body (All Pages), headings, buttons, links). Check combo classes and interaction states like hover, which can override the base colour. Publish before re-testing.
Next.js / Tailwind
Change tokens in your Tailwind theme config, or in the @theme block in Tailwind v4 CSS. For example, swap text-gray-400 for text-gray-500 or darker on white backgrounds. Check dark: variants separately. Run @axe-core/playwright in your test suite to block regressions.
Check that it worked
✅ How to verify
- Run axe DevTools or Lighthouse Accessibility on each key template and confirm the color-contrast rule shows 0 violations.
- Run npx @axe-core/cli https://example.com --rules color-contrast --exit and confirm it exits with code 0.
- In Chrome DevTools, inspect formerly failing elements and confirm the colour picker shows a ratio of at least 4.5 (or at least 3 for large text).
- Manually check text over images, gradients and hover/focus states that axe marked as needing review.
⚠️ Common mistakes
- Fixing one element with an inline style while the same colour stays in the theme tokens, so the failure reappears on other pages.
- Treating 4.4:1 as close enough. The threshold is not rounded, so anything under 4.5:1 fails for normal text.
- Assuming 18px text counts as large. Only 24px+ regular or 18.66px+ bold qualifies for the 3:1 threshold.
- Testing only the default state and light mode, while hover, focus, disabled-looking (but active) buttons and dark mode still fail.
Is this still an issue on your site? Run a free audit — ZORO checks this and 294 other SEO, AI-visibility, accessibility and security signals, with fixes for your platform.
Check my site freeFAQ
What contrast ratio do I need to pass WCAG AA?
Normal text needs 4.5:1 against its background. Large text (24px+ regular, or about 18.66px+ bold) needs 3:1. AAA requires 7:1 and 4.5:1 respectively, but most audits and laws target AA.
Do logos and disabled buttons need to meet contrast requirements?
No. WCAG 1.4.3 exempts logotypes, purely decorative text and inactive (disabled) UI components. A button that only looks disabled but is still clickable must pass.
Why does axe say 'needs review' instead of pass or fail?
axe cannot reliably calculate the background behind text on images, gradients, pseudo-elements or overlapping layers. In those cases, measure the contrast against the lightest part of the background behind the text yourself.
Can I fix contrast without changing my brand colours?
Often yes. You can use a darker tint of the brand colour for text only, keep the bright brand colour for large headings or non-text decoration, increase font size or weight so the 3:1 large-text threshold applies, or put text on a darker background.
How to Fix Missing Image Alt Text for Accessibility
How to Fix WCAG 2.2 AA Accessibility Violations on Your Site
How to Fix Form Fields Missing Labels for Accessibility
How to Fix Missing Video Captions on Your Website
How to Fix Buttons Without Accessible Names on Your Site
How to Fix Positive tabindex Values for Keyboard Users