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.

By Updated ⏱ 45–90 minutes🎯 Intermediate● High impactAccessibility
Illustration: Colour contrast (WCAG 1.4.3) fix guide
ACCESSIBILITY · FIX GUIDE Colour contrast (WCAG 1.4.3) IMPACTEFFORT TIME45–90 minutes LEVELIntermediate

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.

✕BeforeGrey body text #9CA3AF on white(#FFFFFF) gives a contrast ratio of2.54:1, so it fails the color-contrast✓AfterBody text #6B7280 on white gives4.83:1 and passes WCAG AA for normaltext.

What you need

Chrome or Edge with DevTools (or the free axe DevTools extension)
Access to your theme's colour settings or CSS/design tokens
A contrast checker such as WebAIM Contrast Checker
Sign-off from whoever owns the brand palette, if colours will change

Step-by-step fix

1

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.

text
npx @axe-core/cli https://example.com https://example.com/blog/ --rules color-contrast
Pro tip: Failures usually cluster around a few repeated colours, such as footer text, placeholder-style grey, or white text on a light brand button. Group results by colour pair, not by element, and you will often fix dozens of failures with 3–5 changes.
2

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.

Pro tip: Making text bigger is a legitimate fix. A 16px grey label at 3.2:1 fails, but the same colour at 24px passes.
3

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.
Pro tip: Prefer darkening the text rather than lightening the background. It usually needs a smaller visual change to pass.
4

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.

html
: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; }
Pro tip: Run grep -rniE "#9ca3af|#999|#aaa|#ccc" ./src (adjust the values to your palette) to find hard-coded light greys in templates and CSS.
5

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.

html
.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; }
Pro tip: Also check hover, focus, visited and active states, plus dark mode. Each one is a separate colour pair that must pass.
6

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.

Pro tip: Placeholder text is not a substitute for a label. Use a visible label, and keep placeholder colour around #6B7280 or darker on white.
7

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.

text
npx @axe-core/cli https://example.com --rules color-contrast --exit
Pro tip: The --exit flag returns a non-zero exit code when violations are found, so a CI job fails automatically.

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 free

FAQ

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.