How to Write Alt Text That Actually Works

Alt text is the requirement most often named in accessibility complaints, and it is also the one a machine can check the least. A scanner confirms an alt attribute exists. Some tools go further and flag alt text shaped like a filename, because that is a pattern rather than a judgment. None of them read the chart, so alt="chart" on a chart showing sales falling 40 percent clears the automated checks and tells your reader nothing.

W3C's Decision Tree, in the Order It Actually Asks

There is a published five-question funnel for this, and its first question is not the one people expect. It does not open on whether the image carries meaning. It opens on whether the image contains text, because that case has four different answers and the wrong one is expensive.

1. 1Does the image contain text? Four branches. If the same words appear as real text nearby, the image takes an empty alt. If the text is purely a visual effect, empty alt. If the text has a function, such as an icon, describe the function rather than the letters. If the words appear nowhere else, put them in the alt, and read the section below about what that does and does not fix.
2. 2Is the image inside a link or a button, and would removing it leave the purpose unclear? If so, the alt describes the destination or the action, not the picture.
3. 3Does the image contribute meaning to the page? Three branches. A simple graphic or photograph takes a brief description conveying that meaning. A graph or other complex information needs the information written out elsewhere on the page. Anything redundant to nearby text takes an empty alt.
4. 4Is the image purely decorative, or not intended for users at all? Empty alt. That second half covers tracking pixels and spacer images, which are not decorative in the design sense, they are invisible, and putting words on them only distracts.
5. 5Anything else needs the full images tutorial, because W3C says outright that the tree does not cover every case.

The outcome is always one of two things, an alt text or an empty alt, and there is more than one mechanism for the second. W3C's preferred route for a decorative image is not alt="" at all. It is not putting the image in the HTML in the first place, and delivering it as a CSS background instead. role="presentation" is a third route and is less widely supported than an empty alt. And the failure that runs the other way is worth knowing. Information conveyed only by a CSS background image has no way to carry an alternative at all.

Where the Tree Comes From, and What Else Is On That Shelf

The tree is W3C's, and it lives inside the W3C images tutorial, which is one of six tutorials the accessibility group publishes. The other five cover forms, tables, page structure, menus and carousels. Between them they are the most practical writing W3C has done on this subject. Hardly anybody outside the field has opened one, because they sit two clicks off the standard and end up in bibliographies rather than in front of the person doing the work.

The images tutorial is nine pages, and the seven kinds of image in the next section are its categories rather than ours. It also carries the parts the decision tree has no room for. That an image carrying no alt attribute at all makes some screen readers read out the file name instead. That a long description attached with aria-describedby reaches a listener as one unbroken paragraph, with any headings and tables inside it flattened away. And that logos are exempt from the contrast and text-size requirements other images of text have to meet, which settles an argument most design teams have at least once.

One thing is worth knowing before you follow any of the six end to end. They deliberately combine success criteria and techniques from different conformance levels inside a single instruction, and W3C states that outright rather than leaving you to notice. Every tutorial page then lists the specific criteria it used, so you can check what level any given instruction sits at before committing to it. Follow one straight through and you may build past the level your law actually asks of you, which is a fine thing to do on purpose and a strange thing to do by accident.

The Kinds of Image, and What Each Needs

The last two are the ones our own list used to leave out, and both have their own group technique and hotspot technique. A clickable regional map or an organizational chart with hotspots is an image map in the standard's sense, and it needs alternatives in two places rather than one.

Then, the Words

Six rules cover nearly every case.

1. 1Describe the purpose, not the picture. The same photograph gets different alt text on a travel site and on a university site, because what it is doing there is different. W3C's own paired example is an image of the world, described as International Travel in one place and International Campuses in the other.
2. 2Skip image of and picture of. Screen readers generally announce that it is an image already, so you are making somebody hear it twice. That is convention rather than a rule, and it depends on verbosity settings, and it is still the right habit.
3. 3Keep it to a sentence or so. There is no length threshold in the standard. What there is instead is a pattern. Where an image needs more than a sentence, that is the signal to write a short alt and put the detail in the page.
4. 4Do not repeat the caption, and check what the image adds first. This one has an exception people trip on. A file-format icon inside a download link takes alt="PDF" even though the link text is right beside it, because the format is information the words do not carry. W3C's other worked example is a dog with a bell on its collar in an article about the dog, where the alt covers the bell and nothing else.
5. 5End the thought. Alt text is a sentence somebody hears, so write it as one.
6. 6Never use the filename. IMG_4471.jpg tells nobody anything.

That last one deserves precision, because two different failures get collapsed into it. Alt text that is a filename fails because the text cannot stand in for the image, and the test is loss of information rather than the presence of a file extension. An image with no alt attribute at all is a different failure, and it is the one that actually makes some screen readers read the file name out. So the automated rule that used to test filenames as names has been retired, and alt="dog.jpg" on a photograph of a dog was never automatically a failure. Our own checker flags a file extension because it is a useful signal, not because the extension is the rule.

