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

Ethan Moore — Thu, 29 Oct 2026 01:00:33 +0000

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.

Generating Lightweight Terminal GIFs with asciinema, agg, and gifsicle

Ethan Moore — Mon, 26 Oct 2026 14:17:48 +0000

When building small web tools and command-line utilities, I frequently need to demonstrate workflows directly inside project README files and documentation sites. Recording the screen with a generic GUI capture tool often yields bulky files: a 10-second terminal clip can easily balloon to several megabytes, stutter on mobile connections, and introduce blurry text compression artifacts.

To keep documentation snappy, I rely on a pipeline of standard open-source utilities: asciinema to record timing data, agg (asciinema gif generator) to render crisp frames, ffmpeg for palette calculations when fine-tuning, and gifsicle for lossy payload reduction. This workflow keeps terminal recordings sharp and, for short clips, often gets them down to a few hundred kilobytes.

Step 1: Record Text Streams with asciinema

Instead of capturing screen pixels, asciinema records the raw terminal output along with its timing. A pause costs only a timestamp, not a stream of identical frames.

Install asciinema via your package manager and start recording to a local .cast file:

asciinema rec demo.cast

Run your commands naturally. When you finish, press Ctrl+D or type exit.

Before moving to the next step, you can edit demo.cast with any text editor. It is newline-delimited JSON: a header line, then one event per line. You can trim stray events by hand, but for long hesitations it is easier to let tools cap them: asciinema rec --idle-time-limit 2 while recording, or agg's --idle-time-limit when rendering (agg defaults to 5 seconds).

Step 2: Render Crisp Terminal Frames with agg

The agg utility converts .cast timing data into an animated GIF. Unlike a screen recorder, it renders the text itself from a font onto a fixed character grid, using a terminal color theme, so the glyphs come out clean.

Install agg with Cargo or grab a prebuilt binary from its GitHub releases page, then generate a baseline GIF:

agg --fps-cap 12 \
    --font-size 14 \
    --theme monokai \
    --speed 1.2 \
    --rows 18 \
    --cols 80 \
    demo.cast raw.gif

A few flags make an enormous difference here:

--fps-cap 12: agg's default cap is 30 fps. For a text terminal, around 12 fps still looks smooth and produces fewer frames.
--speed 1.2: Speeding up execution slightly keeps visitors engaged without making keystrokes unreadable.
--rows and --cols: Override the recorded terminal size, which keeps the output dimensions predictable. Record at the same size, or long lines will wrap differently.

Step 3: Palette Control with ffmpeg

A GIF frame can use at most 256 colors. If your terminal uses smooth syntax highlighting or gradient progress bars, default conversion algorithms will produce noisy color banding.

When I need tighter control over color mapping than agg provides out of the box, I render a lossless intermediate file or pass the frames through ffmpeg using a two-pass palette generator:

ffmpeg -i raw.gif -vf "fps=12,palettegen=max_colors=64:reserve_transparent=0" palette.png

ffmpeg -i raw.gif -i palette.png -lavfi "fps=12 [x]; [x][1:v] paletteuse=dither=bayer:bayer_scale=3" palette_mapped.gif

By capping max_colors to 64 (or 128 for complex themes) and applying an ordered Bayer dither, the file usually shrinks. Terminal backgrounds stay flat, which gives the subsequent LZW compression algorithm repetitive pixel runs to compress efficiently.

Step 4: Final Shrinkage with gifsicle

The raw output from rendering engines often retains duplicate pixels and unoptimized frame metadata. gifsicle is the standard tool for stripping overhead, dropping redundant frame data, and applying lossy quantization.

Run this compression pass on your rendered GIF:

gifsicle -O3 \
         --lossy=80 \
         --colors 64 \
         --no-extensions \
         raw.gif -o demo_optimized.gif

Here is what these arguments do:

-O3: The highest optimization level. Like the lower levels it stores only the changed part of each frame, but it tries several methods and keeps the smallest (slower to run).
--lossy=80: Allows small visual noise in exchange for massive file savings. gifsicle's docs suggest values around 30 to 200; on dark terminal backgrounds 60 to 80 is usually hard to notice. Compare before and after on your own clip.
--colors 64: Reduces the palette to 64 colors. A smaller palette means fewer bits per pixel and longer repeated runs, so LZW compresses better.
--no-extensions: Drops non-essential extension blocks such as comments and app metadata. gifsicle still keeps the loop setting.

Baseline Reference Numbers

Across my open-source projects, I aim for these constraints:

Target size: Under 800 KB for a 15-second clip.
Frame rate: 12 fps (never exceed 15 fps for CLI tooling).
Color count: 32 to 64 colors for standard mono-like shells; 128 colors maximum for rich terminal UIs.
Dimensions: 80 columns by 16 to 24 rows, agg font size 14.

Text-based capture plus strict frame optimization gives you crisp documentation demos that load fast.

DEV Community: Ethan Moore