Skill: accessibility-writing
What I do
I help you create documentation that everyone can read and understand. I focus on making content accessible to users with visual impairments, cognitive disabilities, or those who use assistive technology like screen readers. I ensure your technical writing is clear, structured, and inclusive.
When to use me
- When you're writing READMEs, guides, or API docs.
- When you're adding images or diagrams to your documentation.
- When you're structuring complex information in tables or lists.
- When you're choosing link text or headings.
Core principles
- Clarity over cleverness, use plain language and avoid unnecessary jargon.
- Logical structure, use headings to create a clear hierarchy that reflects the content's importance.
- Redundancy for resilience, don't rely on colour or shape alone to convey meaning.
- Descriptive context, ensure all non-text elements have meaningful text alternatives.
Patterns & examples
Plain language and reading levels
Aim for a reading level that's easy to grasp. Use short sentences and active voice.
- Good, "Run this command to start the server."
- Bad, "The execution of the following command is required for the initiation of the server process."
Meaningful link text
Links should tell the user where they're going without needing to read the surrounding text.
Heading hierarchy
Always use headings in a linear order. Don't skip levels just for styling.
- Correct, H1 -> H2 -> H3 -> H2 -> H3
- Incorrect, H1 -> H3 -> H5
Alt text for diagrams
Describe what the diagram shows and why it matters.
- Example,
Anti-patterns to avoid
- ❌ "Click here" links, screen reader users often navigate via links alone. "Click here" gives no context.
- ❌ Empty alt text, leaving alt tags empty makes images invisible to screen readers, unless they're purely decorative.
- ❌ Skipping heading levels, this breaks the document's outline for assistive technology.
- ❌ Relying on colour, don't say "the red button" without adding a text label or icon.
KB Reference
~/vaults/baphled/3. Resources/Knowledge Base/AI Development System/Skills/Communication-Writing/Accessibility Writing.md
Related skills
documentation-writing, for general documentation structure.writing-style, to keep a consistent voice.ui-design, for visual accessibility in interfaces.ux-design, for inclusive user journeys.
1---2name: accessibility-writing3description: Guide creating accessible documentation and content for everyone4---5
6# Skill: accessibility-writing
7
8## What I do
9
10I help you create documentation that everyone can read and understand. I focus on making content accessible to users with visual impairments, cognitive disabilities, or those who use assistive technology like screen readers. I ensure your technical writing is clear, structured, and inclusive.
11
12## When to use me
13
14- When you're writing READMEs, guides, or API docs.
15- When you're adding images or diagrams to your documentation.
16- When you're structuring complex information in tables or lists.
17- When you're choosing link text or headings.
18
19## Core principles
20
211. **Clarity over cleverness**, use plain language and avoid unnecessary jargon.
222. **Logical structure**, use headings to create a clear hierarchy that reflects the content's importance.
233. **Redundancy for resilience**, don't rely on colour or shape alone to convey meaning.
244. **Descriptive context**, ensure all non-text elements have meaningful text alternatives.
25
26## Patterns & examples
27
28### Plain language and reading levels
29Aim for a reading level that's easy to grasp. Use short sentences and active voice.
30- **Good**, "Run this command to start the server."
31- **Bad**, "The execution of the following command is required for the initiation of the server process."
32
33### Meaningful link text
34Links should tell the user where they're going without needing to read the surrounding text.
35- **Good**, "Read the [installation guide](/docs/install) for more details."
36- **Bad**, "[Click here](/docs/install) to read more about installation."
37
38### Heading hierarchy
39Always use headings in a linear order. Don't skip levels just for styling.
40- **Correct**, H1 -> H2 -> H3 -> H2 -> H3
41- **Incorrect**, H1 -> H3 -> H5
42
43### Alt text for diagrams
44Describe what the diagram shows and why it matters.
45- **Example**, ``
46
47## Anti-patterns to avoid
48
49- ❌ **"Click here" links**, screen reader users often navigate via links alone. "Click here" gives no context.
50- ❌ **Empty alt text**, leaving alt tags empty makes images invisible to screen readers, unless they're purely decorative.
51- ❌ **Skipping heading levels**, this breaks the document's outline for assistive technology.
52- ❌ **Relying on colour**, don't say "the red button" without adding a text label or icon.
53
54## KB Reference
55
56`~/vaults/baphled/3. Resources/Knowledge Base/AI Development System/Skills/Communication-Writing/Accessibility Writing.md`
57
58## Related skills
59
60- `documentation-writing`, for general documentation structure.
61- `writing-style`, to keep a consistent voice.
62- `ui-design`, for visual accessibility in interfaces.
63- `ux-design`, for inclusive user journeys.
majiayu000