A Practical Checklist for WCAG Contrast Before You Ship UI

Color contrast determines whether people can read your interface in ordinary lighting, on imperfect screens, and with common vision differences. Web Content Accessibility Guidelines (WCAG) define measurable contrast ratios for text and for meaningful non-text UI. Teams that wait until launch week to ‘fix contrast’ usually discover that brand tokens, chart palettes, and disabled styles all need redesign—not a 2% lighten pass.

This checklist is practical. It assumes you already picked a visual direction and now need to verify it before release. It is not a full WCAG audit. Contrast is one strand of accessibility alongside keyboard access, semantics, motion preferences, and more. Still, contrast failures are among the most common—and most visible—issues in modern product UI.

Use a contrast checker on real hex or RGB pairs from your design tokens, not on a screenshot guess. Our contrast checker follows the same relative luminance math used in WCAG evaluations so you can validate pairs quickly while designing.

For normal text, WCAG 2.x Level AA expects a contrast ratio of at least 4.5:1 against the background. Large text—typically 18pt regular or 14pt bold and above, with nuances in CSS px equivalents—may meet AA at 3:1. Level AAA raises normal text to 7:1 and large text to 4.5:1. Most product teams aim for AA as a baseline and push critical reading surfaces higher when feasible.

Non-text contrast (WCAG 2.1 Success Criterion 1.4.11) asks for at least 3:1 for graphical objects and user interface components that convey meaning—icons that are the only label, control boundaries that define a clickable region, and focus indicators. Decorative flourishes that convey nothing can be exempt; if removing the graphic would lose information, treat it as covered.

Placeholder text, legal footnotes, and chart axis labels are still text. ‘Muted’ secondary copy often fails AA when designers push zinc-500 on zinc-900 or light gray on white. If the text is meant to be read, it needs a passing ratio. If it is truly optional decoration, reconsider whether it should be text at all.

Before ship, inventory every text style token: headings, body, captions, labels, helper text, error text, and link styles. For each, record foreground and background—including backgrounds that change inside cards, tables, banners, and inverted footer bars. Test the actual pair used in CSS, including opacity. Semi-transparent white text on a photo is not the same as opaque white on a solid token.

Test hover, active, and visited link styles if they change color. Test selected tabs and selected list rows. Test form labels against the input background, not only against the page background. Test table headers and sticky columns that use a slightly different fill.

For text on images or gradients, measure the worst credible region behind the letters or place a solid scrim behind the text and test the scrim color. Marketing heroes fail constantly because body copy sits across bright and dark photo zones without a stable backing plate.

• Body text on default page background
• Muted helper text and footnotes
• Primary and secondary buttons (label vs fill)
• Destructive / error text and icons
• Links default, hover, and visited
• Text inside alerts, toasts, and badges

Icon-only buttons need either a visible label for assistive tech and a contrast-passing glyph, or a text label that carries the meaning. A low-contrast gear icon with no accessible name fails twice. Outline buttons need a boundary that meets non-text contrast against adjacent colors if the outline is how users perceive the control.

Focus rings must be visible. A 1px soft blue ring on a blue primary button can disappear. Prefer a dual-color focus indicator (light and dark ring) or a high-contrast offset ring that remains visible on both light and dark fills. Keyboard users should never wonder where they are.

Disabled controls are tricky. WCAG does not require disabled elements to meet the same contrast as active controls in all interpretations, but if disabled text is still expected to be readable as content, low contrast hurts. Prefer patterns that do not rely on ultra-faint text to mean ‘unavailable’—use explicit ‘Unavailable’ labels or locked states when clarity matters.

Do not encode meaning with color alone. Red and green lines may be indistinguishable for some users even when each line contrasts with the chart background. Add patterns, shapes, or direct labels. Then ensure each series color still contrasts adequately with the plot background and that gridlines do not overpower data.

Status pills—success, warning, danger—often use pale fills with mid-tone text that fails AA. Either darken the text, darken the fill and use light text, or use a stronger border plus bold label. Soft pastel badges are a frequent production failure.

Dark mode is a second theme, not an invert filter. Retest every token pair. Soft gray text that passed on white may fail on near-black. Borders that were subtle on light UI may vanish on dark UI, removing the non-text contrast that defined inputs. Ship dark mode only after the checklist runs on dark tokens.

Add contrast checks when tokens change, when a new component lands, and in visual QA before release. Designers can validate Figma styles; engineers should validate computed styles in the browser because opacity, overlays, and backdrop filters change outcomes.

Define a ship rule: AA failures on body text, form errors, and primary actions are blockers. Borderline marketing flourishes can be tracked as follow-ups only if they are not required to complete a task. Document exceptions with rationale rather than silently shipping failures.

Pair this checklist with a short regression set of screenshots or storybook stories for core flows. Contrast debt accumulates the same way typography debt does—one muted caption at a time—until the product feels washed out and hard to trust.