Generated alt text, reviewed: three rules before the prompt

Generated alt text is a draft: it describes what the model sees, not what the image is for on the page. Review it, shorten it, and sometimes delete it.

Three rules worth more than the prompt

• Purpose, not pixels: "button that opens the filters", not "grey icon with three lines".
• Decorative, empty: when the image repeats the nearby text, an empty alt is the correct answer.
• Short: under 125 characters it is heard in full; beyond that the screen reader gets interrupted.

grep -o ']*>' dist/index.html | grep -vc 'alt='

The command counts images without an alt attribute in a built HTML file: it is the first check, not the last. An empty alt and a missing alt look the same on the page and are two different things in the DOM.

The review round

Generate, then compare with the page: every alt that names a colour or a shape without saying what the image is for has to be rewritten. Review costs more than generation, and it is the only part that improves the result.

import { generateText } from 'ai';

const alt = await generateText({
  model: 'openai/gpt-6-luna',
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'Write alt text under 125 characters. State the purpose, not the pixels. If the image is decorative, answer exactly: decorative.',
        },
        { type: 'image', image: new URL(imageUrl) },
      ],
    },
  ],
  maxOutputTokens: 60,
});

console.log(alt.text);

What not to delegate

• Text inside the image: the model transcribes it with errors; the alt must carry it exactly.
• Proper names: a person or a brand half-recognised is worse than no name at all.
• Charts: a chart needs its data and its conclusion, not a description of the shape.

The limitation

The model never sees the page: without the text around it, it produces generic captions. And no public metric measures alt quality, so the check stays a human reading, page by page.

Where to continue

The full check is in an accessibility audit, recurring mistakes in common WCAG errors, the headless library comparison in Radix, Base UI and React Aria. The records: 12,808 icons, 111,985 components, 1,556 blocks.