Skip to content

D0006 image-alt

Rule: Every image has alternative text.

Code D0006 (stable, never reused)
Id image-alt
Category reading
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn an image without alternative text tells a screen reader, a search engine and a broken link nothing
small-workspace warn an image without alternative text tells a screen reader, a search engine and a broken link nothing
medium warn an image without alternative text tells a screen reader, a search engine and a broken link nothing
big warn an image without alternative text tells a screen reader, a search engine and a broken link nothing
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Why

Alternative text is what a screen reader reads aloud, what a search engine indexes, and what the reader sees when the image does not load. An image without it tells those readers nothing.

![](board-top.png)                          <- nothing to read
![The board from the top, USB on the left](board-top.png)

In Markdown an image always has its text between the brackets, so empty brackets are reported. An HTML <img> is reported when it has no alt attribute at all. alt="" marks an image that is only decoration, and is left alone.

How to fix

Write what the image shows, in the words a reader would need if they could not see it. For an image that only decorates, use HTML with alt="".

Configure

[lints.image-alt]
level = "deny"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(image-alt) <reason> (waivers); the code works there too, as in [lints.D0006].