A reliable WCAG color contrast check covers more than a paragraph of body text. This guide gives you a repeatable workflow for testing text, controls, icons, focus indicators, transparency, gradients, and dark mode before a frontend release.
Overview
Color contrast describes the difference in perceived brightness between a foreground color and its background. A contrast checker can calculate a ratio, but the result is only useful when you test the right state, component, and visual context.
For a practical audit, identify the exact foreground and background colors, determine whether the content is text or a non-text interface element, and test every meaningful state. A button may pass in its default state but fail on hover. A focus outline may be visible on a light page and disappear on a dark card. A brand color may work for large headings but not for small body copy.
Use a browser inspector or color picker to capture the colors rendered on screen, then enter those values into a WCAG color contrast checker. Do not rely only on design-file values: CSS opacity, overlays, inherited styles, images, gradients, and theme variables can change the final appearance.
Common contrast requirements
| Content or component | Common AA target | What to check |
|---|---|---|
| Normal-sized text | At least 4.5:1 | Body copy, labels, navigation, form instructions, and most links |
| Large text | At least 3:1 | Text that qualifies as large under the applicable WCAG definition |
| Meaningful icons and UI boundaries | At least 3:1 | Controls, input borders, status icons, and other essential non-text visuals |
| Enhanced text target | At least 7:1 for normal text; 4.5:1 for large text | Use when your product targets a higher level of text contrast |
These are practical comparison points, not a substitute for checking the conformance target and exceptions that apply to your product. Contrast alone also cannot confirm that a design is understandable or usable.
Checklist by scenario
1. Body text, headings, and links
- Capture the rendered text color and the actual background behind it.
- Test normal copy separately from large headings; do not assume a heading size makes every nearby label pass.
- Check links in their default, hover, focus, visited, and disabled-looking states.
- Make sure links are identifiable without color alone, using an underline or another clear treatment where appropriate.
- Test muted text carefully. Secondary labels, placeholders, helper text, and timestamps often use lighter colors than the main copy.
2. Buttons, fields, and other controls
- Test the button label against the button background, including primary, secondary, destructive, and disabled variants.
- Check hover, pressed, selected, loading, error, success, and focus states.
- Test input text, placeholder text, borders, icons, and validation messages independently.
- Verify that an input boundary or another visual cue remains distinguishable when the field is not focused.
- Check controls on both neutral page backgrounds and colored cards, banners, or modal surfaces.
3. Icons, illustrations, and status indicators
- Test an icon when it conveys meaning or identifies an interactive control.
- Check the icon against the surface immediately behind it, not the page background several layers below.
- Do not communicate success, warning, error, or category through color alone. Pair color with text, shape, position, or an accessible name.
- Review thin strokes and small details at normal zoom. A nominally passing ratio may still produce a weak visual signal when the mark is tiny or low-weight.
4. Focus indicators and keyboard navigation
- Navigate the interface with a keyboard and record every focusable component.
- Check the focus indicator against the adjacent background and against the component itself where both affect visibility.
- Test focus on cards, tables, dark surfaces, images, gradients, and elements near the viewport edge.
- Ensure focus is not removed by a reset or replaced with a subtle color change that is difficult to see.
- Review the indicator at different zoom levels and with both light and dark themes enabled.
5. Dark mode and alternate themes
- Audit dark mode as its own palette rather than assuming light-mode tokens will invert safely.
- Test text on elevated surfaces, nested panels, borders, links, code blocks, and notification components.
- Check whether semi-transparent white or black overlays create unexpected ratios over different surfaces.
- Compare the same component across system settings, app themes, and any high-contrast or forced-color behavior relevant to your audience.
- Confirm that icons, focus rings, charts, and status colors remain distinguishable in every theme.
6. Images, gradients, and transparency
- Test text at the lightest and darkest areas behind it when a background image or gradient changes across the component.
- Use a solid scrim, text panel, or alternate layout when no single foreground color can pass over the full background.
- Inspect the computed result in the browser when opacity is applied to text, a parent, an overlay, or a pseudo-element.
- Do not treat a contrast result from a flat color swatch as proof that the rendered component passes.
What to double-check
Record findings in a color-audit log so contrast decisions can be reviewed after a palette or component change. A compact reusable template can include:
- Component: for example, primary button, error message, card link, or focus ring.
- Location and state: page, theme, viewport, default, hover, focus, pressed, disabled, or error.
- Foreground value: the rendered color, including an alpha value when relevant.
- Background value: the surface immediately behind the content or indicator.
- Contrast ratio: the checker result and the target being applied.
- Issue and remedy: such as darken text, lighten the surface, add an outline, increase stroke weight, or add a non-color cue.
- Status: open, fixed, retested, or accepted exception with an explanation.
Use browser DevTools to inspect computed styles rather than only source variables. Then retest the rendered page at normal zoom, keyboard-only navigation, and common responsive widths. Automated checks are useful for finding obvious failures, but they may miss text over images, state coverage, meaning conveyed by color, and whether a focus indicator is actually noticeable.
When a contrast issue is found, prefer a token-level fix where possible. Updating a semantic color token can correct many components consistently, while changing one isolated selector may leave the design system with the same problem elsewhere.
Common mistakes
- Testing only the default state: Hover, focus, selected, and error states can use different colors and need separate records.
- Checking the wrong background: A text label inside a translucent card may be rendered over an image or gradient rather than the page color.
- Assuming large text solves everything: Nearby labels, icons, borders, and controls still require their own checks.
- Using color as the only signal: Add text, icons, patterns, underlines, or clear state labels where color carries meaning.
- Ignoring focus: A visually polished interface can still be difficult to operate if the keyboard position is unclear.
- Treating disabled controls as irrelevant: Even when a disabled state has different requirements, it should remain understandable and distinguishable from ordinary content.
- Relying on one palette preview: Theme changes, browser rendering, opacity, and component context can alter the final result.
- Fixing a color without checking brand intent: If a brand color fails for small text, reserve it for larger text, fills, borders, or decorative use and choose a related accessible text token.
When to revisit
Run the full checklist before a new frontend release and whenever you change brand colors, design tokens, typography, component states, illustrations, imagery, or theme behavior. Recheck after launching dark mode, adding a new component library, changing browser-support assumptions, or resolving an accessibility regression.
For ongoing maintenance, sample every component variant during routine development and keep the audit log beside the design-system or frontend documentation. Revisit the workflow when your accessibility target, testing tools, browser behavior, or applicable guidance changes. A six-month editorial review is a practical reminder for this guide, while product teams should test sooner when their inputs change.
Action plan: choose one representative page, inspect its rendered colors, list every interactive state, run each foreground/background pair through a contrast checker, test keyboard focus, and record the result. Fix shared tokens first, retest light and dark themes, then expand the same checklist to the remaining components before release.