How to write good alt text
Alt text (the alt attribute of an image) is what a screen reader reads aloud in place of the image, what shows if the image fails to load, and one of the signals search engines use to understand it. WCAG success criterion 1.1.1 (Non-text Content) requires a text alternative for every image that carries meaning. The best alt text is the one that does the same job as the image, for someone who cannot see it.
- Say what matters here. The same photo of a chef needs different alt text on a restaurant's About page ("Head chef Maria Santos plating a dessert") and in a recipe ("Lemon tart topped with torched meringue").
- Keep it short. One sentence, usually under 125 characters, which is the limit many accessibility guides use. A long alt is tiring to listen to; detail that matters belongs in the page text.
- Skip "image of" and "picture of". The screen reader already announces it is an image. Do say "photo", "illustration" or "screenshot" when the medium matters.
- Include text that is in the image. If a banner says "Spring sale, 20% off", the alt text says it too.
- Do not stuff keywords. Alt text written for people is also what works for image search.
The four kinds of image, with examples
The W3C's alt decision tree sorts images by the job they do on the page, not by what they show. The same logo can be informative in an article about rebrands and functional in a header link.
| Kind | Example | Alt text |
|---|---|---|
| Informative | Product photo on a store page | alt="Oak dining table with six matching chairs in a bright kitchen" |
| Decorative | Divider flourish, background texture, a handshake photo next to the words "Our partners" | alt="" |
| Functional | Logo linking to the homepage; magnifying glass on a search button | alt="Northwind Studio home", alt="Search" |
| Complex | Bar chart of quarterly sales | alt="Bar chart: online sales grew every quarter of 2025, from $40k to $95k", plus the figures in a table below it |
Two mistakes cause most failures. An image with no alt attribute at all is not the same as a decorative one: many screen readers then read the file name, such as "IMG underscore 4021 dot jpg", so decorative images need the empty alt="". And a functional image describes the action, not the picture: "Search", not "magnifying glass". For charts and diagrams, the generator also writes a long description to put in the page text or a caption.
Using AI for alt text, honestly
The model is good at describing what is in a picture and reading text inside it. It does not know who the people are, what your product is called, or why the image is on the page, which is why the context field matters and why you should read every result before you publish it. Treat it as a first draft that saves typing, not as a decision about how the image is used.
Images are also part of documents: check the alternate text in your PDFs with the PDF accessibility checker. Text set inside an image also has to meet contrast rules; test the colors with the color contrast checker.
Methodology and limits
- Model
- Mistral Small 3.1 24B Instruct, a vision language model run on Cloudflare Workers AI, at a low temperature (0.2) so the same image gives similar text. Your context and language choice go into the instruction.
- Rules it is given
- Describe what matters in context in one sentence of up to 125 characters, never start with "image of", include text that appears in the image, write a long description only for charts, diagrams and dense scenes, and say whether the image looks purely decorative. Drafts over 125 characters are cut at a word and flagged.
- Standards
- WCAG 2.2 success criterion 1.1.1 Non-text Content (level A) and the W3C images tutorial. The 125 character limit is a common accessibility convention, not a WCAG requirement.
- Image handling
- Uploads are shrunk in your browser to 1024 pixels on the longest side (JPEG) before sending. JPEG, PNG, WebP and GIF are accepted, checked by the file's bytes rather than its name, up to 5 MB; a GIF is described from its first frame. The image is processed in memory and not stored.
- Allowance
- 15 images per person per day, and a shared daily cap for everyone, so the tool stays free.
- What it does not do
- It does not identify people by name or know your product names, scan your website for missing alt text, decide for you whether an image is decorative in context, or describe video. It can be wrong: read the result before you publish it.
Sources
- W3C's alt decision tree, w3.org
- Cloudflare Workers AI, developers.cloudflare.com
- 1.1.1 Non-text Content, w3.org