How to fix color contrast on Headless / Custom (I build in code)

Steps for Headless / Custom (I build in code)

1. Use browser DevTools to find the CSS class or variable controlling the failing text color.
2. Open your design-token or variables file (e.g. _variables.scss, tokens.css, tailwind.config.js) and update the color value to one that passes 4.5:1.
3. If using a utility-class framework like Tailwind, swap the class (e.g. replace 'text-gray-500' with 'text-gray-700') — verify the new class passes contrast.
4. Commit, build, and deploy. Re-run your accessibility scanner to confirm.

What is color contrast?

Color contrast is the difference in brightness between text and the background behind it. WCAG (Web Content Accessibility Guidelines) Success Criterion 1.4.3 requires that normal-sized text (below 18pt / 24px regular, or 14pt / ~18.5px bold) has a contrast ratio of at least 4.5:1 against its background. A ratio like 4.47:1 — for example, #777777 grey text on a white #ffffff background — falls just short of that threshold and is therefore a measurable accessibility failure. The ratio is a simple math score: higher numbers mean more contrast and easier reading.

Approximately 1 in 12 men and 1 in 200 women have some form of color vision deficiency, and many more users struggle with low contrast in bright sunlight or on older screens. Failing WCAG 1.4.3 exposes your store to legal risk in the US (ADA), UK (Equality Act), EU (EAA 2025), and other jurisdictions that reference WCAG as the accessibility standard for commercial websites. Beyond legal compliance, hard-to-read text directly hurts conversions: shoppers who can't comfortably read product descriptions, prices, or call-to-action buttons abandon faster. Google also uses accessibility signals as part of its Core Web Vitals and overall quality assessment, so fixing contrast issues can have a positive downstream effect on organic rankings.

See the complete Color contrast guide for every platform and the full background.