git:20260331.f09d889 to git:20260722.125074b

256 added, 206 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: image-alt-text
description: >
Load this skill whenever the project contains <img> elements, inline SVGs
used as content images, CSS background images that convey meaning, or icon
fonts. Under no circumstances omit alt text on meaningful images. Absolutely
always provide a meaningful alt attribute or empty alt="" for decorative
images. Apply WCAG 2.2 SC 1.1.1 — every non-text element requires a text
alternative.
---
# 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 Success Criterion 1.1.1 — Non-text Content (Level A): every non-text element must have a text alternative conveying the same meaning and purpose. There are no exceptions for decorative images — those require an explicit empty `alt` attribute.
+ 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.
- Automated tools can flag missing alt text, but only human judgment can determine whether alt text is _meaningful_ and _appropriate_ for the context.
+ 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)
| Level | Meaning |
| --- | --- |
| **Critical** | Image conveying essential meaning has no `alt` attribute, or `alt` is entirely absent |
| **Serious** | Functional image (button/link) has no text alternative, preventing keyboard/screen reader use |
| **Moderate** | Alt text is present but inaccurate, redundant ("image of…"), or missing meaningful context |
| **Minor** | Alt text is slightly verbose or could be improved but does not prevent understanding |
---
- ## The Alt Text Decision Tree
+ ## The Alt Text Decision Process
- Use this flowchart (based on the [W3C WAI Images Tutorial](https://www.w3.org/WAI/tutorials/images/decision-tree/)):
+ Ask in order, for each use of an image (not the asset generically):
- ```
- Does the image contain text?
- ├── YES → Use the same text as the alt attribute (unless decorative/logo)
- └── NO
- └── Is the image used for a functional purpose (link, button)?
- ├── YES → Describe the destination/action (e.g., "Go to homepage")
- └── NO
- └── Does the image convey information not present in surrounding text?
- ├── YES
- │ └── Is the image complex (chart, diagram, graph)?
- │ ├── YES → Provide a short alt + long description in nearby text
- │ └── NO → Write a concise description of the content and meaning
- └── NO
- └── Is the image purely decorative or redundant?
- ├── YES → Use empty alt: alt=""
- └── NO → Re-evaluate — the image likely carries meaning
- ```
+ 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`.
- ## Image Categories and Requirements
+ **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.
- ### Informative Images
+ ---
- Images that convey information not expressed in surrounding text.
+ ## Critical: Informative Images
+ An informative image contributes meaning not already available in nearby text.
+
```html
<!-- 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 -->
+ <!-- DON'T: Describe visual appearance only, or use filenames/generic labels -->
<img src="quarterly-growth.png" alt="Blue and green bar chart">
-
- <!-- DON'T: Use file names or generic labels -->
<img src="quarterly-growth.png" alt="quarterly-growth.png">
<img src="quarterly-growth.png" alt="image">
```
- ### Decorative Images
+ Context changes the alternative — the same asset can need different alt text:
- Images that are purely aesthetic and add no information beyond what the page text already provides.
+ ```html
+ <!-- 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.
+
```html
- <!-- DO: Empty alt for decorative images -->
+ <!-- DO -->
<img src="decorative-divider.png" alt="">
-
- <!-- DO: aria-hidden for inline SVG decorations -->
<svg aria-hidden="true" focusable="false">...</svg>
- <!-- DON'T: Omit alt entirely — screen readers announce the filename -->
+ <!-- DON'T: omit alt entirely (AT may expose the filename) -->
<img src="decorative-divider.png">
-
- <!-- DON'T: Use "decorative" or "spacer" as alt text -->
+ <!-- DON'T: describe that it's decorative -->
<img src="decorative-divider.png" alt="decorative">
```
- **When is an image truly decorative?** Only if it is purely aesthetic (border, texture, flourish), adds no information beyond surrounding text, and removing it would not affect a user's 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.
- **If you are debating whether an image is decorative, it probably is not.** When in doubt, provide alt text. The cost of unnecessary alt text is low; the cost of missing alt text can be complete loss of meaning.
+ ---
- ### Functional Images
+ ## Serious: Functional Images
- Images that are the only content of a link or button.
+ Images that are the only content of a link or control must describe the
+ action/destination, not the icon's shape.
```html
- <!-- DO: Describe the link destination -->
- <a href="/home">
- <img src="logo.svg" alt="Go to homepage">
- </a>
+ <!-- Image-only link -->
+ <a href="/"><img src="acme-logo.svg" alt="Acme home"></a>
- <!-- DO: Describe the button action -->
- <button>
- <img src="search-icon.svg" alt="Search">
- </button>
+ <!-- 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>
- <!-- DO: Use aria-label on the button, empty alt on the image -->
- <button aria-label="Search">
- <img src="search-icon.svg" alt="">
+ <!-- Icon-only button: name goes on the control -->
+ <button type="button" aria-label="Close dialog">
+ <img src="close.svg" alt="">
</button>
- <!-- DON'T: Leave functional images with empty alt (creates unlabelled control) -->
- <button>
- <img src="search-icon.svg" alt="">
- <!-- Missing accessible name — use aria-label on the button instead -->
- </button>
+ <!-- Image submit button: alt IS the control name -->
+ <input type="image" src="submit-order.png" alt="Submit order">
```
- ### Complex Images
+ 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.
- Charts, graphs, diagrams, maps, and infographics where a short alt cannot convey all information.
+ **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.
+
```html
- <!-- Pattern 1: Alt summary + adjacent long description -->
<figure>
- <img
- src="accessibility-adoption-chart.png"
- alt="Line chart: WCAG AA adoption rose from 38% in 2020 to 67% in 2024"
- aria-describedby="chart-desc">
- <figcaption id="chart-desc">
- Annual WCAG 2.1 Level AA adoption rates from 2020 to 2024 across a sample
- of 10,000 public websites. Adoption grew steadily from 38% (2020) to 67%
- (2024), driven by increased procurement requirements.
+ <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>
```
- ### Images of Text
-
- ```html
- <!-- DO: Reproduce the exact text in the alt attribute -->
- <img src="sale-banner.png" alt="Summer Sale: 50% off all items through July 31">
-
- <!-- DON'T: Describe that it is text -->
- <img src="sale-banner.png" alt="Sale banner showing promotional text">
- ```
-
- Prefer actual text over images of text whenever possible (WCAG 1.4.5).
-
- ### Groups of Images
-
- When multiple images work together to convey a single piece of information (e.g., a star rating):
+ 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.
- ```html
- <!-- Star rating: 4 out of 5 stars — only the first image needs meaningful alt -->
- <img src="star-filled.png" alt="Rating: 4 out of 5 stars">
- <img src="star-filled.png" alt="">
- <img src="star-filled.png" alt="">
- <img src="star-filled.png" alt="">
- <img src="star-empty.png" alt="">
- ```
+ ---
- ### Linked Images with Adjacent Text
+ ## Moderate: Images of Text
- When an image and text are together inside the same link:
+ Prefer real HTML text over images of text (WCAG 1.4.5) — real text resizes,
+ reflows, adapts to user colors, and translates more reliably.
```html
- <!-- DO: Empty alt when link text describes the destination -->
- <a href="/articles/accessibility-guide">
- <img src="accessibility-thumbnail.jpg" alt="">
- <span>The Complete Accessibility Guide</span>
- </a>
+ <!-- Reproduce the exact important words -->
+ <img src="sale-banner.png" alt="Summer sale: 50% off through July 31">
- <!-- DON'T: Duplicate the link text in alt -->
- <a href="/articles/accessibility-guide">
- <img src="accessibility-thumbnail.jpg" alt="The Complete Accessibility Guide">
- The Complete Accessibility Guide
- </a>
+ <!-- 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.
+
---
- ## Writing Quality Alt Text
+ ## Moderate: Figures and Captions
- 1. **Be concise but complete.** Aim for 125 characters or fewer for simple images; use long descriptions for complex images.
- 2. **Describe content and purpose, not appearance.** "Person in a wheelchair using a laptop" is more useful than "image of a person".
- 3. **Context is everything.** The same image can have different alt text depending on how it is used.
- 4. **Do not start with "Image of", "Picture of", or "Photo of".** Screen readers already announce that they are reading an image.
- 5. **Avoid keyword stuffing.** Alt text serves users, not search engines.
- 6. **Include text that appears within the image.**
- 7. **Match the level of detail to the image's role.**
+ `<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.
---
- ## Common Bad Alt Text Patterns (Critical/Serious to flag and fix)
+ ## Minor: Groups, Responsive Images, and Image Maps
- ### Missing or absent `alt` attribute — Critical
+ **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`:
```html
- <!-- WRONG: Screen reader reads the filename -->
- <img src="Q3-revenue-chart-final-v2.png">
-
- <!-- RIGHT -->
- <img src="Q3-revenue-chart-final-v2.png"
- alt="Bar chart: Q3 2024 revenue reached $4.2M, up 18% from Q2">
+ <img src="star-filled.png" alt="Rating: 4 out of 5 stars">
+ <img src="star-filled.png" alt="">
+ <img src="star-empty.png" alt="">
```
- ### Filename or CMS-injected alt text — Serious
+ **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.
+
```html
- <!-- WRONG -->
- <img src="golden-retriever.jpg" alt="golden-retriever.jpg">
- <img src="dog.png" alt="This image has an empty alt attribute; its file name is dog.png">
+ <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>
```
- ### Generic single-word placeholders — Serious
+ 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.
- The following values are flagged as errors by multiple accessibility checkers:
+ ---
- ```html
- <!-- WRONG -->
- <img src="photo.jpg" alt="image">
- <img src="photo.jpg" alt="photo">
- <img src="photo.jpg" alt="graphic">
- <img src="photo.jpg" alt="chart">
- <img src="photo.jpg" alt="alt">
- <img src="spacer.gif" alt="spacer"> <!-- use alt="" instead -->
- <img src="divider.png" alt="decorative"> <!-- use alt="" instead -->
- ```
+ ## Writing Quality Alt Text
- ### Draft/placeholder text — Serious
+ 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
- ```html
- <!-- WRONG -->
- <img src="portrait.jpg" alt="TBD">
- <img src="portrait.jpg" alt="TODO">
- <img src="portrait.jpg" alt="placeholder">
- <img src="portrait.jpg" alt="null">
- <img src="portrait.jpg" alt="undefined">
- ```
+ ---
- ### "Type" prefix phrases — Moderate
+ ## Common Bad Alt Text Patterns
- ```html
- <!-- WRONG: Redundant medium prefix -->
- <img src="team-photo.jpg" alt="Image of the team">
- <img src="team-photo.jpg" alt="Photo of team members">
+ | Pattern | Severity | Fix |
+ | --- | --- | --- |
+ | Missing `alt` on an informative `<img>` | Critical | Provide an equivalent alternative |
+ | Missing `alt` on a decorative `<img>` | Serious | Use `alt=""` |
+ | Filename or CMS-injected text as `alt` | Serious | Replace with contextual author-written text |
+ | Generic placeholders (`"image"`, `"photo"`, `"chart"`, `"alt"`) | Serious | Describe the relevant content or purpose |
+ | `alt="decorative"` / `alt="spacer"` | Serious | Use `alt=""` |
+ | Draft placeholders (`"TBD"`, `"TODO"`, `"null"`, `"undefined"`) | Serious | Block publication until a real decision is made |
+ | "Type" prefix phrases ("Image of…", "Photo of…") when medium doesn't matter | Moderate | Describe the content directly |
+ | Alt text duplicates an adjacent `<figcaption>` verbatim | Moderate | Use `alt=""` or make it complementary |
+ | Name-only alt for person portraits | Moderate | Include role/context when relevant and known |
+ | `title` used instead of `alt` | Serious | Use `alt`; don't rely on hover-only text |
+ | `aria-label` added to `<img>` instead of `alt` | Moderate | Use the native `alt` attribute |
+ | Full chart data forced into one long `alt` | Moderate | Short alt + visible structured data |
+ | One asset-level alternative reused in every context | Moderate | Author an alternative per use |
+ | AI-generated text published without review | Serious | Require contextual human approval |
- <!-- RIGHT -->
- <img src="team-photo.jpg" alt="The Civic Innovations team of 12 staff gathered outside City Hall">
- ```
+ ---
- ### Alt text that duplicates a figcaption — Moderate
+ ## CSS Background Images
- ```html
- <!-- WRONG: Screen reader announces the text twice -->
- <figure>
- <img src="annual-report-cover.jpg"
- alt="2024 Annual Report cover showing the city skyline at dusk">
- <figcaption>2024 Annual Report cover showing the city skyline at dusk</figcaption>
- </figure>
+ CSS `background-image` has no `alt` support — use only for decoration or when
+ equivalent information is already present as real content.
- <!-- RIGHT: Caption fully describes — use empty alt -->
- <figure>
- <img src="annual-report-cover.jpg" alt="">
- <figcaption>2024 Annual Report cover showing the city skyline at dusk</figcaption>
- </figure>
+ ```css
+ /* OK: decorative */
+ .hero { background-image: url('geometric-pattern.svg'); }
```
- ### Name-only alt for person portraits — Moderate
-
```html
- <!-- POOR: Name only -->
- <img src="j-smith.jpg" alt="J Smith">
+ <!-- NOT OK: meaningful image invisible to screen readers -->
+ <div class="award-badge"></div>
- <!-- BETTER: Include role and context -->
- <img src="j-smith.jpg"
- alt="Dr. Jane Smith, Chief Medical Officer, presenting at the 2024 health summit">
+ <!-- DO: put the information in HTML -->
+ <p class="award-badge">Winner, 2026 Inclusive Design Award</p>
```
+ 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.
+
---
- ## CSS Background Images
+ ## CMS and Authoring Requirements
- CSS `background-image` does not support `alt` text. Use only for decorative purposes.
+ 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.
- ```css
- /* OK: Decorative pattern */
- .hero { background-image: url('geometric-pattern.svg'); }
- ```
+ **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.
- ```html
- <!-- NOT OK: Meaningful image as CSS background (invisible to screen readers) -->
- <div style="background-image: url('award-badge.png')"></div>
+ ---
- <!-- DO: Use <img> for meaningful images -->
- <img src="award-badge.png" alt="Winner: Best Accessibility Tool 2024">
- ```
+ ## 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 can detect | Requires human review |
| --- | --- |
| Missing `alt` attribute | Whether alt text is meaningful |
| Empty alt on functional images | Whether alt text matches context |
- | Alt text that equals the file name | Whether a decorative image actually needs alt text |
- | Suspicious prefix phrases ("image of") | Whether the description conveys the right meaning |
- | Known placeholder values ("TBD", "null") | Whether content-author intent was decorative or informative |
+ | Alt text equal to the file name | Whether a decorative image actually needs alt |
+ | Suspicious prefix phrases, known placeholders | Whether the description conveys the right meaning |
| Alt text identical to adjacent figcaption | Whether the alt or the caption should be kept |
+ | Missing names on image buttons/image-map areas | Whether a complex description preserves relationships |
- Automated tools such as axe-core detect structural issues. Human review is always required to evaluate quality.
+ 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 `<img>` element has an `alt` attribute (even decorative images use `alt=""`)
- - [ ] Decorative images use `alt=""` and are confirmed to add no meaning
- - [ ] Functional images (links, buttons) describe the action or destination
- - [ ] Alt text does not begin with "image of", "picture of", or "photo of"
- - [ ] Alt text does not repeat the file name or generic label ("image", "photo", "graphic", "chart")
- - [ ] Alt text is not a draft placeholder ("TBD", "TODO", "null", "none", "undefined", "placeholder")
- - [ ] Alt text is not a machine-generated code or CMS-injected message
- - [ ] Complex images (charts, diagrams) have both a short alt and a long description
- - [ ] Images of text reproduce the exact text in the `alt` attribute
- - [ ] Grouped images convey combined meaning via one image's alt (others are `alt=""`)
- - [ ] Linked images with adjacent link text use `alt=""` on the image
- - [ ] Figures with a `<figcaption>` do not duplicate the caption verbatim in the `alt`
- - [ ] Portrait images include the person's role and context, not just their name
- - [ ] CSS background images are decorative (meaningful images use `<img>`)
- - [ ] Alt text has been reviewed in context, not just in isolation
- - [ ] Alt text has been tested with a screen reader (NVDA + Firefox or VoiceOver + Safari)
+ * [ ] 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)
- * 4.1.2 Name, Role, Value (A) — all UI components have accessible names and roles
+ * 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](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/examples/IMAGE_ALT_TEXT_ACCESSIBILITY_BEST_PRACTICES.md)
* [W3C WAI — Images Tutorial and Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)
* [WCAG 2.2 — 1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html)
* [WebAIM — Writing Effective Alt Text](https://webaim.org/techniques/alttext/)
* [Sa11y](https://sa11y.netlify.app/) — flags suspicious alt text patterns
- * [Editoria11y](https://editoria11y.princeton.edu/) — CMS-focused alt text checking
* [axe-core rules: `image-alt`, `image-redundant-alt`, `input-image-alt`, `area-alt`, `object-alt`](https://github.com/dequelabs/axe-core)