How to write useful alt text

1. Decide what the image does here

Open one page and list its images, including linked logos, icons inside controls, and content added by a template. For each image, finish this sentence: “The reader needs this image to…” If you cannot finish it, check whether the image is simply decoration.

• Information: write the detail a reader needs to understand the surrounding content.
• Action or destination: make sure the control or link has a name that describes its purpose.
• Decoration or repetition: an HTML image can use an empty alternative, alt="", when it adds no information beyond the adjacent text.
• Complex information: provide a short alternative and put the fuller explanation in accessible page content.

The W3C alt decision tree helps distinguish these cases. Empty alt text is a deliberate choice; omitting the attribute is a different thing.

2. Write the information the reader needs

Imagine a visitor information page with a photo showing a building entrance. If the photo explains how to reach reception, a useful alternative might identify the entrance and the route. If the surrounding paragraph already gives the same directions and the photo adds nothing, repeating the paragraph would add noise.

<img
  src="reception-entrance.jpg"
  alt="Reception entrance beside the courtyard, reached by the path on the left"
  width="960"
  height="640"
>

This is an illustrative image description. Use it only if it matches the actual image and page. Do not infer a step-free route, an identity, or a facility from a photograph when you cannot establish that fact.

Draft the alternative, then read the nearby heading, paragraph, and alternative in sequence. Remove repeated introductions and keep details that change what the reader understands. A screenshot showing a setting can identify the selected option; it usually does not need a tour of the browser toolbar. W3C's informative image guidance explains why meaning depends on context.

3. Give linked images a useful destination

For an image that is the only content of a link, the alternative needs to explain where the link goes. Describing a small house shape does not tell someone which site or page it opens. When visible text already names the destination inside the same link, the image can often have an empty alternative.

<a href="/visit">
  <img src="courtyard-thumbnail.jpg" alt="" width="80" height="60">
  Plan your visit
</a>

Keep that text inside the link, rather than placing it in a separate paragraph. Inspect the resulting accessible name in the browser's accessibility tools and check it in the link's context. For icon buttons, use a native button with a clear visible label where possible. See W3C's functional image examples for the distinction between an image's appearance and its function.

4. Move long explanations into the page

A route map, process diagram, or detailed chart may contain more information than one short alternative can convey. Give the image a concise identifier and explain the important relationships nearby. Readers should be able to find the explanation without relying on visual position alone.

For a visitor map, that could mean a heading called “Route from the station” followed by the turns, entrances, and landmarks in order. For a chart, include the relevant values in a properly headed table and explain the trend in text. Do not put an entire table into one alt attribute.

Make the description part of content maintenance. When the map changes, review the route instructions in the same change. W3C's complex image tutorial describes ways to provide short and detailed alternatives together.

5. Check the published result

1. Read the page with the image alternatives in context. If you use a screen reader, check the announced name and whether a decorative image adds unnecessary speech. Record the browser and assistive technology used.
2. Inspect the rendered HTML. Confirm the CMS saved the alternative on the intended image and did not reuse a media-library default in an unsuitable context.
3. Open links and operate buttons with the keyboard. Confirm their names match their actual actions.
4. Check another page using the same image or template. An image reused in a different context may need a different alternative.

Keep a short record for the editor: page URL, image location, its purpose, proposed alternative, and the person who will check the final page. An observation such as “The entrance photo adds directions missing from the paragraph” gives a reviewer something specific to verify. Record it only when you have observed it.

6. Separate missing text from useful text

An automated rule can detect certain missing image alternatives. It cannot decide whether a valid-looking description tells the right story or whether an image really is decorative. Deque's image-alt documentation explains the rule and the use of an empty alternative for decorative images.

Use a WebAccez finding to locate the image and begin the review above. After changing the content, run a new scan and repeat the contextual check. A cleared automated finding means that particular check no longer reports the problem on the scanned content. Keep your editorial judgment separate from that result, and leave images on unvisited pages marked as unreviewed.