plain-language

Name: plain-language
Author: mgifford

27stars2forks

How to install plain-language?

mgifford/accessibility-skills/plain-language

$npx -y skills add mgifford/accessibility-skills --skill plain-language

Installs into the current project.

Summary

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 with

Files · 1

View on GitHub

SKILL.md

1	# Plain Language Accessibility Skill
2
3	> Canonical source: `examples/PLAIN_LANGUAGE_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when writing, editing, or reviewing web content.
7	Only load this skill if the project involves content creation or editing.
8
9	This skill complements `content-design/SKILL.md` — load both for content work.
10	Plain language is the deeper implementation; content design is the structural pattern.
11
12	---
13
14	## Core Mandate
15
16	Plain language means writing so that people can find what they need, understand
17	it, and act on it the first time they read it. It is not about dumbing content
18	down — it is about respecting the reader's time and removing unnecessary barriers.
19
20	Plain language is the primary accessibility strategy for:
21	- Users with cognitive disabilities, learning disabilities, and intellectual disabilities
22	- Users with low literacy or whose first language is not the page language
23	- Users who are stressed, fatigued, or in crisis
24	- Users accessing content via screen reader, where re-reading is slow
25	- Users in reader mode or using text-to-speech, where complex syntax breaks down
26
27	WCAG 3.1.5 Reading Level (AAA) targets Grade 8 or lower for general audiences.
28	Plain language is also an Opquast requirement (rules 5, 7) and aligns with the
29	[Web Sustainability Guidelines](https://www.w3.org/TR/web-sustainability-guidelines/) —
30	concise content reduces data transfer and reading time.
31
32	---
33
34	## Severity Scale (this skill)
35
36	\| Level \| Meaning \|
37	\|---\|---\|
38	\| Critical \| Content is entirely incomprehensible to the target audience; essential instructions cannot be followed \|
39	\| Serious \| Dense jargon or complex sentence structure creates a significant barrier for users with cognitive disabilities \|
40	\| Moderate \| Reading level above Grade 8; abbreviations unexpanded; passive voice dominates \|
41	\| Minor \| Opportunities to shorten or clarify that do not create a barrier \|
42
43	---
44
45	## Assistive Technology Context
46
47	Plain language matters differently across AT:
48
49	\| AT \| How plain language helps \|
50	\|---\|---\|
51	\| Screen readers (NVDA, JAWS, VoiceOver) \| Short sentences reduce cognitive load when re-listening; heading hierarchy aids navigation \|
52	\| Reader Mode (Firefox/Edge/Safari) \| Strips visual hierarchy — plain language structure must carry meaning alone \|
53	\| Edge Read Aloud / TalkBack TTS \| Long sentences with many clauses are harder to parse when heard \|
54	\| Voice Control \| Clear, short headings and labels are easier to speak as navigation targets \|
55	\| Screen magnification \| Users see small portions at a time — front-loaded key information reduces scrolling \|
56	\| Cognitive accessibility tools (e.g., Helperbird, Recite Me) \| These reformat content; simple structures reformat better than complex ones \|
57
58	---
59
60	## Critical: Structure Before Prose
61
62	Plain language begins with structure. A well-structured page with mediocre prose
63	is more accessible than beautiful prose with poor structure.
64
65	### One topic per page; one idea per paragraph
66
67	```
68	✗ This page covers our history, our services, our pricing, and how to contact us.
69
70	✓ Separate pages for: About us / Services / Pricing / Contact
71	```
72
73	### Front-load the key information
74
75	Put the conclusion first, then the evidence. Readers should not have to reach
76	the end of a paragraph to understand what it is about.
77
78	```
79	✗ After reviewing several options and consulting with our legal team, we have
80	decided that applications submitted after 31 March will not be accepted.
81
82	✓ Applications close 31 March. We will not accept late submissions.
83	```
84
85	### Inverted pyramid: most important → supporting detail → background
86
87	This structure serves screen reader users (who navigate by heading), search
88	engine users, and users in crisis who need the answer immediately.
89
90	---
91
92	## Serious: Sentence and Paragraph Length
93
94	Long sentences and paragraphs are a Serious barrier for users with
95	cognitive disabilities, dyslexia, and low literacy.
96
97	Sentences:
98	- Target 15–20 words maximum for most sentences
99	- One main clause per sentence; move subordinate clauses to their own sentence
100	- Remove hedges and qualifications where possible: "It should be noted that" → remove it
101
102	Paragraphs:
103	- 3–5 sentences maximum for general web content
104	- One main idea per paragraph
105	- Use blank lines between paragraphs (not just indentation)
106
107	```
108	✗ Due to the fact that the application pro

People who liked this also viewed

6 picks

