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.
2. 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.
3. 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.
4. Is all the image's relevant information already provided nearby? → alt="".
5. Is the image purely decorative or only visual formatting? → alt="".
6. 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 -->

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

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.

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.

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.

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.

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:

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.

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
2. Describe content and purpose, not appearance — but include the medium (photo/painting/screenshot) when it changes meaning, source, or interpretation
3. Context is everything — the same image can need different alt text depending on use; author per-context, not once per asset
4. Do not start with "Image of", "Picture of", or "Photo of" unless the medium itself matters — there is no universal wording ban
5. Avoid keyword stuffing, filenames, and SEO/marketing phrases — alt text serves users, not search engines
6. Include important text that appears within the image
7. 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
8. Write in the page's language with normal capitalization/punctuation so synthesized speech and Braille are understandable

Common Bad Alt Text Patterns

CSS Background Images

CSS background-image has no alt support — use only for decoration or when equivalent information is already present as real content.

Background images can disappear under user styles, forced colors, print, or content blockers — the page must not depend on them for essential content or function.

CMS and Authoring Requirements

A content system should support the decision, not just require a non-empty field. Provide authors a required choice (Informative / Functional / Decorative or redundant / Needs detailed description), an alt field that permits a deliberately empty value, and context about where the image is used. Do not auto-fill empty alt fields with filenames, captions, or asset titles — a caption, credit, and alt text serve different purposes.

Block publication when: no alt decision has been made; an informative image has no alternative or equivalent visible text; a functional image doesn't name its control; a complex image lacks its detailed equivalent; a placeholder/filename was inserted as the alternative. Do not block a deliberate alt="" solely because the field is empty — require the author to confirm the image is decorative in that use.

AI-Assisted Alt Text

AI can suggest a draft description but cannot reliably know editorial purpose, audience, or redundancy. An AI-assisted workflow should: ask for purpose-equivalent text, not a visual inventory; distinguish informative/ functional/decorative/complex uses; flag uncertainty rather than fabricate details; avoid inferring sensitive attributes or identifying unknown people; avoid sending private images/metadata to an unapproved service; require a responsible person to review the suggestion in the rendered context; and send complex images for a detailed human-authored equivalent. Do not let AI-generated confidence replace editorial accountability — a fluent description can still be inaccurate, biased, or unsafe.

Automated vs. Human Testing

Automated tools such as axe-core detect structural issues; human review is always required to evaluate quality. Store the tool/rule version with results, and route confirmed issues through skills/bug-reporting/SKILL.md.

Definition of Done Checklist

• Every image use has an explicit purpose and alt decision
• Every meaningful <img> has an accurate, contextual alt
• Every decorative or fully redundant <img> has alt=""
• No filename, placeholder, keyword list, or unrelated metadata used as alt
• Functional images provide useful link or control names; visible labels are included in accessible names
• Important words shown only in an image are also available as text
• Complex images have a short identification and an accessible detailed equivalent
• Captions and alternatives complement rather than duplicate each other
• Responsive <picture> sources convey the same essential meaning; alt is on the fallback <img>
• CSS background images are not the only source of information or function
• Alternatives use the page language and are included in translation workflows
• Descriptions do not invent identity, emotion, or sensitive attributes
• AI-generated suggestions received contextual human review
• Tested with a screen reader (NVDA + Firefox or VoiceOver + Safari)

Key WCAG Criteria

• 1.1.1 Non-text Content (A) — Critical if any meaningful image has no text alternative
• 1.4.5 Images of Text (AA) — prefer real text over images of text
• 1.4.9 Images of Text No Exception (AAA)
• 2.4.4 Link Purpose in Context (A) — image-only and combined links must communicate purpose
• 2.5.3 Label in Name (A) — visible control text must be in the accessible name
• 4.1.2 Name, Role, Value (A)

References

• Full best practices guide
• W3C WAI — Images Tutorial and Decision Tree
• WCAG 2.2 — 1.1.1 Non-text Content
• WebAIM — Writing Effective Alt Text
• Sa11y — flags suspicious alt text patterns
• axe-core rules: image-alt, image-redundant-alt, input-image-alt, area-alt, object-alt