mgifford/accessibility-skills/image-alt-text

Image Alt Text Accessibility Skill

Canonical source: examples/IMAGE_ALT_TEXT_ACCESSIBILITY_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md

This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules when creating, reviewing, or auditing any page containing images. Only load this skill if the project contains `<img>` elements, inline SVG images used as content, or CSS background images that may convey meaning.

Core Mandate

WCAG 2.2 SC 1.1.1 Non-text Content (A): every non-text element must have a text alternative serving the equivalent purpose. There is no exception for decorative images — they require an explicit empty alt="". Alternative text is determined by the image's purpose in its specific context, not by the file alone: the same asset may need different alt text, or none, in different uses.

Never invent details — do not guess a person's identity, race, ethnicity, gender, disability, diagnosis, religion, age, or emotion from appearance. Automated tools detect structural problems (missing alt); only human judgment can determine whether alt text is meaningful, accurate, and appropriate for the context.

Severity Scale (this skill)

The Alt Text Decision Process

Ask in order, for each use of an image (not the asset generically):

1. Is the image the only content naming a link, button, or control? →

provide a name for the action/destination.

1. Does the image contain text that matters here? If the same words are

already available as nearby real text, use alt=""; otherwise include the necessary words in the alternative.

1. **Does the image add information, meaning, identity, state, instruction, or

an intended impression?** Simple image → concise alternative. Complex image → short identification plus an accessible detailed equivalent.

1. Is all the image's relevant information already provided nearby? → alt="".
2. Is the image purely decorative or only visual formatting? → alt="".
3. Still unclear? Clarify why the image is present before publishing —

don't guess.

WCAG does not prescribe a universal character limit — use the shortest alternative that communicates the necessary purpose, and move substantial or structured information into visible page content instead of a long alt.

If you are debating whether an image is decorative, it probably is not — the cost of unnecessary alt text is low; the cost of missing alt text can be complete loss of meaning.

Critical: Informative Images

An informative image contributes meaning not already available in nearby text.

<!-- DO: Describe the meaning/content -->
<img src="quarterly-growth.png" alt="Bar chart showing 23% revenue growth in Q3 2024">
 
<!-- DON'T: Describe visual appearance only, or use filenames/generic labels -->
<img src="quarterly-growth.png" alt="Blue and green bar chart">
<img src="quarterly-growth.png" alt="quarterly-growth.png">
<img src="quarterly-growth.png" alt="image">

Context changes the alternative — the same asset can need different alt text:

<!-- Adoption profile: identity and appearance are relevant -->
<img src="buddy.jpg" alt="Buddy, a golden retriever with a red collar">
 
<!-- Article already states Buddy is a golden retriever with a red collar -->
<img src="buddy.jpg" alt="">
 
<!-- Training article: the depicted action is relevant -->
<img src="buddy.jpg" alt="Buddy waits beside his handler before crossing the street">

A literal visual description is appropriate when appearance itself is the information (art history, product comparison, design critique).

Moderate: Decorative and Redundant Images

Only truly decorative if purely aesthetic, adds no information beyond surrounding text, and removing it wouldn't affect understanding.

<!-- DO -->
<img src="decorative-divider.png" alt="">
<svg aria-hidden="true" focusable="false">...</svg>
 
<!-- DON'T: omit alt entirely (AT may expose the filename) -->
<img src="decorative-divider.png">
<!-- DON'T: describe that it's decorative -->
<img src="decorative-divider.png" alt="decorative">

For <img>, prefer alt="" over role="presentation". Do not use aria-hidden="true" to conceal an image that provides information or a control name. An unnecessary description is not harmless — it interrupts reading order and makes navigation more tiring.

Serious: Functional Images

Images that are the only content of a link or control must describe the action/destination, not the icon's shape.

<!-- Image-only link -->
<a href="/"><img src="acme-logo.svg" alt="Acme home"></a>
 
<!-- Image plus redundant link text: make the image decorative -->
<a href="/reports/annual">
  <img src="report-cover.jpg" alt="">
  <span>2026 annual report</span>
</a>
 
<!-- Icon-only button: name goes on the control -->
<button type="button" aria-label="Close dialog">
  <img src="close.svg" alt="">
</button>
 
<!-- Image submit button: alt IS the control name -->
<input type="image" src="submit-order.png" alt="Submit order">

If the control has a visible text label, the accessible name must contain that visible text (supports speech input, required by WCAG 2.5.3 Label in Name). Prefer a normal <button> with real text over <input type="image"> when possible.