There is a failure in the other direction too, and it has its own number. Junk alt on a decorative image, so alt="spacer" or alt="image" on something that should be ignored, is distinct from leaving the attribute off. Useful to know when a developer disputes the finding.

Worked Examples

The team photo is the row we changed our minds about, and it is the row most likely to be copied, so it is worth being careful. We used to say alt="" on the grounds that it illustrates rather than informs. W3C's directly comparable example runs the other way. A photograph of a family on a company's website is treated as informative, with the alt text We are family-friendly, because the impression the picture creates is the content.

Both answers are defensible and the deciding test is published. An image is decorative when it illustrates adjacent text without adding information, or when the surrounding text already identifies and describes it. A team photo under a heading naming the team meets that and takes an empty alt. A team photo standing alone as the only thing on the page arguing that a real group of people works here does not, and giving it an empty alt deletes the content.

Charts, Infographics and Anything Complex

The pattern is two parts. A short alt naming what the thing is and, where it helps, saying where the fuller description lives. Then the detail, in the page itself, as a real table or as prose.

How you attach the second part matters more than people expect, and there are four published ways. A text link next to the image. A note inside the alt attribute saying where the description is. A figure with role="group" holding the description in its figcaption. Or aria-describedby for a description that is text only. That last one has a limit that rules it out for the most common case. A description attached that way is announced as one continuous paragraph, with no headings and no table structure, so a data table attached with aria-describedby arrives as an unbroken run of numbers. Use a link beside the image or put the description in the surrounding text.

One failure specific to charts, and it counts twice. Alt text that leaves out what the colors were carrying fails the non-text content rule and the use-of-color rule together. Sales by region, on a chart where each region is a color and the alt never says which is which, is the shape of it.

Putting a data table next to a chart is not a compromise for disabled users. It is usually the better page, and W3C's argument for it names who gains beyond screen reader users. People with low vision, people with learning disabilities, and anybody who is not already expert in the subject. Our charts guide has the rest.

Two Things Nobody Mentions

Alt text has to be in the same human language as the page, and the requirement comes from the conformance rules rather than from the alt text criterion itself. An English alt attribute on a French page is a conformance problem rather than a style slip, and it is a real and common failure on multilingual sites, because alt fields are the last thing a translation workflow picks up.

And alt text goes stale. Not updating the text alternative when the image changes is a named failure, and it is the one that eats any library of pre-written descriptions. An editor swaps the photograph, the alt field stays exactly as it was, and now the page confidently describes something that is not there.

What About AI-Generated Alt Text?

A model looks at a picture and tells you what is in it. Whether that is the right sentence depends on why the picture is on the page, and the answer to that lives in the words around it rather than in the image. So a tool handed nothing but the file is guessing at the half that matters, and one handed the surrounding page does better. Neither of them knows that this photograph is the one your legal team insisted on, or that the chart beside it already gives the number. The same photograph on a travel site and a university site wants different words, and the picture never says which site it is sitting on.

In practice it produces a blue kettle on a white background where you needed a cordless kettle in matte blue, and it will happily describe the photo on your About page that should have had an empty alt. Treat it as a first draft, edit every one, and keep the stale-alt failure above in mind, because a generated library is exactly the kind of thing nobody revisits.

How to Accept Thousands of Generated Descriptions

Run a generator across your whole catalogue and you have swapped one problem for another, because nobody can read ten thousand of anything. The job stops being writing and becomes accepting, and accepting needs a sheet rather than a feeling about how it went. Seven fields, one row per image, and the row travels with the image rather than with the batch.

How Many of Them You Actually Have to Read

Fewer than all of them, and there is no published number that tells you how many is enough, so anybody quoting you a percentage invented it. What you can do is choose the sample on purpose and write down what you chose. Read every image inside a set whose members have to be told apart, so product galleries and staff photographs. Read every functional image, meaning anything that is a link or a button, because those fail hardest and fail silently. Then take a spread of the ordinary ones across templates rather than across pages, since the same slot repeats underneath.

And then read a genuinely random handful on top, which is the step everybody skips. If the random handful turns up a kind of failure your chosen sample missed, the chosen sample was not representative, and you have found that out yourself rather than from a customer. That is the same two-sample logic W3C's evaluation methodology asks for on a website, and it works here for the same reason.

One boundary worth drawing, because we sell something that sits next door to this. The sheet above is a method your team runs over a library you generated, and it samples. Our alt text and image audit is a different shape. It does not sample. It reads your content images page by page and reports what each one says to somebody who cannot see it, and your team still writes the replacement words. So one is a method you run and the other is a review you buy, and the coverage is what separates them. Neither turns a sampled pass into a statement about a whole catalogue, and no sampled result should be written into a supplier questionnaire as though it were one.