OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add mgifford/accessibility-skills --skill plain-language
Load this skill whenever the project involves writing, editing, or reviewing content for a general audience, including UI copy, help text, error messages, documentation, and instructions. Under no circumstances use jargon, complex sentence structures, or unexplained acronyms without providing plain alternatives. Absolutely always target a reading level accessible to the broadest possible audience. Load alongside content-design/SKILL.md for all content work.
npx skills add mgifford/accessibility-skills --skill plain-language
Canonical source:
examples/PLAIN_LANGUAGE_ACCESSIBILITY_BEST_PRACTICES.mdinmgifford/ACCESSIBILITY.mdThis skill is derived from that file. When in doubt, the example is authoritative.
Apply these rules when writing, editing, or reviewing web content. Only load this skill if the project involves content creation or editing.
This skill complements content-design/SKILL.md — load both for content work.
Plain language is the deeper implementation; content design is the structural pattern.
Plain language means writing so that people can find what they need, understand it, and act on it the first time they read it. It is not about dumbing content down — it is about respecting the reader's time and removing unnecessary barriers.
Plain language is the primary accessibility strategy for:
WCAG 3.1.5 Reading Level (AAA) targets Grade 8 or lower for general audiences. Plain language is also an Opquast requirement (rules 5, 7) and aligns with the Web Sustainability Guidelines — concise content reduces data transfer and reading time.
| Level | Meaning |
|---|---|
| Critical | Content is entirely incomprehensible to the target audience; essential instructions cannot be followed |
| Serious | Dense jargon or complex sentence structure creates a significant barrier for users with cognitive disabilities |
| Moderate | Reading level above Grade 8; abbreviations unexpanded; passive voice dominates |
| Minor | Opportunities to shorten or clarify that do not create a barrier |
Plain language matters differently across AT:
| AT | How plain language helps |
|---|---|
| Screen readers (NVDA, JAWS, VoiceOver) | Short sentences reduce cognitive load when re-listening; heading hierarchy aids navigation |
| Reader Mode (Firefox/Edge/Safari) | Strips visual hierarchy — plain language structure must carry meaning alone |
| Edge Read Aloud / TalkBack TTS | Long sentences with many clauses are harder to parse when heard |
| Voice Control | Clear, short headings and labels are easier to speak as navigation targets |
| Screen magnification | Users see small portions at a time — front-loaded key information reduces scrolling |
| Cognitive accessibility tools (e.g., Helperbird, Recite Me) | These reformat content; simple structures reformat better than complex ones |
Plain language begins with structure. A well-structured page with mediocre prose is more accessible than beautiful prose with poor structure.
Put the conclusion first, then the evidence. Readers should not have to reach the end of a paragraph to understand what it is about.
This structure serves screen reader users (who navigate by heading), search engine users, and users in crisis who need the answer immediately.
Long sentences and paragraphs are a Serious barrier for users with cognitive disabilities, dyslexia, and low literacy.
Sentences:
Paragraphs:
Passive voice hides the actor and increases cognitive load. Use active voice unless there is a deliberate reason not to.
When to use passive voice deliberately:
Use the word your reader already knows. Technical terminology is appropriate for expert audiences; general audiences need plain equivalents.
| Instead of | Use |
|---|---|
| utilise | use |
| commence | start |
| endeavour | try |
| prior to | before |
| in the event that | if |
| at this point in time | now |
| facilitate | help |
| demonstrate | show |
| subsequently | then / after |
| approximately | about |
Domain-specific terms (legal, medical, technical): define them on first use inline, not in a separate glossary unless the audience is expert.
Target Grade 8 or lower (Flesch-Kincaid) for general public content. Above Grade 10 is Moderate; above Grade 12 is Serious for public-facing content.
Tools for checking reading level:
retext-readability — CI-integrable readability linterGrade level is a guide, not an absolute rule. Legal or regulatory text may require precision that raises the grade level — acknowledge this and provide a plain language summary alongside the formal text.
Unexpanded abbreviations are a Moderate barrier — screen readers may mispronounce them; new readers do not know them.
Rule: Expand on first use on every page (not just the first page of the site).
<abbr title="..."> provides the expansion to AT and on hover for sighted users.
Screen readers handle <abbr> inconsistently — the expansion in the title
attribute is read by some but not all AT. Always write the expansion in text on
first use regardless of whether you use <abbr>.
Use lists for three or more parallel items. Embedding lists in prose hides the structure and increases cognitive load.
Use <ul> for unordered lists, <ol> for steps or sequences that must be
followed in order.
Number steps. Place the action before the context (not after).
<title> must identify the page and the site: "About Us | Acme Corp"<h1> per page; must match or closely reflect the <title>Run these checks before publishing:
<title> in "Page | Site" format<h1>; headings descriptive and hierarchicallang attribute on <html>lang on elements in a different languageStandards horizon: WCAG 3.0 is in development. Plain language requirements are expected to expand, not contract, particularly around cognitive accessibility. Monitor: https://www.w3.org/TR/wcag-3.0/
✗ Decisions will be made by the committee.
✗ Applications must be submitted before the deadline.
✗ Your account may be suspended if payment is not received.
✓ The committee will decide.
✓ Submit your application before the deadline.
✓ We will suspend your account if we do not receive payment.<!-- First use: define inline -->
<p>Your <abbr title="General Data Protection Regulation">GDPR</abbr> rights
allow you to request a copy of your personal data.</p>
<!-- Subsequent uses: abbreviation alone is acceptable -->
<p>To exercise your GDPR rights, contact our data protection team.</p><p>The <abbr title="Web Content Accessibility Guidelines">WCAG</abbr> are
published by the W3C. WCAG version 2.2 is the current standard.</p>✗ You will need to provide your full name, date of birth, current address,
email address, and a copy of your identification document.
✓ You will need:
• Full name
• Date of birth
• Current address
• Email address
• A copy of your identification document✗ After logging in, which you can do from the homepage, click the Settings
icon in the top-right corner of the screen, then select Account.
✓ To update your account:
1. Log in at [homepage link].
2. Click Settings (top-right corner).
3. Select Account.