---
name: image-alt-text
description: Write useful alt text for images and mark decorative images correctly. Use when an audit lists images without alt attributes, or when a user asks to improve image SEO or accessibility.
---

# Image alt text

## Facts to use
- Google uses alt text, together with page content and the file name, to understand an image.
- Good alt text describes the image in the context of the page. Avoid keyword stuffing.
- A decorative image (a divider, a background pattern) gets an empty attribute: `alt=""`. Do not leave the attribute out.
- Use `<img>` elements with `src` for images you want indexed. Google does not index CSS background images.

## Workflow
1. List every `<img>` with its page, `src`, current alt and nearby text.
2. Classify each image: content (shows information), functional (a link or button), or decorative.
3. Write alt text:
   - Content image: what it shows that matters on this page, in one short phrase. Example: "Pricing table with Free, Starter and Pro plans".
   - Functional image: the action or target. Example: "Download the report".
   - Logo: the company name.
   - Decorative: `alt=""`.
4. Do not start with "image of". Do not repeat the caption word for word.
5. Rename files with unclear names (`IMG_0042.png`) when the owner can change URLs safely.

## Checks
- [ ] Every `<img>` has an alt attribute.
- [ ] No alt text is a list of keywords.

## Output
A table: page, image src, type, old alt, new alt.

## Sources
- Google: Google image SEO best practices. https://developers.google.com/search/docs/appearance/google-images
- W3C WAI: An alt decision tree. https://www.w3.org/WAI/tutorials/images/decision-tree/
