OpenParable
Skip to content
← Back to skills

Accessible Content

Design
accessible-content

Accessible Content is an Agent Skill for design published in the Owl-Listener/designpowers repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Owl-Listener/designpowers/blob/HEAD/skills/accessible-content/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/accessible-content, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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 TypeAlt Text Approach
Informative imageDescribe the information the image conveys, not the image itself
Decorative imageEmpty 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 textReproduce 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