Low colour contrast

Normal text: 4.5:1 at Level AA, 7:1 at Level AAA.

Large text — 18pt, or 14pt bold, which is roughly 24px and 18.66px bold: 3:1 at AA, 4.5:1 at AAA.

User-interface components and graphical objects needed to understand content: 3:1 against their surroundings. This covers input borders, icon buttons and focus indicators, and it is the criterion most often forgotten.

Exempt: text that is part of a logo, and text in an image that is purely decorative. Incidental text, such as a name on a photograph of a sign, is also outside the requirement.

The ratio is calculated from relative luminance, not from how different two colours look. Two colours that feel very different can measure close, which is why this is computed rather than judged.

Placeholder text in form inputs, which is conventionally light grey and frequently below 4.5:1. It is text, and it carries information, so it is covered.

Disabled controls. WCAG does exempt inactive components from the contrast requirement, but a disabled control whose label nobody can read is still a control nobody can understand.

Text over images and gradients, where the ratio changes across the image. The worst point is the one that counts.

Brand colours used for body text. A mid-tone brand colour that works as a background often fails as text on white, and this is the case that generates the most resistance to fixing.

Hover and focus states, which are frequently styled without being measured — a link that meets the ratio at rest and fails on hover fails.

Dark mode, added later, where a palette designed for light backgrounds is inverted mechanically and every ratio changes.

It computes the ratio exactly when both colours are known: a solid background, a declared text colour, a known font size.

It cannot resolve text over an image, a video or a gradient, because the background is not a single value. Those cases need a person looking at the worst point.

It cannot decide whether text is decorative or incidental, which is where the exemptions live.

It frequently cannot see text that appears only on hover, on focus, or inside a component that has not been opened.

So a clean automated contrast report means the ratios it could compute all pass — a useful and partial statement, and one worth reporting as such rather than as an all-clear.

Browser developer tools show the contrast ratio directly in the colour picker when you inspect a text element, along with whether it meets AA and AAA.

The accessibility pane in Chrome and Edge flags insufficient contrast on individual elements and shows the computed ratio.

For a palette, compute the ratios between every text colour and every background colour once, and record which pairs are permitted. That converts a recurring per-component argument into a lookup.

Test both themes if the site has a dark mode, and test the hover and focus states of every interactive element.

Darken the text rather than changing the brand colour. A brand colour usually survives as a background, a border or an accent; it often does not survive as body text on white.

Add a solid or semi-opaque layer behind text over images. A scrim is visually mild and makes the ratio computable and stable.

Raise placeholder contrast, or better, use a visible label and let the placeholder carry an example rather than the field's name.

Define the permitted pairs as design tokens, so the decision is made once and applied everywhere rather than re-argued per component.

Do not rely on increasing font size to reach the large-text threshold unless the size is genuinely appropriate — 3:1 on text that should have been 16px is a workaround, not a fix.

`accessibility.contrast` computes the ratio for the text it can resolve on each crawled page, comparing the declared foreground against the effective background, and reports the pairs that fall below the WCAG AA thresholds with the element and the measured ratio.

The evidence is the number, not an opinion: each finding carries the two colours and the ratio they produce, so the fix can be verified by recomputing rather than by eye.

Where the background cannot be resolved — an image, a gradient, a video — the check says so rather than guessing, and those elements need a person.