Text with insufficient contrast against its background

The page is loaded in a real browser and visible texts are walked (at most 400 nodes per page; texts shorter than 2 characters are skipped). For each, the contrast ratio between the text colour and the background is computed and compared against the WCAG requirement: 4.5 : 1 for ordinary text, 3 : 1 for large text.

“Large text” means 24 px and above, or 18.66 px and above in bold; that definition comes from the standard, not from us. The report gives the number of failing pairs, the total, and the share.

Severity is dynamic: when more than 30 % of the judged pairs fall below the threshold (config/colors.json#severity.color01_critical_ratio), the finding is raised to critical. Otherwise it is a warning.

What the check does not do: it does not judge text on an image, it does not compute contrast against a gradient or a photograph behind the text (it takes the background colour as the browser reports it), and it cannot see states such as hover or focus. The finding is page-level.

For visibility in AI answers there is no effect at all: text colour is a property of rendering; the text in the HTML is the same. Hence “effect not demonstrated”, the only honest classification given what this product measures.

At the same time it is the code with the hardest backing of all the paid-module codes; the backing is just somewhere other than where the rest of the audit looks. 4.5 : 1 is a normative requirement of WCAG 1.4.3, level AA, and in Europe it is part of accessibility legislation. It is not a recommendation and not a convention.

Who it affects: people with low vision, with cataracts, older users, and everybody else, any time they read a phone in sunlight. Low contrast is not an aesthetic choice, it is a barrier.

Where our measurement is weaker than it looks, and it is fair to know: we take the background colour as the browser reports it. Text laid over a photograph or a gradient is therefore judged against the colour beneath it at that point, not against the worst spot. For such elements, trust your own eyes rather than our number.

The practical conclusion: fix this finding even if somebody bought the audit for AI. It is the one paid-module item that you owe to specific people.

First find out whether it is one colour used in many places or many different problems. It is nearly always the former: one shade of grey in the design that was never followed through.

Typical cases, in order of frequency:

1. Light grey text for “less important” information: labels, notes under a form, an article's date. It looks delicate and it is the single commonest cause.
2. Text on a coloured button: white on light orange or yellow rarely passes.
3. Links in the brand colour on white, when that colour is light.
4. Text on an image with no backdrop.

The fix is darkening the text or lightening the background until the ratio passes. The difference is smaller than expected: from #999999 to #767676 on white is the difference between 2.8 : 1 and 4.5 : 1, and the eye barely notices.

• Do not raise contrast by bolding the text. Bold lowers the requirement only above 18.66 px; on small text it does not help.
• For text on an image, put a backdrop under the text: a translucent layer or a solid panel. A text shadow is unreliable.
• Check states separately. A link on hover often turns lighter and the standard applies there too; our check cannot see it.
• Fix in variables, not per site. With colours in CSS variables it is one change; scattered, it is fifty.