alt-text-design

name	alt-text-design
description	Write meaningful alternative text for images, charts, diagrams, and visual content. Use when creating or reviewing alt text, image descriptions, chart summaries, or any visual content that needs a text equivalent. Triggers on: alt text, image description, alternative text, screen reader, decorative image, chart description, infographic, data visualisation, complex image, meaningful alt.

Alt Text Design

Write alt text that conveys the same information and purpose as the visual content — not just what the image looks like, but what it communicates.

Core Principle

Alt text answers the question: if this image disappeared, what information would be lost? That's what needs to be in the alt text.

Decision Tree

1. Is the image purely decorative?

• Background textures, dividers, visual flourishes
• Images that repeat information already in adjacent text
• Action: use empty alt (alt="") so screen readers skip it

2. Is the image functional?

• A linked logo, an icon button, an image link
• Action: alt text describes the function, not the image
• Logo linking to homepage: alt="Company name — home"
• Search icon button: alt="Search"
• NOT alt="magnifying glass icon"

3. Is the image informative?

• Photos, illustrations, screenshots that add information
• Action: describe the information the image conveys
• Photo of a damaged product: alt="Crack running along the bottom edge of the screen"
• NOT alt="Photo of a phone" or alt="product-image-032.jpg"

4. Is the image complex?

• Charts, graphs, diagrams, infographics, maps
• Action: short alt text summarising the key message PLUS a longer description nearby (in the page text or a linked detail)
• Bar chart: alt="Bar chart showing sales growth — details below" followed by a text summary of the data
• NOT alt="bar chart" and not the entire data set in the alt attribute

Writing Good Alt Text

Be Specific

• Bad: "A group of people"
• Good: "Three team members reviewing a prototype on a whiteboard"

Convey Purpose, Not Just Appearance

• Bad: "Red circle with a number"
• Good: "3 unread notifications"

Match the Context

The same image needs different alt text in different contexts:

• On a recipe page: "Finished risotto in a white bowl, garnished with parmesan and basil"
• On a kitchenware product page: "Round white ceramic serving bowl, 22cm diameter"

Keep It Concise

• Aim for one sentence, two at most
• Don't start with "Image of..." or "Picture of..." — screen readers already announce it as an image
• For complex images: keep alt text short and provide detail elsewhere

Specific Content Types

Charts and Graphs

• Alt text: state the type and the key takeaway
• Provide a text summary or data table nearby
• "Line chart showing website traffic doubling between January and June 2026. Full data in the table below."

Screenshots

• Describe what the screenshot shows that matters to the reader
• "Settings panel with the notifications toggle switched off"
• NOT "Screenshot of the settings page"

Icons with Labels

• If the icon has a visible text label, the icon is decorative (alt="")
• If the icon is the only indicator, the alt text must convey the meaning

Images of Text

• Avoid images of text wherever possible — use real text
• If unavoidable: the alt text must contain the full text in the image

Assessment Questions

1. Does every non-decorative image have meaningful alt text?
2. Does the alt text convey purpose, not just appearance?
3. Are decorative images marked with empty alt?
4. Do complex images have both short alt text and a longer description?
5. Would someone using a screen reader get the same information as someone seeing the image?