javimontano/accessibility-writing

Accessibility Writing

Accessible writing helps more people understand, decide, recover, and act.

TL;DR

Use this skill to turn copy, UI text, docs, image descriptions, error messages, and instructions into accessible writing. It produces clean reader-facing copy plus a separate validation note with assumptions, evidence, unresolved questions, and not-verified items. Do not invent visual details, reading-level measurements, audience facts, legal claims, or cultural context. [EXPLICIT]

Procedure

Step 1: Discover

• Identify the content type: alt text, UI microcopy, docs, instructions, error copy, link text, localization, or inclusive language review.
• Capture audience, language/locale, channel, brand constraints, reading-level target, and publication risk.
• Inventory assets and source context: image, chart data, screenshot, original text, destination URL, product terminology, code/API names, legal or regulated copy.
• Mark missing inputs as not verified; for images or charts, do not infer details that are not visible or provided.

Step 2: Analyze

• Classify each content item by job-to-be-done: inform, instruct, warn, recover, compare, navigate, or describe.
• For images, choose the right treatment: decorative empty alt, informative alt, functional alt, complex description, caption, or adjacent long description.
• For copy, check plain language, scannability, reading burden, inclusive wording, sensory-only instructions, link purpose, error recovery, and localization fit.
• Separate reader-facing copy from validation evidence so the final text remains usable.

Step 3: Execute

• Produce accessible rewrites that preserve meaning, reduce jargon, define necessary acronyms, and keep one main idea per sentence or step.
• Write descriptive link text that makes sense out of context and distinguishes repeated links.
• Write error copy with the problem, likely cause when known, recovery action, and non-blaming tone.
• Replace sensory-only or positional instructions with names, labels, roles, headings, or stable identifiers.
• For inclusive language, propose contextual alternatives without silently changing code identifiers, product names, legal terms, or quoted source text.
• If writing to files, do so only when the user explicitly asks for an artifact or patch.

Step 4: Validate

• Confirm reader-facing copy is clear without internal evidence tags unless the user requested inline annotation.
• Provide a validation table with changed item, issue, rewrite, rationale, evidence/source, assumption, and residual risk.
• Label reading level as measured only if a tool or user-provided measurement was actually used; otherwise mark it as an estimate.
• Reject keyword stuffing, invented image details, unsupported accessibility claims, and edits that erase necessary precision.

Quality Criteria

• [ ] Audience, locale, channel, and content type are explicit or marked not verified.
• [ ] Alt text decisions distinguish decorative, informative, functional, complex, and missing-context assets.
• [ ] Plain-language rewrites preserve meaning while reducing unnecessary jargon, passive voice, dense sentences, and unexplained acronyms.
• [ ] Link text, headings, instructions, and errors are specific enough to be understood out of context.
• [ ] Inclusive language changes are contextual and do not silently rename code, APIs, product terms, or quoted text.
• [ ] Reading-level claims are measured or explicitly labeled as estimates.
• [ ] Reader-facing output is separated from evidence/validation notes.
• [ ] Every assumption, unverifiable detail, and requested-but-unsafe change is called out.

Anti-Patterns

• Inventing image, chart, demographic, or product details to make alt text sound complete
• Stuffing SEO keywords into alt text at the expense of usefulness
• Making a text simpler by deleting critical warnings, constraints, or decision criteria
• Replacing technical terms that are required for the task without defining or preserving them
• Using only color, shape, size, or position to explain an action
• Claiming an exact reading level without measurement
• Putting evidence tags inside final user-facing copy by default

Related Skills

• accessibility-testing — use for axe, keyboard, screen reader, contrast, and motion tests
• accessibility-audit — use for broader governance or WCAG audit evidence
• accessibility-design — use for component behavior, focus, ARIA, and visual interaction design
• copywriting or brand skills — use when persuasion or brand campaign copy is primary

Usage

Example invocations:

• "/accessibility-writing" — Run the full accessibility writing workflow
• "Write alt text for these product images"
• "Rewrite this onboarding page in plain language"
• "Make this error copy accessible"
• "Review this document for inclusive language and reading burden"

Assumptions & Limits

• Uses the language and locale of the input unless the user requests otherwise. [EXPLICIT]
• Assumes source text or asset context is available; missing image/chart data must be requested or marked not verified. [EXPLICIT]
• Does not certify legal, medical, financial, or regulatory wording; it can improve clarity and flag validation needs. [EXPLICIT]
• Does not replace accessibility-testing for runtime behavior, focus, screen reader, or contrast validation. [EXPLICIT]
• Does not mutate files unless the user explicitly asks for a patch or artifact. [EXPLICIT]

Edge Cases

| Scenario | Handling | |----------|----------| | Empty or minimal input | Request clarification before proceeding | | Conflicting requirements | Flag conflicts explicitly, propose resolution | | Out-of-scope request | Redirect to appropriate skill or escalate | | Image or chart missing | Ask for the asset/data or mark visual details not verified; do not hallucinate | | Decorative image | Recommend empty alt and explain where the visual meaning is carried | | Complex chart | Provide short alt plus long description structure using only supplied data | | SEO conflicts with alt usefulness | Prioritize user-useful description and document the conflict | | Reading level requested without measurement tool | Provide estimate and measurement recommendation, not a guaranteed score | | Inclusive language conflicts with code/API/legal names | Preserve required terms, suggest aliases or explanatory copy | | Sensory-only instruction | Rewrite using label, role, heading, or stable identifier |