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)

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

• Full best practices guide
• Plain Language Guidelines (digital.gov)
• Hemingway Editor — readability tool

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/>