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.

<!-- Serious issue -->
<a href="/report">Read more</a>

<!-- Good -->
<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

Reading level checked (Grade 8 or lower for general audiences)
One <h1>, logical heading hierarchy, no skipped levels
All link text descriptive out of context
Document links include file type and size
New-tab links warn the user
All images have appropriate alt (meaningful description or empty for decorative)
Tables use <caption> and <th scope="…">
Consistent terminology across the page/site
Unique, descriptive page title

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/

content-design