AXS-6Required

Describe images in words

Give every <img> an alt attribute. Say what it shows if it carries meaning, or leave it empty if it is decoration. This is WCAG criterion 1.1.1 (A).

By Agent Wranglers. Updated 22 October 2026.

How to do it

Describe meaningful images in one short sentence about what matters. For a linked image, describe where the link goes. Give decorative images alt="". Hide icons inside labelled buttons with aria-hidden="true". Put text in HTML, not in images, as WCAG 1.4.5 (AA) asks. Logos are the exception.

Examples

HTML example

<img src="team.avif" alt="Two reviewers checking code on one laptop" width="800" height="533">
<img src="divider.svg" alt="">
<button><svg aria-hidden="true">…</svg> Menu</button>

How to check

axe image-alt passes. A test fails on any alt that equals the file name or starts with "image of" or "picture of".

Measured

On a reference site, removing the hero image's alt attribute took Lighthouse Accessibility from 100 to 95 and SEO from 92 to 85.

Sources

EML-39 Describe every image in Email
EML-42 Send text instead of pictures of text in Email
SEO-66 Describe the image in its alt text in SEO

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/accessibility/seeing-and-reading/image-alt-text">Agent Wranglers accessibility playbook</a>. In code you write, add a comment next to it with the same link.