Type

plain-language

27stars2forks

View on GitHub

How to install plain-language?

mgifford/accessibility-skills/plain-language

$npx -y skills add mgifford/accessibility-skills --skill plain-language

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Plain Language Accessibility Skill
2
3	> Canonical source: `examples/PLAIN_LANGUAGE_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
4	> This skill is derived from that file. When in doubt, the example is authoritative.
5
6	Apply these rules when writing, editing, or reviewing web content.
7	Only load this skill if the project involves content creation or editing.
8
9	This skill complements `content-design/SKILL.md` — load both for content work.
10	Plain language is the deeper implementation; content design is the structural pattern.
11
12	---
13
14	## Core Mandate
15
16	Plain language means writing so that people can find what they need, understand
17	it, and act on it the first time they read it. It is not about dumbing content
18	down — it is about respecting the reader's time and removing unnecessary barriers.
19
20	Plain language is the primary accessibility strategy for:
21	- Users with cognitive disabilities, learning disabilities, and intellectual disabilities
22	- Users with low literacy or whose first language is not the page language
23	- Users who are stressed, fatigued, or in crisis
24	- Users accessing content via screen reader, where re-reading is slow
25	- Users in reader mode or using text-to-speech, where complex syntax breaks down
26
27	WCAG 3.1.5 Reading Level (AAA) targets Grade 8 or lower for general audiences.
28	Plain language is also an Opquast requirement (rules 5, 7) and aligns with the
29	[Web Sustainability Guidelines](https://www.w3.org/TR/web-sustainability-guidelines/) —
30	concise content reduces data transfer and reading time.
31
32	---
33
34	## Severity Scale (this skill)
35
36	\| Level \| Meaning \|
37	\|---\|---\|
38	\| Critical \| Content is entirely incomprehensible to the target audience; essential instructions cannot be followed \|
39	\| Serious \| Dense jargon or complex sentence structure creates a significant barrier for users with cognitive disabilities \|
40	\| Moderate \| Reading level above Grade 8; abbreviations unexpanded; passive voice dominates \|
41	\| Minor \| Opportunities to shorten or clarify that do not create a barrier \|
42
43	---
44
45	## Assistive Technology Context
46
47	Plain language matters differently across AT:
48
49	\| AT \| How plain language helps \|
50	\|---\|---\|
51	\| Screen readers (NVDA, JAWS, VoiceOver) \| Short sentences reduce cognitive load when re-listening; heading hierarchy aids navigation \|
52	\| Reader Mode (Firefox/Edge/Safari) \| Strips visual hierarchy — plain language structure must carry meaning alone \|
53	\| Edge Read Aloud / TalkBack TTS \| Long sentences with many clauses are harder to parse when heard \|
54	\| Voice Control \| Clear, short headings and labels are easier to speak as navigation targets \|
55	\| Screen magnification \| Users see small portions at a time — front-loaded key information reduces scrolling \|
56	\| Cognitive accessibility tools (e.g., Helperbird, Recite Me) \| These reformat content; simple structures reformat better than complex ones \|
57
58	---
59
60	## Critical: Structure Before Prose
61
62	Plain language begins with structure. A well-structured page with mediocre prose
63	is more accessible than beautiful prose with poor structure.
64
65	### One topic per page; one idea per paragraph
66
67	```
68	✗ This page covers our history, our services, our pricing, and how to contact us.
69
70	✓ Separate pages for: About us / Services / Pricing / Contact
71	```
72
73	### Front-load the key information
74
75	Put the conclusion first, then the evidence. Readers should not have to reach
76	the end of a paragraph to understand what it is about.
77
78	```
79	✗ After reviewing several options and consulting with our legal team, we have
80	decided that applications submitted after 31 March will not be accepted.
81
82	✓ Applications close 31 March. We will not accept late submissions.
83	```
84
85	### Inverted pyramid: most important → supporting detail → background
86
87	This structure serves screen reader users (who navigate by heading), search
88	engine users, and users in crisis who need the answer immediately.
89
90	---
91
92	## Serious: Sentence and Paragraph Length
93
94	Long sentences and paragraphs are a Serious barrier for users with
95	cognitive disabilities, dyslexia, and low literacy.
96
97	Sentences:
98	- Target 15–20 words maximum for most sentences
99	- One main clause per sentence; move subordinate clauses to their own sentence
100	- Remove hedges and qualifications where possible: "It should be noted that" → remove it
101
102	Paragraphs:
103	- 3–5 sentences maximum for general web content
104	- One main idea per paragraph
105	- Use blank lines between paragraphs (not just indentation)
106
107	```
108	✗ Due to the fact that the application pro

People who liked this also viewed

6 picks

Type