Alt text is not a field you fill in. It is the image, written down, for the readers who get it in words.
That reframing is the whole page. An image without alt text is not an image with a missing attribute — it is a hole in the page, and only some readers fall in it. Nobody reports the hole. They just get less of what everyone else got, and we never find out.
This is the standard for every image we publish: pages, posts, glossary entries, broadsides, social posts, and documents. It sits with Form Accessibility as one of the minimum standards for anything that leaves this house.
What alt text is for
A screen reader cannot read a picture. It reaches the image, looks for the alt text, and reads that out instead — to a synthetic voice or a refreshable braille display. So the alt text is not a label attached to the image. For that reader, in that moment, it is the image.
The test is not “did I describe what is in the frame.” The test is: what would be lost if the image vanished, and have I put that back?
That question has a different answer for a book cover, a chart, a meme, a portrait of a friend, and a photograph of a room. The frame does not tell you what matters. The page does.
The decorative trap
The conventional advice says: decide whether an image is decorative, and if it is, give it empty alt text so screen readers skip it.
We think that advice is applied far too widely, and we are not the first to say so.
So just what is a decorative image? It seems to me that one person’s eye candy is another person’s emotional link to a website.
A good alt text can conjure up wonderfully stimulating mental images. A friendly smile is the same in print, photo or wax crayon. Whether you listen to an image or see it, the emotional response is the key factor, so why should we recommend that these emotion rich images should be given a null alt text and hidden from screen reader users?
Perhaps it’s time we introduced another group of images: Emotion rich images and encouraged the practice of providing descriptive alt texts for them. If people don’t want to listen to the alt text, they won’t. If people don’t want to pause and look at the image, they won’t. In either case, it’s good to have the choice.
— Text descriptions and emotion rich images – Tink – Léonie Watson
The usual objection is that describing these images creates noise for screen reader users. Watson, who is one, answers it in the same piece:
It’s sometimes argued that providing such images with descriptive alt texts provides too much “noise” for a screen reader user. If we screen reader users stopped to listen to every alt text, every time we came across an image, then this assumption would probably be right. But I’ll let you into a secret. We won’t.
The noise argument assumes a captive listener. There isn’t one. Describing an image offers something a reader can take or leave; leaving it out removes the choice.
Good alt text means that screen reader users get the same ‘meaning’ from the page as a fully sighted user.
The relevant parts of an image aren’t limited to the cold hard facts. Images can make you feel a particular way, and that’s something that should be made available to a screen reader user.
— Writing great alt text: Emotion matters – JakeArchibald.com
Emotion-rich images get described here. A photograph that sets the mood of a page is doing work. Deleting it for one set of readers is not efficiency, it is an edit — and it is an edit we made on their behalf without telling them.
Genuinely decorative means genuinely nothing: a background texture, a divider, a spacer, an icon sitting next to text that already says the same word. If you find yourself building an argument for why an image is decorative, it is not decorative. It is an image you did not want to write about.
What we found when we counted
We hold that position in public. Then we counted our own images, across every published page, post, and glossary entry on this site.
2,594 images. 1,770 carry alt text. 822 are empty.
Empty alt is the correct choice for exactly 18 of them — cover-block backgrounds sitting behind text. The rest are photographs of our community at events, book covers, portraits, and artwork. A book cover with empty alt text is not a decorative decision. It is a title nobody read to you.
The 822 sit across 99 pages, and 71% of them are concentrated in seven photo-heavy pages. Forty-eight pages have exactly one.
Then we looked at the alt text we did write, and found the shape of the problem:
- Median length: 82 characters.
- Top tenth: 484 characters and up. 576 of them run past the 125-character figure people usually cite as a ceiling.
- Longest: 4,521 characters.
So this is not a knowledge failure. Where we sit with one image and write about it, we write generously — sometimes lavishly. Where images arrive many at a time, we write nothing at all.
Alt text quality tracked attention per image, not understanding. We already knew how. We ran out of looking.
Two more findings, both instructive:
Sixty-four images carry alt text identical to their visible caption. Screen reader users hear it twice. Duplication reads as noise, and noise trains people to skip.
Our longest alt text is not a description. It is a social media post pasted whole — handle, hashtags, “Incoming 🧵” and all — with the actual description of the drawing buried partway in. The information is technically present. Almost nobody will reach it.
That is the other failure mode, and it is worth naming as clearly as the empty ones. The problem is not the length. It is the opening. Watson, writing as a screen reader user, describes exactly how the reader decides:
Like sighted users, we’ll skip around the content of the page until we find something that interests us. If the first few syllables of an alt text sound promising, we’ll pause to read. If they don’t, we’ll move on to the next element on the page.
— Text descriptions and emotion rich images – Tink – Léonie Watson
Our 4,521-character alt text opens with a Bluesky handle. Those are the first few syllables. The drawing never gets its chance.
How we write it
Say what would be lost. Start from the image’s job on the page, not from an inventory of the frame.
Front-load it. The first few syllables decide whether the reader stays or moves on. Put the thing that matters first, and never spend the opening on throat-clearing.
Do not open with “image of” or “photo of.” A screen reader already announced that it is an image. Those are three wasted syllables in the only position that reliably gets heard.
No character limit — the ceiling is a different shape. The 125-character figure is folklore, not spec, and we exceed it on purpose. Length is not the constraint; structure is. A long description that opens well is fine. A short one that opens with metadata is not. When a description is long and needs to be searched, quoted, or re-read, it stops being alt text and belongs on the page.
Never paste. Alt text is written for the image in its place on this page. A caption, a filename, a social post, or a block of source metadata dropped into the field is not a description, however many characters it contains.
Do not repeat the caption. If a caption is visible, the alt text says something the caption does not — or the image gets empty alt and the caption carries it. Pick one. Never both.
Transcribe text that appears in an image. Words in a screenshot, a poster, a meme, or a chart are content. If the text is long, put it in the page as real text and let the alt text describe the object.
Describe people, including race, gender, and disability, when it matters to the meaning. Not as an afterthought, and not by pretending description is neutral. Leaving those details out does not make an image unmarked. It makes it default to whatever the reader already assumes. That is how a page ends up describing some people and not others, entirely by accident. The argument is laid out in We Need Your Help: Specifying Race and Gender in Image Descriptions, archived — The Body Is Not An Apology’s site is currently down. Follow the same identity-first conventions we use everywhere else.
Write the feeling, not only the inventory. This is the Léonie Watson point made operational. If the image is on the page because it is warm, funny, defiant, or sad, the alt text is allowed to be warm, funny, defiant, or sad.
Describe charts by their finding, not their axes. “Funding by disability category, 2020–2024” is a label. The finding is what the chart is for. If the finding needs a paragraph, write the paragraph on the page and let everyone have it.
Never stuff keywords. Alt text is not a place to do SEO. Somebody is listening to it.
Empty alt is a decision you make out loud. alt="" is correct for pure decoration, and it is a real tool — but write it deliberately, not by leaving the field blank. An image that was never considered and an image that was considered and dismissed look identical in the markup. That is exactly why 822 of ours are ambiguous.
When alt text is the wrong tool
Alt text is one of several ways an image can reach a reader, and reaching for it by default is how it ends up overloaded.
- Captions are visible to everyone. If a description is worth reading, consider giving it to all readers rather than only the ones using assistive technology.
- Long descriptions belong in the body of the page — under the image, in an accordion, or in a lily pad. Complex charts, diagrams, and comics need this.
- Describing the image in the surrounding prose is often the best answer, and it makes the alt text short or unnecessary. Nobody is excluded from body text.
- Transcripts carry text-heavy images, and are the right home for anything a reader might want to search or quote.
The bias should run toward putting description in the page where everyone gets it, and using alt text for what is left.
Beyond this website
The standard does not stop at our own markup.
Social posts. Bluesky, Mastodon, Instagram, LinkedIn, and Facebook all support alt text. We write it every time. A post with an unlabeled image is a post part of our community cannot read.
Documents. PDFs, Word documents, Google Docs, and slide decks all carry alt text, and all of them ship without it by default.
Print. A broadside has no alt text — paper has no assistive layer, as Designing for Paper works through at length. That is a reason to keep the meaning in the words on the sheet rather than in the picture, and to make sure the web version of any printed thing carries what the paper cannot.
Keeping a bank of reusable descriptions for the images we publish repeatedly — the logo, the mascot, the wheelchair-and-umbrella — is worth the ten minutes. The A-Z of Effective, Inclusive Campaigns recommends this, and it removes the excuse most likely to win on a bad day.
Where this stands
We are writing this down partly to hold ourselves to it, the same way we did with motion.
Done. The standard is written, and it now lives in one place instead of as two quotations inside Page Conventions.
In progress. 804 images carry empty alt text that nobody chose, and 71% of them sit in seven pages. They are being worked through page by page. The photo-heavy pages are the biggest job and the biggest win.
The rule we did not have. Count it. A practice you cannot count is a practice you are not running — the same lesson the motion audit taught us, arriving a second time from a different direction. “We write alt text” was true and also 32% wrong, and we could not have told you which until we added it up.
If you hit an image on this site that told you nothing, tell us. We would rather hear it than keep publishing holes.
Sources
- Alt Text as Poetry — the workbook that treats description as a creative act rather than a compliance burden.
- Text descriptions and emotion rich images – Léonie Watson
- Writing great alt text: Emotion matters – Jake Archibald
- An alt Decision Tree – W3C Web Accessibility Initiative
- We Need Your Help: Specifying Race and Gender in Image Descriptions – The Body Is Not An Apology — via the Internet Archive; the original site is down.
- How to Write Alt Text and Image Descriptions – Perkins School for the Blind
- Image Alt text best practices – Siteimprove
- The A-Z of Effective, Inclusive Campaigns