axe-core "color-contrast" insufficient contrast ratio in CI
axe-core rule color-contrast compared the computed text and background colors and their ratio is below the WCAG 2 AA threshold: 4.5:1 for normal text, 3:1 for large text. The message reports the measured ratio and the expected minimum.
What this error means
axe reports "color-contrast: Elements must meet minimum color contrast ratio thresholds" with "Expected contrast ratio of 4.5:1" and the actual foreground, background, and font size for the failing element.
color-contrast: Elements must meet minimum color contrast ratio thresholds (moderate)
Fix any of the following:
Element has insufficient color contrast of 2.53 (foreground color: #999999,
background color: #ffffff, font size: 12.0pt, font weight: normal).
Expected contrast ratio of 4.5:1Common causes
Text and background colors are too close
A light gray on white (for example #999 on #fff) computes to about 2.5:1, well under the 4.5:1 required for normal-size body text.
A design token or theme change lowered the ratio
A palette update or a new muted variant dropped a color pair below AA without anyone measuring the resulting ratio.
How to fix it
Darken or lighten one color to reach 4.5:1
- Read the reported foreground, background, and font size.
- Adjust one color until the pair reaches 4.5:1 for normal text (3:1 for >=18pt or >=14pt bold).
- Verify the new ratio with a contrast checker, then re-run axe.
/* #999 on #fff is 2.53:1; #595959 on #fff is 7:1 */
.muted-text { color: #595959; }Use large-text sizing where 3:1 applies
If the copy is genuinely large text, the threshold is 3:1. Ensure the font size or weight qualifies so the rule evaluates against the lower bound.
How to prevent it
- Bake AA-compliant contrast into design tokens and check pairs when the palette changes.
- Run axe-core on themed and dark-mode variants, not just the default.
- Reserve low-contrast grays for decorative, non-text elements only.