# Alt text inventory: a guide

> Template version 1.0, 2026-10-07, from https://auricartisan.com/templates/alt-text-inventory/
> Licence: CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/). Copy it, change it and use it for anything; no credit needed.
> This guide goes with alt-text-inventory.csv. Delete the sample rows in the CSV before you start.

A text alternative stands in for an image for anyone who cannot see it: people who use a screen reader, people who turn images off, and anyone whose images fail to load. WCAG 2.2 asks for one that serves the same purpose as the image (1.1.1 Non-text Content, Level A).

The right words depend on what the image does on the page, not only on what it shows. So the inventory records the purpose first, and the words second.

## 1. Decide what the image is for

Ask these questions in order. The first one you answer yes to gives the purpose. They follow the order of the questions in the W3C WAI alt decision tree (https://www.w3.org/WAI/tutorials/images/decision-tree/).

1. Is there text in the image?
   - The same words are on the page as real text nearby: Decorative.
   - The text does a job, such as a letter used as the icon of a button: Functional, as in question 2.
   - Otherwise: Image of text. The alternative is the words.
2. Is the image in a link or a button, and would the link or button be unclear without it?
   - Yes: Functional. The alternative says where the link goes or what the button does.
3. Does the image add meaning to the page?
   - A photo or a simple drawing: Informative. Say what it tells the reader, in a phrase or a sentence.
   - A chart, diagram, map or other image that holds more than a sentence can: Complex. Give a short alternative, and the full information on the page.
   - It shows what the text beside it already says: Decorative.
4. Is the image there only for its looks, or not meant for people at all, such as a spacer?
   - Yes: Decorative.
5. None of these, or you are not sure?
   - Ask the person who put the image on the page why it is there, and read the W3C WAI Images Tutorial (https://www.w3.org/WAI/tutorials/images/).

Two more cases from the tutorial:

- Group of images: several images that carry one piece of information together, such as a row of stars for a rating. Put the alternative on one image and give the others alt="".
- Image map: each clickable area is a link with its own alternative, and the image as a whole has one that says what the map is.

## 2. Write the alternative

- Write for the page, not for the file. The same photo can need different words on a product page and in a blog post.
- Keep it short: usually a phrase or one sentence. Leave out "image of" and "picture of"; screen readers already say that it is an image.
- Do not repeat the text next to the image.
- Functional: the action or the destination, not the icon. "Search", not "Magnifying glass".
- A logo that links to the home page: the name in the logo and where the link goes, such as "Example Shop home".
- Image of text: the words in the image. Then ask whether real text could replace the image (1.4.5 Images of Text, Level AA). A logo is the usual exception, because its look is part of what it is.
- Complex: a short alternative that says what the image is and where the details are, then the details as text or a table on the page. If they are not next to the image, point to them with aria-describedby.
- Decorative: alt="", with nothing between the quotes. Leaving out the alt attribute is not the same thing: a screen reader may then read the file name instead.
- Inline svg has no alt attribute. Give it role="img" and an aria-label, or aria-hidden="true" when it is decorative.
- A CSS background image cannot have a text alternative, so put any information it carries in the HTML.

## 3. The columns

| Column | What to write |
|---|---|
| ID | A short reference, such as IMG-001, to use in tickets and reviews. |
| Page | The page's path, such as /products/oak-side-table/. For an image on every page, say where it is, such as "All pages (header)". |
| Image | The file name and what the image shows: enough to find it without opening the page. |
| Purpose | Informative, Decorative, Functional, Image of text, Complex or Group of images. |
| Current alt | The alt as it is now, word for word. Write (missing) when there is no alt attribute, and (empty) for alt="". |
| Proposed alt | The words the image should have. Leave it empty for a decorative image. |
| Long description | For a complex image, the information the short alternative leaves out. Otherwise leave it empty. |
| Decision | Keep, Rewrite, Mark decorative, Replace with text, or Add long description. |
| Status | To do, In progress, Done, or Checked. |
| Notes | Why you decided as you did, the markup to use, or who must approve the words. |

Give each use of an image its own row, not each file: the same file on two pages can need two different alternatives.

## 4. Review the inventory

1. Find the images. Go page by page, or through a sample of each kind of page, and list every img element, inline svg, icon in a link or button, and CSS background image that carries information.
2. Decide the purpose of each one with section 1 before you write any words.
3. Write the proposed alt with the person who put the image on the page, because they know why it is there.
4. Read each page with its images swapped for the proposed alternatives. The text should make sense in order and say nothing twice.
5. Make the change in the code or the content management system, and set Status to Done.
6. Check it on the live page with a screen reader, in context, and set Status to Checked.
7. Keep the inventory up to date: add a row whenever an image is added, and go through it again after a redesign.

An automated checker can find an image with no alt, or with a file name as its alt. It cannot tell you whether the words are right; only a person who knows the page can.

## References

- WCAG 2.2, 1.1.1 Non-text Content (Level A): https://www.w3.org/TR/WCAG22/#non-text-content
- WCAG 2.2, 1.4.5 Images of Text (Level AA): https://www.w3.org/TR/WCAG22/#images-of-text
- W3C WAI Images Tutorial: https://www.w3.org/WAI/tutorials/images/
- W3C WAI, An alt Decision Tree: https://www.w3.org/WAI/tutorials/images/decision-tree/
- The image alternatives pattern on Auric Artisan: https://auricartisan.com/accessibility-patterns/image-alt/