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)

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.

htmlCopy code
<!-- 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:

htmlCopy code
<a href="/report.pdf">2024 Annual Report (PDF, 2.3 MB)</a>

Warn users when links open in new tabs:

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