/accessible-content

name: accessible-content
description: Use when writing or structuring any user-facing content — interface copy, labels, error messages, help text, headings, alt text, link text, or form instructions — ensures content is readable, navigable, and meaningful for everyone

Accessible Content

Words are interface. Every label, every heading, every error message is a design decision. This skill ensures content works for screen readers, for people reading in a second language, for people under stress, and for people who just need things to be clear.

When to Use

• Writing interface labels, button text, or form instructions
• Structuring headings and page hierarchy
• Writing error messages or help text
• Creating alt text for images
• Writing link text
• Structuring data tables
• Any time words appear on screen

Process

Step 1: Plain Language First

Every piece of content should meet these criteria:

• **Reading level:** aim for a reading age of 12-14 (roughly 6th-8th grade). Use short sentences and common words
• **One idea per sentence.** If a sentence has "and" in the middle, consider splitting it
• **Active voice.** "We sent your confirmation" not "Your confirmation has been sent"
• **Specific over vague.** "Save your changes" not "Submit" or "OK"
• **No jargon** unless the audience demonstrably uses it. When jargon is necessary, provide a plain explanation

Step 2: Heading Structure

Headings are navigation for screen readers. Get the structure right:

• **One H1 per page** — describes the page purpose
• **Headings follow a logical hierarchy** — H1 → H2 → H3, never skip levels
• **Headings are descriptive** — a screen reader user scanning headings alone should understand the page structure
• **Do not use headings for visual styling** — if you need big bold text that is not a heading, use CSS

Step 3: Form Labels and Instructions

Every form input must have:

• **A visible label** — placeholders are not labels (they disappear on focus)
• **Programmatic association** — `<label for="id">` or `aria-labelledby`
• **Required field indication** — visible and announced, not just an asterisk
• **Format hints** — "DD/MM/YYYY" before the input, not after
• **Error association** — `aria-describedby` linking the input to its error message

Step 4: Alt Text

Alt text is content, not metadata:

| Image Type | Alt Text Approach | |-----------|------------------| | Informative image | Describe the information the image conveys, not the image itself | | Decorative image | Empty alt (`alt=""`) — do not describe decorative images | | Functional image (button/link) | Describe the action, not the image ("Search", not "magnifying glass") | | Complex image (chart/graph) | Brief alt + detailed description in surrounding text or `<details>` | | Image of text | Reproduce the full text content |

Step 5: Link Text

Links must make sense out of context (screen reader users often navigate by links alone):

• Yes: "Read the accessibility guidelines"
• No: "Click here" or "Read more" or "Learn more"
• If multiple "Read more" links exist on a page, each must be distinguishable (via `aria-label` or visible text)

Step 6: Error Messages

Follow the pattern: **[What happened] + [What to do]**

• Keep the language neutral — never blame the user
• Be specific about what needs to change
• Place the error message adjacent to the relevant field
• Announce errors to screen readers via `aria-live="assertive"` or by moving focus

Step 7: Tables

Data tables need:

• `<caption>` describing the table's purpose
• `<th>` elements with `scope="col"` or `scope="row"`
• No layout tables — use CSS Grid or Flexbox for layout
• If a table is complex, provide a text summary

Step 8: Content Review

Before finalising any content, verify:

• [ ] Every interactive element has a visible, descriptive label
• [ ] Heading hierarchy is logical and complete
• [ ] Link text makes sense out of context
• [ ] Error messages explain both the problem and the solution
• [ ] Alt text is present and appropriate for every image
• [ ] Reading level is appropriate for the audience
• [ ] Content works when translated (avoid idioms, cultural references that do not travel)

Integration

• **Called by:** `writing-design-plans`, `ui-composition`, `interaction-design`
• **Pairs with:** `cognitive-accessibility` (reading load), `inclusive-personas` (audience awareness)
• **Reviewed by:** `designpowers-critique`