content-design · git:20260331.0b2aead · 2026-03-31 · sha256 8bf7c2cc9921865a
content-design git:20260331.0b2aeadC
Immutable. This exact content never changes and is served at /api/v1/blob/8bf7c2cc9921865a.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_m72dss6hw6zdibv2/8bf7c2cc9921865a7fe04ec2e6f26f29d573b48c1054c95a15d0a59a9012af07.json
Then /plugin install content-design@markdownregistry-m72dss6hw6zdibv2 in Claude Code. It installs this exact version, the one graded C here, pinned to the commit it was graded at, and leaves it there.
# 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. ```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> ``` --- ## 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](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/) > **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/>