content-design

Name: content-design
Author: mgifford

27stars2forks

How to install content-design?

mgifford/accessibility-skills/content-design

$npx -y skills add mgifford/accessibility-skills --skill content-design

Installs into the current project.

Summary

Load this skill whenever writing, editing, or reviewing any web content, copy, headings, labels, error messages, or instructions. Under no circumstances write inaccessible content — every piece of text must be clear, structured, and usable by people with cognitive, visual, and la

Files · 1

View on GitHub

SKILL.md

1	# Content Design Accessibility Skill
2
3	> Canonical source: `examples/CONTENT_DESIGN_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 writing, editing, or reviewing any web content.
7
8	---
9
10	## Core Mandate
11
12	Content design and accessibility are inseparable. A technically accessible page that
13	is confusing or poorly structured still creates barriers. Design content for the
14	widest possible audience: write clearly, structure logically, and present
15	information in the order users need it.
16
17	---
18
19	## Severity Scale (this skill)
20
21	\| Level \| Meaning \|
22	\| --- \| --- \|
23	\| Critical \| Content is completely inaccessible or incomprehensible to a disability group \|
24	\| Serious \| Significant barrier; unreasonable to expect workaround \|
25	\| Moderate \| Creates friction; workaround exists and is not too burdensome \|
26	\| Minor \| Best-practice gap; marginal impact \|
27
28	---
29
30	## Critical: Images Must Have Appropriate Text Alternatives
31
32	A meaningful image with no `alt` attribute or `alt=""` is Critical —
33	blind users receive no information. A decorative image with descriptive `alt` is
34	Moderate — it adds noise but does not block information.
35
36	* Every informative image needs meaningful alt text that conveys its purpose, not
37	just its appearance
38	* Decorative images: `alt=""` (empty string — the attribute must still be present)
39	* Do not rely on images alone to convey information; support visual content with
40	accompanying text
41	* Charts and graphs must be accompanied by a text summary or accessible data table
42	(see `skills/charts-graphs/SKILL.md`)
43	* For diagram-specific guidance, see `skills/svg/SKILL.md`
44
45	---
46
47	## Serious: All Link Text Must Make Sense Out of Context
48
49	"Click here", "Read more", and "Learn more" are Serious — screen reader
50	users navigate by links and hear them without surrounding context.
51
52	```html
53	<!-- Serious issue -->
54	<a href="/report">Read more</a>
55
56	<!-- Good -->
57	<a href="/report">2024 Accessibility Annual Report</a>
58	```
59
60	For document links, include file type and size:
61
62	```html
63	<a href="/report.pdf">2024 Annual Report (PDF, 2.3 MB)</a>
64	```
65
66	Warn users when links open in new tabs:
67
68	```html
69	<a href="/report" target="_blank">
70	Annual Report
71	<span class="visually-hidden">(opens in new tab)</span>
72	</a>
73	```
74
75	Use consistent terminology: if a concept is called "accessibility statement" in
76	one place, do not call it "a11y disclosure" somewhere else.
77
78	---
79
80	## Serious: Heading Hierarchy Must Be Logical
81
82	Skipping heading levels is Moderate; having no `<h1>` or using headings
83	purely for visual styling is Serious — screen reader users rely on headings
84	for page navigation.
85
86	* One `<h1>` per page describing the page's main purpose
87	* Logical hierarchy: `h1` → `h2` → `h3` (do not skip levels)
88	* Headings must be descriptive and unique — not "Introduction" or "Overview" alone
89	* Write headings as statements or clear topic labels, not questions (unless FAQ
90	format is appropriate)
91	* Navigation labels, button text, and form labels must be descriptive and
92	unambiguous out of context
93
94	---
95
96	## Moderate: Plain Language
97
98	Overly complex language is Moderate — it creates real barriers for users
99	with cognitive disabilities and low literacy, but the content is technically
100	still present.
101
102	* Common words, short sentences, active voice
103	* Target Grade 8 reading level or lower for general audiences
104	* Avoid jargon, acronyms on first use, and insider terminology unless the
105	audience requires it
106	* Define technical terms inline; spell out abbreviations on first use
107	* Front-load key information — most important point first
108	* Use the second person ("you") to speak directly to the reader
109	* Avoid double negatives and conditional stacking — write "Complete all required
110	fields to proceed" instead of "You can only proceed if you have not failed to
111	complete the required fields"
112	* Prefer short, concrete words over long, abstract ones ("use" instead of
113	"utilize")
114	* Run a readability checker before publishing; target Flesch-Kincaid Grade 8 or
115	lower for general audiences
116
117	---
118
119	## Moderate: Tables
120
121	* Use only for genuinely tabular data — never for layout (Critical if layout
122	table has no `role="presentation"`)
123	* `<caption>` or heading explaining what the table contains
124	* Header cells marked with `<th scope="col">` or `<th scope="row">`
125	* Keep tables simple; avoid merging cells unless necessary
126	* Provide a text summary for complex tables
127
128	**Missing `scope` on a simpl

People who liked this also viewed

6 picks

Type

content-design

27stars2forks

View on GitHub

How to install content-design?

mgifford/accessibility-skills/content-design

$npx -y skills add mgifford/accessibility-skills --skill content-design

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Content Design Accessibility Skill
2
3	> Canonical source: `examples/CONTENT_DESIGN_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 writing, editing, or reviewing any web content.
7
8	---
9
10	## Core Mandate
11
12	Content design and accessibility are inseparable. A technically accessible page that
13	is confusing or poorly structured still creates barriers. Design content for the
14	widest possible audience: write clearly, structure logically, and present
15	information in the order users need it.
16
17	---
18
19	## Severity Scale (this skill)
20
21	\| Level \| Meaning \|
22	\| --- \| --- \|
23	\| Critical \| Content is completely inaccessible or incomprehensible to a disability group \|
24	\| Serious \| Significant barrier; unreasonable to expect workaround \|
25	\| Moderate \| Creates friction; workaround exists and is not too burdensome \|
26	\| Minor \| Best-practice gap; marginal impact \|
27
28	---
29
30	## Critical: Images Must Have Appropriate Text Alternatives
31
32	A meaningful image with no `alt` attribute or `alt=""` is Critical —
33	blind users receive no information. A decorative image with descriptive `alt` is
34	Moderate — it adds noise but does not block information.
35
36	* Every informative image needs meaningful alt text that conveys its purpose, not
37	just its appearance
38	* Decorative images: `alt=""` (empty string — the attribute must still be present)
39	* Do not rely on images alone to convey information; support visual content with
40	accompanying text
41	* Charts and graphs must be accompanied by a text summary or accessible data table
42	(see `skills/charts-graphs/SKILL.md`)
43	* For diagram-specific guidance, see `skills/svg/SKILL.md`
44
45	---
46
47	## Serious: All Link Text Must Make Sense Out of Context
48
49	"Click here", "Read more", and "Learn more" are Serious — screen reader
50	users navigate by links and hear them without surrounding context.
51
52	```html
53	<!-- Serious issue -->
54	<a href="/report">Read more</a>
55
56	<!-- Good -->
57	<a href="/report">2024 Accessibility Annual Report</a>
58	```
59
60	For document links, include file type and size:
61
62	```html
63	<a href="/report.pdf">2024 Annual Report (PDF, 2.3 MB)</a>
64	```
65
66	Warn users when links open in new tabs:
67
68	```html
69	<a href="/report" target="_blank">
70	Annual Report
71	<span class="visually-hidden">(opens in new tab)</span>
72	</a>
73	```
74
75	Use consistent terminology: if a concept is called "accessibility statement" in
76	one place, do not call it "a11y disclosure" somewhere else.
77
78	---
79
80	## Serious: Heading Hierarchy Must Be Logical
81
82	Skipping heading levels is Moderate; having no `<h1>` or using headings
83	purely for visual styling is Serious — screen reader users rely on headings
84	for page navigation.
85
86	* One `<h1>` per page describing the page's main purpose
87	* Logical hierarchy: `h1` → `h2` → `h3` (do not skip levels)
88	* Headings must be descriptive and unique — not "Introduction" or "Overview" alone
89	* Write headings as statements or clear topic labels, not questions (unless FAQ
90	format is appropriate)
91	* Navigation labels, button text, and form labels must be descriptive and
92	unambiguous out of context
93
94	---
95
96	## Moderate: Plain Language
97
98	Overly complex language is Moderate — it creates real barriers for users
99	with cognitive disabilities and low literacy, but the content is technically
100	still present.
101
102	* Common words, short sentences, active voice
103	* Target Grade 8 reading level or lower for general audiences
104	* Avoid jargon, acronyms on first use, and insider terminology unless the
105	audience requires it
106	* Define technical terms inline; spell out abbreviations on first use
107	* Front-load key information — most important point first
108	* Use the second person ("you") to speak directly to the reader
109	* Avoid double negatives and conditional stacking — write "Complete all required
110	fields to proceed" instead of "You can only proceed if you have not failed to
111	complete the required fields"
112	* Prefer short, concrete words over long, abstract ones ("use" instead of
113	"utilize")
114	* Run a readability checker before publishing; target Flesch-Kincaid Grade 8 or
115	lower for general audiences
116
117	---
118
119	## Moderate: Tables
120
121	* Use only for genuinely tabular data — never for layout (Critical if layout
122	table has no `role="presentation"`)
123	* `<caption>` or heading explaining what the table contains
124	* Header cells marked with `<th scope="col">` or `<th scope="row">`
125	* Keep tables simple; avoid merging cells unless necessary
126	* Provide a text summary for complex tables
127
128	**Missing `scope` on a simpl

People who liked this also viewed

6 picks

Type