Leaving a functional image with empty `alt` and no other accessible name creates an unlabelled control — Serious.

Moderate: Complex Images

Charts, diagrams, maps, and infographics need two parts: a short alternative identifying the image and its purpose/main conclusion, plus a visible detailed equivalent (description, data table, ordered steps) that preserves values, labels, units, trends, comparisons, and relationships.

<figure>
  <img src="revenue-trend.png"
       alt="Line chart showing revenue rising each quarter in 2025. Data table follows.">
  <figcaption>
    <p>Revenue increased from $1.2 million in Q1 to $2.1 million in Q4.</p>
    <table>
      <caption>Quarterly revenue for 2025</caption>
      <thead><tr><th scope="col">Quarter</th><th scope="col">Revenue</th></tr></thead>
      <tbody>
        <tr><th scope="row">Q1</th><td>$1.2 million</td></tr>
        <tr><th scope="row">Q4</th><td>$2.1 million</td></tr>
      </tbody>
    </table>
  </figcaption>
</figure>

Prefer descriptions visible to everyone over aria-describedby alone — content referenced by aria-describedby is commonly exposed as a single description and can lose headings, tables, and other structure. Do not rely on the obsolete longdesc attribute. See skills/charts-graphs/SKILL.md and skills/maps/SKILL.md for domain-specific guidance.

Moderate: Images of Text

Prefer real HTML text over images of text (WCAG 1.4.5) — real text resizes, reflows, adapts to user colors, and translates more reliably.

<!-- Reproduce the exact important words -->
<img src="sale-banner.png" alt="Summer sale: 50% off through July 31">
 
<!-- If the same message already appears as real text nearby -->
<img src="sale-banner.png" alt="">
<p><strong>Summer sale:</strong> 50% off through July 31.</p>

For a poster or scanned notice with substantial text, put the full text as visible page content and let alt identify the image. Logotypes are essential images of text under 1.4.5 but still need an alternative — usually the organization/product name, plus "home" when a logo is the only content of a home-page link.

Moderate: Figures and Captions

<figcaption> does not justify omitting alt from an informative <img>. Choose the relationship deliberately: if the caption already gives the full equivalent, use alt=""; if the image adds information beyond the caption, make alt complementary; if the caption is a title/credit/commentary rather than an equivalent, the image still needs its own alternative. Do not copy the same sentence into both. Do not put copyright/licensing/photo-credit information only in alt — keep it visible.

Minor: Groups, Responsive Images, and Image Maps

Groups: when multiple images express one value (e.g., a star rating), give the combined value once and mark repeated units alt="" or aria-hidden:

<img src="star-filled.png" alt="Rating: 4 out of 5 stars">
<img src="star-filled.png" alt="">
<img src="star-empty.png" alt="">

Responsive images: place alt on the fallback <img> inside <picture>, never on <source>. Every responsive source must communicate substantially the same information — if art direction changes the image's meaning, one shared alternative may no longer be accurate.

Image maps: give the <img> an alt describing overall context, and give each <area> its own alt describing its destination/action.

<img src="campus-map.png" alt="Campus buildings" usemap="#campus-buildings">
<map name="campus-buildings">
  <area shape="rect" coords="20,30,120,100" href="/library" alt="Central Library">
</map>

For inline SVG, see skills/svg/SKILL.md. For <canvas>, provide equivalent fallback content and keyboard-operable alternatives — aria-label alone cannot replace complex canvas content.

Writing Quality Alt Text

1. Be concise but complete — aim for ~125 characters for simple images; use

long descriptions for complex ones

1. Describe content and purpose, not appearance — but include the medium

(photo/painting/screenshot) when it changes meaning, source, or interpretation

1. Context is everything — the same image can need different alt text

depending on use; author per-context, not once per asset

1. Do not start with "Image of", "Picture of", or "Photo of" *unless the

medium itself matters* — there is no universal wording ban

1. Avoid keyword stuffing, filenames, and SEO/marketing phrases — alt text

serves users, not search engines

1. Include important text that appears within the image
2. Use a person's name only when identity is known, relevant, and appropriate

to publish; describe a visible characteristic only when it serves the purpose — do not infer race, disability, emotion, or other sensitive attributes

1. Write in the page's language with normal capitalization/punctuation so

synthesized speech and Braille are understandable

Common Bad Alt Text Patterns