content-design · diff
git:20260331.f09d889 to git:20260722.125074b
86 added, 16 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
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.
+ 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.
- * Meaningful images: `alt` text that conveys purpose, not appearance
+ * 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.
```html
<!-- 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:
```html
<a href="/report.pdf">2024 Annual Report (PDF, 2.3 MB)</a>
```
Warn users when links open in new tabs:
```html
<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" alone
+ * 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
- * Avoid double negatives and conditional stacking
- * Run a readability checker before publishing; target Flesch-Kincaid Grade 8 or lower
+ * 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"`)
+ * 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**.
+ with multiple header rows is **Serious**. (For code-level table requirements, also
+ load `skills/tables/SKILL.md`.)
---
- ## Moderate: Page Structure
+ ## Moderate: Page and Content Structure
- * Use lists for three or more parallel items (not embedded in prose)
- * Short paragraphs: 3–5 sentences maximum
+ * 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
- * Label fields with what the user needs to enter
+ * 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
+ * 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
+ * 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](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/examples/CONTENT_DESIGN_ACCESSIBILITY_BEST_PRACTICES.md)
* [Plain Language Guidelines (digital.gov)](https://digital.gov/guides/plain-language)
* [Hemingway Editor — readability tool](https://hemingwayapp.com/)
+ * [Canada.ca Content Style Guide](https://design.canada.ca/style-guide/)
+ * [GOV.UK Style Guide](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/style-guides/)
+ * [California ODI Content Design Guide](https://hub.innovation.ca.gov/content-design/odi-style-guide/)
+ * [ONS Content Guide: Structuring Content](https://service-manual.ons.gov.uk/content/writing-for-users/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/>