Images without alternative text

On every live page the images are counted, and among them those missing the alt attribute entirely. The finding is raised when the share of missing ones exceeds 20 %. The threshold lives in config/thresholds.json under rule_engine.STR-05 as max_missing_alt_ratio: 0.2 and is marked "_status": "PROPOSAL" (our estimate pending revision, not a number from the specification). The reason for having a threshold at all is simple: one image in fifty is not worth a finding; half of them are.

An empty alt="" does not count as missing, and that matters. It is the valid and correct way to mark a decorative image: the author is telling a screen reader and a model “this image carries no information, skip it”. A site that labels its decorative images properly must not be penalised for it.

What the check does not do:

• It does not judge the quality of the text. alt="image", alt="IMG_2931.jpg" or alt="." pass exactly like a careful description. This is the most common way to “fix” the finding while improving nothing.
• It cannot see images inserted through CSS (background-image). Those cannot have an alt at all, and if you carry content in them, that is a problem this check says nothing about.
• It does not weigh importance. A footer icon counts the same as a product photograph.
• It checks neither <svg> nor <canvas>, although those should carry an accessible name too.
• It never runs on pages with an error status.

The finding is page-level; severity is warning. A full accessibility analysis is done by a separate audit module with its own A11Y-… codes; this check is a coarse sieve in the core set.

Let us split this by who the alternative text serves: the strength of the evidence differs per group, and merging them would be dishonest.

The class of the finding as a whole is therefore “effect not demonstrated”, meaning for visibility in AI, which is what this audit is about. It does not mean alternative text is pointless. It means the reason to add it lies somewhere other than where people tend to look for it.

And that reason is worth more than our score. Alternative text is the one thing in this entire audit that you owe to specific people rather than to an algorithm. If one thing from this finding should stick, let it be that.

For each image, decide which of two groups it belongs to. It is not about how important it is, but whether it carries information that is not in the text anyway:

1. A content image: a product photo, a chart, a screenshot, an infographic. It needs an alt describing what matters about it.
2. A decorative image: a divider, an ornamental background, an icon beside text that says the same thing. It gets alt="", empty, not omitted.

For the first group, one measure works better than any rule about length: write what you would say over the phone to somebody who cannot see the image.

<!-- Wrong -->
<img src="chart.png">
<img src="chart.png" alt="chart">
<img src="chart.png" alt="sales chart image diagram statistics graph">

<!-- Right -->
<img src="chart.png" alt="Sales rose from 120 units in January to 340 in June.">

<!-- Decorative: empty alt, not omitted -->
<img src="divider.svg" alt="">

What to watch out for:

• Do not start with “image of…” or “photo of…”. The screen reader has already announced it is an image; repeating it doubles the information.
• For a chart, describe the conclusion, not the appearance. “A bar chart with six bars” helps nobody; “Sales tripled” does.
• When an image is also a link, the alt describes the link's destination, not the picture. So a logo in the header takes alt="Home" or the site name, not “logo”.
• Do not stuff keywords. Google explicitly discourages it: filling alt attributes with keywords results in a negative user experience and may cause your site to be seen as spam.
• Never add alt in bulk with a script. alt="image" on a thousand images clears the finding and helps nobody, and from then on the site looks fixed while it is not.

And as with the other structural findings: fix the template. A missing alt on a product card usually means one template and a thousand affected pages.