---
name: alt-text-writing
source: https://app.decimal.ai/s/alt-text-writing@1/SKILL.md
source_sha256: f484d89de2e4
---

# 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.

2. **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.

3. **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.

4. **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"`.

5. **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).

6. **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".

7. **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.