Writing alternative text.

Alternative text is the text that conveys an image’s information to a user who cannot see it — and writing it well is an editorial decision, not a technical one.

Alternative text is WCAG’s oldest and best-known rule; it is also the most wrongly applied. The reason is not the rule’s difficulty but the fact that no TOOL can audit it. The only question a tool can ask is “is there alternative text”; the question “does this text describe the image correctly” can be answered only by a human.

Alternative text auditing consequently produces almost nothing but green reports, and the real quality is never measured. Sites where the file name serves as the alternative, where meaningless values like “image” or “photo” are used, or where an informative chart is waved through with a single word — all pass the audit without a hitch.

Classify first: what is this image doing

The question to answer before writing alternative text is not which words to choose but what job the image does on the page. The same photograph carries information in one context and is decoration in another — and the correct alternative differs completely between the two.

1. Informative — the image carries information not in the text. The alternative translates that information into text.
2. Decorative — the image contributes only visually and carries no information. The alternative is left EMPTY, not omitted.
3. Functional — the image is the content of a link or button. The alternative describes the FUNCTION, not the image: “Search,” “Home,” “Open menu.”
4. Image of text — an image with writing on it. The alternative carries all of that writing.
5. Complex — charts, tables, flow diagrams. A short alternative says what it is; the detailed explanation lives on the page as text.
6. CAPTCHA — the purpose is stated, not the content. And an alternative verification method must be offered.

Alternative texts written without this classification typically land in the wrong category: a decorative background photo is narrated as “two people working in an office,” and the screen reader user listens to a sentence that serves them nothing; or the magnifier icon in a search button is labeled “magnifying glass,” and the user never learns what the button does.

The empty alternative: marking, not skipping

The correct alternative for decorative images is empty, and this is the most misunderstood rule. An empty alternative tells the screen reader “skip this image,” and the user never hears it. REMOVING the alternative attribute entirely is something else: in that case the screen reader starts reading the file name to compensate for the missing information.

The result is the user listening to a string like “horizontal-line-decorative-2-final-copy dot png.” When the attribute is forgotten, the image does not fall silent — it produces noise. The distinction arises from a single character’s difference — an empty value versus no value — and makes a large practical difference.

On this site the cover plates and background textures are marked exactly this way: being decorative, they carry an empty alternative and are additionally hidden from assistive technology. Together the two guarantee the image never enters the screen reader stream.

An empty alternative silences the image; a missing alternative makes it speak in file names.

Length and content

There is no strict rule for the length of alternative text, but there is a practical limit: the screen reader reads it in one piece and the user cannot pause midway. A paragraph-long alternative is exhausting to listen to. Roughly one sentence, at most two, is a good target.

For images needing long explanation — data charts, flow diagrams, complex figures — the right fix is not lengthening the alternative but putting the detail on the page as text. The short alternative says “quarterly sales chart for 2026”; what the chart tells sits under it as a paragraph or a table. This serves everyone, not just the screen reader user.

There is also the context rule: alternative text must not REPEAT the surrounding text. If the alternative of an image right under a heading is the same as the heading, the user hears the same sentence twice. The alternative should say what the surrounding text does not — if what it would say is already there, the image is decorative in that context.

The practical method: an inventory

The most efficient way to fix alternative texts on an existing site is not walking page by page but building an inventory. A short script listing every image, its current alternative and its surrounding context does half the job.

1. List all images — source, current alternative value, page and nearest heading.
2. Flag the suspects — values resembling file names, containing extensions, containing “image/photo/resim,” or missing entirely.
3. Classify — one of the six categories above per image. This step is human work and cannot be skipped.
4. Mark the decorative ones in bulk — usually the largest group, and fixable in bulk.
5. Write the rest by hand — the informative and functional ones. Fewer in number, but this is the time-consuming part.
6. Make the field required — if the content system cannot save with an empty alternative, the problem never grows back.

The last item is the most important and the one most teams skip. A one-off alternative text cleanup is broken again by the hundred images added over the next six months. Making the field required — or at least warning when it is left empty — stops the problem from recurring.

And a warning: the required field must leave an escape hatch for decorative images. Otherwise content editors type “decorative” or “spacer” into the field they cannot leave empty, and things end up worse than they started. The right design is a checkbox that can mark “this image is decorative.”

Same image, different alternative

The best way to show that alternative text depends on context is placing a single image in different places. Picture a product photo: a blue coffee cup on a wooden table, an open notebook beside it. The same file demands four different alternatives in four contexts — and all four are correct.

1. In a product list, with the product name printed below — alternative EMPTY. The information is already in the text; in that context the image is repetition.
2. On the product page, as the only image — “Blue ceramic coffee cup with a matte finish.” The properties that shape the buying decision.
3. As a decorative header image on a blog post — alternative EMPTY. It gives the article a visual opening and carries no information.
4. As a sample in a color guide — “Side-by-side comparison of matte blue and glossy blue.” That is the image’s FUNCTION on that page.
5. Inside an add-to-cart button — “Add the blue cup to the cart.” It describes not the image but what happens on click.

These five lines also show why alternative text cannot be automated. An image recognition model can describe the photo correctly — “blue cup on a table” — but it cannot know whether that description is useful on this page. Usefulness lives not in the image’s content but in its role on the page.

For the same reason, writing an alternative once in the content management system and reusing it everywhere is wrong too. Alternative text is a property not of the image but of the image’s use ON THAT PAGE. A single value kept at library level cannot be right in every context at once.

Useful beyond assistive technology

The screen reader is not alternative text’s only reader, and knowing this makes the investment in quality economically defensible too. When the image fails to load — network error, blocked resource, slow connection — the browser shows the alternative text on screen. In that moment the text is the only source of information for the sighted user as well.

Search engines read alternative text too and use it as a ranking signal in image search. For answer engines, alternative text is the only machine-readable counterpart of visual content — a model has no other way of knowing what an image on the page shows.

A well-written alternative text thus serves four readers at once: the screen reader user, the visitor whose image did not load, the search engine and the answer engine. Among accessibility items it has one of the highest returns — and its only cost is writing with care.