Colour contrast checker

Each colour is converted to a relative luminance value, which weights the red, green and blue components according to how the eye responds to them rather than treating them equally.

The ratio is formed from the two luminance values with a fixed offset, producing a number between 1 and 21.

Identical colours give 1. Black on white gives the maximum of 21.

The computation is symmetric: swapping foreground and background gives the same ratio, so which is text and which is background does not change the number.

None of this is a judgement. Two colours always produce the same ratio, which is why this part of accessibility testing is genuinely automatable.

Ordinary body text has the highest requirement, because small glyphs have thin strokes and less area to carry the contrast.

Large text — defined by a point size, or a smaller size at bold weight — has a lower requirement, since the strokes are thicker.

Interface components and graphical objects that convey meaning have their own, lower requirement: a form field border, a focus indicator, an icon carrying information.

Purely decorative content and disabled controls are exempt, which is why a greyed-out button failing the ratio is frequently not a finding.

The enhanced level raises the first two thresholds, and it is the right target for text-heavy reading interfaces rather than a universal one.

Text over a photograph. The background varies pixel by pixel, so there is no single value to compute against and the honest answer is that it needs a human look.

Text over a gradient, for the same reason — one end may pass and the other fail.

Text over a semi-transparent overlay, where the effective background depends on what is behind the overlay at that point.

Colours produced by a state that the scan does not enter: a hover style, a focus style, a themed variant applied by a preference the scan did not set.

In all of these the check reports that it could not establish a background rather than reporting a pass, because a pass it could not compute is worse than an unknown.

A failure with two solid colours is exact and worth acting on immediately. There is no interpretation involved and the fix is a colour value.

A failure on a value just under the threshold is still a failure, and it is usually the cheapest to fix — a small darkening of the text or lightening of the background clears it.

An unknown over an image is a flag for a human, not a pass. Those are frequently the worst contrast on a site, because a hero image with white text over it varies with the photograph.

The same palette failing in many places is one design-system decision, not many defects. Fixing the token fixes every occurrence.

`accessibility.contrast` computes the ratios from the foreground and background colours it can establish, and reports the cases where it cannot establish one.

`mobile.text_size` reports text rendered below a comfortably readable size on a phone, which interacts with contrast: small text at a marginal ratio is harder to read than either problem suggests alone.

`accessibility.focus_visible` covers the focus indicator, whose contrast falls under the interface-component threshold rather than the text one.

Only colours that can be resolved from the served styles are computed. Text over images, gradients and transparency is reported as unestablished.

States the scan does not enter — hover, focus, an alternative theme — are not measured.

Passing the ratio is not the same as being readable. A long line of text at the exact threshold clears the requirement and is still tiring to read.

Contrast is one success criterion. A page passing every ratio can still be unusable for a person who cannot use a mouse.