image-alt-text

Name: image-alt-text
Author: mgifford

27stars2forks

How to install image-alt-text?

mgifford/accessibility-skills/image-alt-text

$npx -y skills add mgifford/accessibility-skills --skill image-alt-text

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Image Alt Text Accessibility Skill
2
3	> Canonical source: `examples/IMAGE_ALT_TEXT_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when creating, reviewing, or auditing any page containing images.
7	Only load this skill if the project contains `<img>` elements, inline SVG images used as content, or CSS background images that may convey meaning.
8
9	---
10
11	## Core Mandate
12
13	WCAG 2.2 SC 1.1.1 Non-text Content (A): every non-text element must have a text
14	alternative serving the equivalent purpose. There is no exception for
15	decorative images — they require an explicit empty `alt=""`. Alternative text
16	is determined by the image's purpose in its specific context, not by the file
17	alone: the same asset may need different alt text, or none, in different uses.
18
19	Never invent details — do not guess a person's identity, race, ethnicity,
20	gender, disability, diagnosis, religion, age, or emotion from appearance.
21	Automated tools detect structural problems (missing `alt`); only human
22	judgment can determine whether alt text is meaningful, accurate, and
23	appropriate for the context.
24
25	---
26
27	## Severity Scale (this skill)
28
29	\| Level \| Meaning \|
30	\| --- \| --- \|
31	\| Critical \| Image conveying essential meaning has no `alt` attribute, or `alt` is entirely absent \|
32	\| Serious \| Functional image (button/link) has no text alternative, preventing keyboard/screen reader use \|
33	\| Moderate \| Alt text is present but inaccurate, redundant ("image of…"), or missing meaningful context \|
34	\| Minor \| Alt text is slightly verbose or could be improved but does not prevent understanding \|
35
36	---
37
38	## The Alt Text Decision Process
39
40	Ask in order, for each use of an image (not the asset generically):
41
42	1. Is the image the only content naming a link, button, or control? →
43	provide a name for the action/destination.
44	2. Does the image contain text that matters here? If the same words are
45	already available as nearby real text, use `alt=""`; otherwise include the
46	necessary words in the alternative.
47	3. **Does the image add information, meaning, identity, state, instruction, or
48	an intended impression?** Simple image → concise alternative. Complex image
49	→ short identification plus an accessible detailed equivalent.
50	4. Is all the image's relevant information already provided nearby? → `alt=""`.
51	5. Is the image purely decorative or only visual formatting? → `alt=""`.
52	6. Still unclear? Clarify why the image is present before publishing —
53	don't guess.
54
55	WCAG does not prescribe a universal character limit — use the shortest
56	alternative that communicates the necessary purpose, and move substantial or
57	structured information into visible page content instead of a long `alt`.
58
59	If you are debating whether an image is decorative, it probably is not —
60	the cost of unnecessary alt text is low; the cost of missing alt text can be
61	complete loss of meaning.
62
63	---
64
65	## Critical: Informative Images
66
67	An informative image contributes meaning not already available in nearby text.
68
69	```html
70	<!-- DO: Describe the meaning/content -->
71	<img src="quarterly-growth.png" alt="Bar chart showing 23% revenue growth in Q3 2024">
72
73	<!-- DON'T: Describe visual appearance only, or use filenames/generic labels -->
74	<img src="quarterly-growth.png" alt="Blue and green bar chart">
75	<img src="quarterly-growth.png" alt="quarterly-growth.png">
76	<img src="quarterly-growth.png" alt="image">
77	```
78
79	Context changes the alternative — the same asset can need different alt text:
80
81	```html
82	<!-- Adoption profile: identity and appearance are relevant -->
83	<img src="buddy.jpg" alt="Buddy, a golden retriever with a red collar">
84
85	<!-- Article already states Buddy is a golden retriever with a red collar -->
86	<img src="buddy.jpg" alt="">
87
88	<!-- Training article: the depicted action is relevant -->
89	<img src="buddy.jpg" alt="Buddy waits beside his handler before crossing the street">
90	```
91
92	A literal visual description is appropriate when appearance itself is the
93	information (art history, product comparison, design critique).
94
95	---
96
97	## Moderate: Decorative and Redundant Images
98
99	Only truly decorative if purely aesthetic, adds no information beyond
100	surrounding text, and removing it wouldn't affect understanding.
101
102	```html
103	<!-- DO -->
104	<img src="decorative-divider.png" alt="">
105	<svg aria-hidden="true" focusable="false">...</svg>
106
107	<!-- DON'T: omit alt entirely (AT may expose the filename) -->
108	<img src="decorative-divider.png">
109	<!-- DON'T: describe tha

People who liked this also viewed

