Alt text

Covers a11y.alt-text.

The question to ask

Not "what is in this picture" but "what would be lost if the picture were gone?" Write that.

Every img needs an alt attribute. A missing attribute and an empty one mean different things: a missing one makes assistive technology read out the filename, an empty one makes it skip the image entirely. Empty is a decision; missing is a bug.

By case

Decorative - background textures, dividers, a photo that repeats what the caption already says.

<img src="texture.webp" alt="">

Informative - the image carries meaning the copy does not.

<img src="office.webp" alt="Open-plan office with exposed timber beams and a glass roof">

Inside a link - describe the destination, not the picture. The alt text is the link text.

<a href="/projects/villa-lyon/"><img src="villa.webp" alt="Villa Lyon project"></a>

Text in the image - a logo, a poster, a screenshot with a headline. The alt is the text.

<img src="logo.svg" alt="Colibrity">

Complex - a chart, a map, a diagram. A short alt plus the full information in the page or a linked long description. If the image is the only place the data exists, the data is inaccessible.

Rules of thumb

• Do not start with "image of" or "photo of". The screen reader already said "image".
• Do not stuff keywords. It helps nothing and makes the page hostile to listen to.
• Do not repeat the caption. If the caption already says it, the alt is empty.
• Keep it to roughly one sentence. If it needs a paragraph, it needs a long description.
• Same image, different pages, different alt. Context decides the text.

The bit that cannot be automated

A scanner can tell you every image has an alt. It cannot tell you the text is right. On sites where a client fills the media library, alt text is usually either absent or a copy of the filename, and both pass an automated check on the second one.

The test is to read the page's alt text aloud and ask whether it conveys what the page conveys. That is why this rule is eye-verified, and why the handover should tell the client how to write alt text for the images they add after launch.