Alt-text writing

Contract

Enforces the WAI/WebAIM alt-text conventions on every alt value you produce: no redundant prefix, one concise description of content or function, an empty alt for decorative images, and the destination for a linked image. Apply when writing an image's alt attribute; not to visible captions, extended long descriptions, or generating the image.

Rules

1. No redundant prefix. Never open with "Image of", "Picture of", "Photo of", "Graphic of",

"Icon of", or "An image showing". A screen reader already announces the element as an image, so the prefix is heard twice. Start with the subject.

1. Concise and functional. One short phrase — roughly one sentence, about 125 characters or

fewer. Convey the image's purpose or content, not an exhaustive inventory of every colour, pose, and background object. Describe why the image is there, then stop.

1. Decorative images get an empty alt. If the image adds only visual polish and carries no

information the surrounding text lacks — dividers, spacers, ornamental flourishes, a purely aesthetic backdrop — the alt is empty: alt="". That tells the screen reader to skip it. Never describe a decorative image.

1. A linked or functional image describes its destination or action. When the image is itself a

link or a control, the alt says where the link goes or what the control does — "Home", "Search", "Close" — not the picture. A logo that links to the front page has alt="Home" (or the site name), never alt="company logo".

1. Never duplicate adjacent text. If a visible caption or nearby paragraph already conveys the

image, do not repeat it in the alt. Give it an empty alt, or add only what the caption leaves out (the chart type, a specific value).

1. Informative images state the point, not the medium. For a chart, diagram, or screenshot,

the alt gives the takeaway or the key data ("Signups doubled after the March launch"), never "a bar chart" or "a screenshot of a dashboard".

1. End with a period. Close a descriptive alt value with a full stop so the screen reader pauses

cleanly before the next element. (An empty alt="" has nothing to punctuate.)

Worked examples

The base's default on top; the conforming alt below.

A content photo in an article:

BEFORE  alt="Image of a cat sleeping on a windowsill in the warm afternoon
        sun, curled up in a tight ball with its tail over its nose"

AFTER   alt="A tabby cat sleeps curled up on a sunny windowsill."

A purely decorative divider:

BEFORE  alt="decorative swirl graphic dividing the two sections"

AFTER   alt=""

A magnifying-glass icon that is the search button:

BEFORE  alt="magnifying glass icon"

AFTER   alt="Search"

A chart whose caption already describes it:

CAPTION Figure 2. Revenue by quarter.
BEFORE  alt="A bar chart showing revenue by quarter"

AFTER   alt=""        (the caption already conveys it; or add what it omits:
        alt="Q4 revenue is the tallest bar, roughly double Q1.")

An informative chart with no caption:

BEFORE  alt="Line graph of website traffic over twelve months"

AFTER   alt="Website traffic climbed steadily all year, doubling by December."

Edge cases & exceptions

• A photo used purely as a link (a thumbnail linking to an article) → the alt describes the

destination, e.g. the article's title, not the thumbnail's picture.

• Text inside the image (a logo wordmark, a quote graphic) → the alt reproduces that text, not

a description of the lettering's appearance.

• A complex infographic → give the alt a short summary and put the full detail in adjacent body

text or a linked long description; the alt is not the place for a paragraph.

• The same image appears twice on a page → if one instance is decorative repetition, that copy

gets alt="".

• A meaningful inline icon (a ✓ beside "Paid", a red dot for "Offline") → the alt is the meaning

it conveys ("Paid", "Offline"), not the shape or colour of the mark.

• A background image set purely in CSS is not in the markup and takes no alt; if such an image

carries meaning, add a real text alternative in the HTML instead of relying on the background.

Do / Don't

• Do start with the subject. Don't start with "Image of" / "Photo of" / "Graphic of".
• Do write one concise phrase. Don't catalogue every visual detail across several sentences.
• Do give decorative images alt="". Don't describe an image that carries no information.
• Do describe a linked image's destination. Don't describe the logo or icon artwork.
• Do add only what a caption omits. Don't repeat the caption verbatim in the alt.
• Do end a description with a period. Don't punctuate an empty alt.

Common mistakes

• "Image of…" / "A picture showing…" prefixes the screen reader reads as "image, image of…".
• A three-sentence description of a simple photo.
• Alt text on a spacer, divider, or ornamental flourish that should have been alt="".
• A linked logo described as "company logo" instead of its destination.
• Alt text that repeats, word for word, the caption printed right below the image.
• "A bar chart" as the whole alt, conveying none of the data the chart shows.

Quick checklist

• No "Image of / Photo of / Graphic of" prefix.
• One concise phrase (~125 chars), content or function, not an inventory.
• Decorative image → alt="".
• Linked/functional image → destination or action, not the artwork.
• No duplication of an adjacent caption.
• Descriptive alt ends with a period.