Content design

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

Content design and accessibility are inseparable. 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.

• Every informative image needs meaningful alt text that conveys its purpose, not just its appearance
• Decorative images: alt="" (empty string — the attribute must still be present)
• Do not rely on images alone to convey information; support visual content with accompanying text
• Charts and graphs must be accompanied by a text summary or accessible data table (see skills/charts-graphs/SKILL.md)
• For diagram-specific guidance, see skills/svg/SKILL.md

---

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>

Use consistent terminology: if a concept is called "accessibility statement" in one place, do not call it "a11y disclosure" somewhere else.

---

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" or "Overview" alone
• Write headings as statements or clear topic labels, not questions (unless FAQ format is appropriate)
• Navigation labels, button text, and form labels must be descriptive and unambiguous out of context

---

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
• Avoid jargon, acronyms on first use, and insider terminology unless the audience requires it
• Define technical terms inline; spell out abbreviations on first use
• Front-load key information — most important point first
• Use the second person ("you") to speak directly to the reader
• Avoid double negatives and conditional stacking — write "Complete all required fields to proceed" instead of "You can only proceed if you have not failed to complete the required fields"
• Prefer short, concrete words over long, abstract ones ("use" instead of "utilize")
• Run a readability checker before publishing; target Flesch-Kincaid Grade 8 or lower for general audiences

---

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">
• Keep tables simple; avoid merging cells unless necessary
• Provide a text summary for complex tables

Missing scope on a simple table is Moderate; missing it on a complex table with multiple header rows is Serious. (For code-level table requirements, also load skills/tables/SKILL.md.)

---

Moderate: Page and Content Structure

• Use lists for three or more parallel items (not embedded in dense prose)
• Short paragraphs: 3–5 sentences maximum; one idea per paragraph
• Inverted pyramid: most critical content at top
• Use white space generously

---

Moderate: Forms — Writing Requirements

• Write form instructions before the form, not inside it
• Label fields with what the user needs to enter, not how the system stores it
• Provide format examples for unusual inputs: Date: DD/MM/YYYY
• Error messages must describe the problem and the fix — avoid system error codes

(For code-level form requirements, also load skills/forms/SKILL.md.)

---

Moderate: Cognitive Accessibility

• Supplement complex content with summaries, key takeaways, or "what you need to know" sections
• Break long processes into numbered steps
• Use examples and analogies to explain abstract concepts
• Avoid time-pressured content presentation where possible
• Provide enough context so users can understand content without relying on memory of prior sections

---

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; maintain a content style guide and a defined voice/tone applied consistently
• Unique, descriptive page <title> elements
• Review content periodically to remove outdated, misleading, or contradictory information

---

Minor: Content for Diverse Audiences

• Assume a broad audience that includes people with cognitive, learning, and language differences
• Provide content in more than one format where feasible (e.g., video summary alongside written guidance)
• Consider whether translations or Easy Read versions are appropriate
• Avoid idioms, metaphors, or culturally specific references that may not translate

---

Testing and Review

• Read content aloud to check for clarity and natural flow
• Have someone unfamiliar with the topic review it before publishing
• Test page navigation with keyboard only and confirm headings convey structure
• Use a screen reader to verify the content makes sense in linear reading order
• Check that all links are descriptive and functional
• Run a readability score on key pages and track it over time

---

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
• Reviewed by someone outside the team

---

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
• Canada.ca Content Style Guide
• GOV.UK Style Guide
• California ODI Content Design Guide
• ONS Content Guide: Structuring Content

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/