| name | content-design |
| description | 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 language differences. Absolutely always apply plain language, logical heading hierarchy, and meaningful link text.
|
Content Design Accessibility Skill
Canonical source: examples/CONTENT_DESIGN_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 writing, editing, or reviewing any web content.
Core Mandate
A technically accessible page that is confusing or poorly structured still creates
barriers. Design content for the widest possible audience: write clearly, structure
logically, and present information in the order users need it.
Severity Scale (this skill)
| Level | Meaning |
|---|
| Critical | Content is completely inaccessible or incomprehensible to a disability group |
| Serious | Significant barrier; unreasonable to expect workaround |
| Moderate | Creates friction; workaround exists and is not too burdensome |
| Minor | Best-practice gap; marginal impact |
Critical: Images Must Have Appropriate Text Alternatives
A meaningful image with no alt attribute or alt="" is Critical —
blind users receive no information. A decorative image with descriptive alt is
Moderate — it adds noise but does not block information.
- Meaningful images:
alt text that conveys purpose, not appearance
- Decorative images:
alt="" (empty string — the attribute must still be present)
Serious: All Link Text Must Make Sense Out of Context
"Click here", "Read more", and "Learn more" are Serious — screen reader
users navigate by links and hear them without surrounding context.
<a href="/report">Read more</a>
<a href="/report">2024 Accessibility Annual Report</a>
For document links, include file type and size:
<a href="/report.pdf">2024 Annual Report (PDF, 2.3 MB)</a>
Warn users when links open in new tabs:
<a href="/report" target="_blank">
Annual Report
<span class="visually-hidden">(opens in new tab)</span>
</a>
Serious: Heading Hierarchy Must Be Logical
Skipping heading levels is Moderate; having no <h1> or using headings
purely for visual styling is Serious — screen reader users rely on headings
for page navigation.
- One
<h1> per page describing the page's main purpose
- Logical hierarchy:
h1 → h2 → h3 (do not skip levels)
- Headings must be descriptive and unique — not "Introduction" alone
Moderate: Plain Language
Overly complex language is Moderate — it creates real barriers for users
with cognitive disabilities and low literacy, but the content is technically
still present.
- Common words, short sentences, active voice
- Target Grade 8 reading level or lower for general audiences
- Define technical terms inline; spell out abbreviations on first use
- Front-load key information — most important point first
- Avoid double negatives and conditional stacking
- Run a readability checker before publishing; target Flesch-Kincaid Grade 8 or lower
Moderate: Tables
- Use only for genuinely tabular data — never for layout (Critical if layout table has no
role="presentation")
<caption> or heading explaining what the table contains- Header cells marked with
<th scope="col"> or <th scope="row">
Missing scope on a simple table is Moderate; missing it on a complex table
with multiple header rows is Serious.
Moderate: Page Structure
- Use lists for three or more parallel items (not embedded in prose)
- Short paragraphs: 3–5 sentences maximum
- Inverted pyramid: most critical content at top
Moderate: Forms — Writing Requirements
- Write form instructions before the form
- Label fields with what the user needs to enter
- Provide format examples for unusual inputs:
Date: DD/MM/YYYY
- Error messages must describe the problem and the fix
(For code-level form requirements, also load skills/forms/SKILL.md.)
Minor: Writing Style Details
- Active voice preferred: "The form saves your data" not "Your data is saved"
- Present tense where possible
- Gender-neutral and inclusive language throughout
- Consistent terminology: one term per concept across the site
- Unique, descriptive page
<title> elements
Definition of Done Checklist
Key WCAG Criteria
- 1.1.1 Non-text Content (A) — Critical if meaningful images lack alt
- 1.3.1 Info and Relationships (A)
- 2.4.4 Link Purpose in Context (AA) — Serious if links are ambiguous
- 2.4.6 Headings and Labels (AA)
- 2.4.2 Page Titled (A)
- 3.1.5 Reading Level (AAA — target for general audiences)
References
Standards horizon: WCAG 3.0 is in development. Content design
requirements are not expected to change substantially.
Monitor: https://www.w3.org/TR/wcag-3.0/
