Writing alt text for animated images in docs (a short checklist)

Animated GIFs and short looping videos are everywhere in READMEs and docs now: a terminal demo, a UI flow, a before/after. Most of them ship with alt text like demo.gif or screenshot, which tells a screen reader user nothing.

Here's the checklist I've settled on after rewriting the alt text in a few of my own projects.

1. Describe the outcome, not the frames

A screen reader user doesn't need "cursor moves to the button, button turns blue, modal opens". They need what the animation proves.

• Weak: Animation of the app
• Better: Running the init command creates a config file and prints three setup steps

If the GIF exists to show "it works in one command", say that.

2. Keep it short, move detail into the text

Alt text is read in one go and can't be skimmed. I aim for one sentence. If the animation shows a multi-step process, the steps belong in the surrounding prose or a numbered list, where everyone benefits from them, and the alt text can just summarise.

3. Mention text that appears on screen

If the animation types out a message, shows an error, or displays a result value, include that text. It is often the most important part and it is invisible to assistive tech otherwise.

4. Don't start with "GIF of" or "Image of"

Screen readers already announce that it's an image. Start with the content.

5. Decorative loops get empty alt

A purely decorative animated banner should have alt="" so it is skipped, rather than a description nobody needs every time they land on the page.

6. For video, the same ideas apply in different places

For a <video> you don't have alt, so:

• give it a short aria-label or a visible caption that states what it shows,
• write alt text for the poster image if it is meaningful,
• add captions if there is speech, and
• respect prefers-reduced-motion and avoid autoplaying long loops for users who opted out of motion.

7. Read it out loud once

The quickest test: read the page out loud and replace each animation with its alt text. If the paragraph still makes sense, you're done.

---

None of this takes long, and it's one of the few documentation improvements that's almost free. If you have a rule of thumb I missed, I'd like to hear it in the comments.