6 picks

Type

image-alt-text

27stars2forks

View on GitHub

How to install image-alt-text?

mgifford/accessibility-skills/image-alt-text

$npx -y skills add mgifford/accessibility-skills --skill image-alt-text

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Image Alt Text Accessibility Skill
2
3	> Canonical source: `examples/IMAGE_ALT_TEXT_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when creating, reviewing, or auditing any page containing images.
7	Only load this skill if the project contains `<img>` elements, inline SVG images used as content, or CSS background images that may convey meaning.
8
9	---
10
11	## Core Mandate
12
13	WCAG 2.2 SC 1.1.1 Non-text Content (A): every non-text element must have a text
14	alternative serving the equivalent purpose. There is no exception for
15	decorative images — they require an explicit empty `alt=""`. Alternative text
16	is determined by the image's purpose in its specific context, not by the file
17	alone: the same asset may need different alt text, or none, in different uses.
18
19	Never invent details — do not guess a person's identity, race, ethnicity,
20	gender, disability, diagnosis, religion, age, or emotion from appearance.
21	Automated tools detect structural problems (missing `alt`); only human
22	judgment can determine whether alt text is meaningful, accurate, and
23	appropriate for the context.
24
25	---
26
27	## Severity Scale (this skill)
28
29	\| Level \| Meaning \|
30	\| --- \| --- \|
31	\| Critical \| Image conveying essential meaning has no `alt` attribute, or `alt` is entirely absent \|
32	\| Serious \| Functional image (button/link) has no text alternative, preventing keyboard/screen reader use \|
33	\| Moderate \| Alt text is present but inaccurate, redundant ("image of…"), or missing meaningful context \|
34	\| Minor \| Alt text is slightly verbose or could be improved but does not prevent understanding \|
35
36	---
37
38	## The Alt Text Decision Process
39
40	Ask in order, for each use of an image (not the asset generically):
41
42	1. Is the image the only content naming a link, button, or control? →
43	provide a name for the action/destination.
44	2. Does the image contain text that matters here? If the same words are
45	already available as nearby real text, use `alt=""`; otherwise include the
46	necessary words in the alternative.
47	3. **Does the image add information, meaning, identity, state, instruction, or
48	an intended impression?** Simple image → concise alternative. Complex image
49	→ short identification plus an accessible detailed equivalent.
50	4. Is all the image's relevant information already provided nearby? → `alt=""`.
51	5. Is the image purely decorative or only visual formatting? → `alt=""`.
52	6. Still unclear? Clarify why the image is present before publishing —
53	don't guess.
54
55	WCAG does not prescribe a universal character limit — use the shortest
56	alternative that communicates the necessary purpose, and move substantial or
57	structured information into visible page content instead of a long `alt`.
58
59	If you are debating whether an image is decorative, it probably is not —
60	the cost of unnecessary alt text is low; the cost of missing alt text can be
61	complete loss of meaning.
62
63	---
64
65	## Critical: Informative Images
66
67	An informative image contributes meaning not already available in nearby text.
68
69	```html
70	<!-- DO: Describe the meaning/content -->
71	<img src="quarterly-growth.png" alt="Bar chart showing 23% revenue growth in Q3 2024">
72
73	<!-- DON'T: Describe visual appearance only, or use filenames/generic labels -->
74	<img src="quarterly-growth.png" alt="Blue and green bar chart">
75	<img src="quarterly-growth.png" alt="quarterly-growth.png">
76	<img src="quarterly-growth.png" alt="image">
77	```
78
79	Context changes the alternative — the same asset can need different alt text:
80
81	```html
82	<!-- Adoption profile: identity and appearance are relevant -->
83	<img src="buddy.jpg" alt="Buddy, a golden retriever with a red collar">
84
85	<!-- Article already states Buddy is a golden retriever with a red collar -->
86	<img src="buddy.jpg" alt="">
87
88	<!-- Training article: the depicted action is relevant -->
89	<img src="buddy.jpg" alt="Buddy waits beside his handler before crossing the street">
90	```
91
92	A literal visual description is appropriate when appearance itself is the
93	information (art history, product comparison, design critique).
94
95	---
96
97	## Moderate: Decorative and Redundant Images
98
99	Only truly decorative if purely aesthetic, adds no information beyond
100	surrounding text, and removing it wouldn't affect understanding.
101
102	```html
103	<!-- DO -->
104	<img src="decorative-divider.png" alt="">
105	<svg aria-hidden="true" focusable="false">...</svg>
106
107	<!-- DON'T: omit alt entirely (AT may expose the filename) -->
108	<img src="decorative-divider.png">
109	<!-- DON'T: describe tha

People who liked this also viewed

6 picks

Type