Alt text is not just a description of the image

Alt text is the thing everyone thinks they understand and almost no one gets right consistently. The common mental model is: look at the image, describe what you see, put it in the alt attribute. That's not wrong exactly, but it produces bad alt text for a majority of cases.

The correct mental model: alt text should serve the same purpose as the image. Not describe the image. Serve the purpose. Those two things are different, and the difference matters.

Purpose vs. description

Consider a product photo in an e-commerce listing. The image shows a blue denim jacket, folded, on a white background. A description-first approach produces: "Blue denim jacket, folded on a white surface." A purpose-first approach asks: what information does this image convey that isn't already in the surrounding content? If the product name is "Classic Denim Jacket" and there's descriptive text below noting color and material, the alt text might instead be "Front view of the Classic Denim Jacket in indigo," adding the view angle and the specific shade that "blue" undersells.

Or take a different scenario. The same jacket photo appears on a blog post titled "How to style denim this fall." The image is supporting editorial content. Its purpose is to show a styling context, not to convey product specs. The alt text for the same image in that context might be "A denim jacket worn open over a white tee and dark jeans," describing the styling rather than the product.

The image hasn't changed. The appropriate alt text has, because the purpose is different.

Decorative images

Some images genuinely serve no informational purpose. A background texture. An abstract divider line. A stock photo of a laptop on a desk in an article about productivity that doesn't reference the photo. For these, the correct alt text is empty: alt="". This tells the screen reader the image is decorative and to skip it. Omitting the alt attribute entirely is not the same thing. An image with no alt attribute is flagged as a failure by screen readers and automated tools, because the AT doesn't know whether the image has meaning.

The mistake teams make with decorative images is one of two failures: either they assign alt text to genuinely decorative images (screen reader users hear an interrupting description of something that adds nothing), or they mark meaningful images as decorative (screen reader users lose information that was present for sighted users).

The second failure is worse. An icon next to a form field that signals error state, marked alt="" because someone thought it was decorative. A chart in an article about financial performance, marked alt="" because the data felt hard to describe. These are information losses, not accessibility wins.

Complex images

Charts, graphs, diagrams, and data visualizations present a different challenge. The alt attribute can hold a string, but a reasonable description of a line chart showing five years of revenue by product line doesn't fit in a sentence. Trying to compress it produces alt text that's technically present and practically useless.

The correct approach for complex images is a two-part one: a brief alt text that identifies the image's type and subject ("Line chart showing revenue by product line, 2020-2025"), paired with a longer accessible description elsewhere in the page: either in a <details> element below the image, in a <figcaption>, or in the surrounding text. The data in the chart should ideally also be available as a table, both for screen reader users and for anyone who wants to interact with the underlying numbers.

aria-describedby can associate the image with a longer description block elsewhere in the DOM. This works and is well-supported. The usability tradeoff is that the longer description must be visible to be associated. You can't hide it with display: none and reference it. The <details> pattern handles this by letting the description be collapsed by default but present in the DOM.

The caption interaction

When an image has a visible caption below it, the caption and the alt text need to work together rather than duplicate each other. A caption that reads "Greg Sargent presenting at Config 2025" needs an alt that either skips the information the caption already provides ("Photo of the presentation stage") or adds something the caption doesn't ("Presenter gesturing at a slide showing a color system diagram").

What doesn't work: alt text that exactly repeats the caption. Screen reader users hear both. "Greg Sargent presenting at Config 2025. Greg Sargent presenting at Config 2025." This is why alt="" is sometimes correct even for meaningful images, when the caption fully handles the informational purpose of the image and nothing is lost by marking the image decorative.

Functional images

Buttons and links that consist entirely of an image have a different requirement. The alt text for a functional image isn't a description of the image. It's the label for the function. An image of a magnifying glass inside a search button should have alt text "Search," not "Magnifying glass icon." An image of an X inside a close button should have alt text "Close" or "Close dialog," not "X icon" or "White X on gray background."

This distinction matters because the screen reader user is asking: what does this do? The image is the button. The alt text is the button's label. Describing the visual appearance of a button label is as unhelpful as a sighted button that reads "blue rounded rectangle with white text."

What good alt text practice requires

Writing alt text well requires knowing the context: not just what the image looks like, but what it's for, what surrounds it, and what information it carries that isn't already available through text. That's usually a content or design decision, not an engineering one, which is why alt text that gets assigned during production tends to be worse than alt text that's planned alongside the content it accompanies.

The failure mode I see most often in real products: alt text fields treated as optional metadata, filled in by whoever last exported the image to a CMS, with filenames stripped of hyphens, or generic descriptions like "image of woman smiling," or nothing at all. The content author who understands what the image is communicating never gets involved.

Alt text is content. It should be written by whoever writes the other content on the page.