Images missing alt or dimensions

On every live page we count images that are missing alt, OR missing explicit dimensions (width and height). The finding is raised when the share of such images exceeds 20 %. The threshold lives in config/seo.json under seo.SEO-10 (max_missing_alt_or_dimensions_ratio: 0.2), is marked PROPOSAL, and the report gives count and total.

It goes further than STR-05 in the core set, which watches alt only. Dimensions are here because their absence makes content jump around while loading: the browser does not know how much space to reserve, and when the image arrives it shoves the text below it. That is exactly what SEO-21 measures.

An empty alt="" does not count as missing: it is the valid marking of a decorative image. Such an image enters the count only through missing dimensions.

An <img> tag with no source at all has not been counted since 2026-09-19. An empty <img src=""> displays nothing and shifts no layout; in production such dead template leftovers produced four findings reading “2 of 4 images”, where the sensible advice is to remove the tags, not to add dimensions to them. An image enters the count when it has a src or a srcset. The finding text also says separately how many images have no alt and how many have no dimensions.

What the check does not do: it does not judge the quality of the alternative text (alt="image" passes), it cannot see dimensions set in CSS instead of attributes, and it cannot see images inserted via background-image. The finding is page-level; severity is warning.

This code bundles two things with different strengths of evidence, and merging them would be dishonest.

The class of the whole finding is therefore “effect not demonstrated”, meaning for visibility in AI, which is what this audit is about. It does not mean fixing it is optional.

And one thing to take from this finding first: you owe alternative text to specific people who read the web with a screen reader. That is a reason on its own and needs no search engine and no model.

Both are fixed in one pass through the template:

<!-- Wrong: no alt, no dimensions -->
<img src="pump.jpg">

<!-- Right: descriptive alt, dimensions in attributes -->
<img src="pump.jpg" alt="Heat pump installed on the north wall of a house"
     width="1200" height="800">

<!-- Decorative: empty alt, dimensions still yes -->
<img src="divider.svg" alt="" width="800" height="12">

• Dimensions belong in attributes even when CSS controls the size. The browser derives the aspect ratio from them and reserves the space; width: 100% in CSS does not override that, the two work together.
• alt describes what matters about the image, not that it is an image. The measure: what you would say over the phone to somebody who cannot see it.
• Do not 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.
• Fix the template, not the page. A product card without dimensions means one template and a thousand affected pages.