muse skills

Skill text to copy

---
name: accessibility-design-guard
description: "Run an accessibility pass over a web app and freeze what it fixed as automated design-guard tests: keyboard-operable controls with accessible names, focus that moves and stays visible, no zoom locks, sane tab order through interactive text, timed-task accommodations that never move the pass bar, and design-system rules (banned copy, token-only colours, terminology standards) enforced as tests that fail on drift. Use when auditing a web UI for accessibility, adding an accommodation, or turning a design document's written rules into CI enforcement."
---

# Accessibility & Design Guard

An accessibility fix that is not guarded regresses. Someone restyles the slider, the invisible focus trap is back, and nobody notices because nothing failed. A design rule that lives only in a document is a wish: the banned phrase returns in the next copy edit, the raw palette colour creeps back in the next component. This skill has two halves. First, an audit pass that finds and fixes the barriers. Second, a guard pass that encodes every enforceable rule the audit relied on as automated tests, so drift fails the build instead of reaching users.

It composes with `verify-before-shipping`: that skill decides whether a change may be called done. This one decides what an accessibility pass must cover, how each fix is proven, and which of the design system's rules deserve to become tests.

## When this applies

- Before shipping a web UI surface that has never had a deliberate accessibility pass, or after one is reported broken.
- When adding an accommodation (extended time, reduced motion, text scaling) to a timed or scored task.
- When a design document states rules (voice and copy standards, colour tokens, terminology) that the codebase keeps quietly violating.
- When a review finds an accessibility defect class, not just an instance: fix the class, then guard it.

A single known defect with an obvious fix does not need the full pass; fix it, add the one guard assertion it earns, and move on.

## The audit checklist, in running order

Work the list in this order; later items assume the earlier ones hold.

1. **Pointer-only interactions get a keyboard and switch equivalent.** Any hold-to-X, drag, or press-and-hold control must also have a keyboard and switch equivalent chosen for its control type: a discrete toggle for recording-style actions (press to start, press again to stop or send, `aria-pressed` reflecting state, pointer behaviour unchanged), and keyboard adjustment patterns for sliders and list reordering. A voice-record button that only works while a finger or mouse is held down excludes every keyboard and switch user from speaking at all.
2. **Every control has an accessible name.** Sweep for icon-only buttons, custom record buttons, bare textareas, and clickable divs. The canonical find of every real pass is a control with no accessible name whatsoever, often the primary action on its surface. Names come from the app's string system, never a hardcoded label in one language.
3. **Step and view changes move focus.** When a wizard, lesson player, or multi-part form swaps its content, focus goes to the new step's heading (a `tabIndex={-1}` heading and a ref, or the platform equivalent) so keyboard and screen-reader users land where the change happened instead of being stranded at the top of a replaced view or on a removed element.
4. **Focus is visible on every focusable element, including custom-styled ones.** The classic trap is a native input made invisible for styling (an `opacity-0` range slider under a custom track): keyboard focus arrives on an element nobody can see. Put the visible ring on the wrapper, driven by the child's focus state (`:focus-visible` / `:focus-within`), in the design system's ring token, and assert the ring colour meets at least 3:1 contrast against its background.
5. **No zoom locks.** The viewport meta carries no `maximum-scale` and no `user-scalable=no`. Pinch zoom is an accessibility feature, not a layout bug. Prove the removal with a repo-wide search, not by reading the one file you edited.
6. **Interactive long text gets a sane tab order.** A reading passage where every word is a lookup target must not become hundreds of tab stops. Use a roving tabindex (the passage is one tab stop; arrow keys plus Home/End move within it) and put a skip link before the passage so keyboard users can jump past it entirely. Non-interactive text stays non-interactive, and the pointer lookup behaviour is preserved exactly.
7. **Timed tasks offer a time accommodation that never moves the pass bar.** See the accommodations section below; the checklist-level rule is that the accommodation exists wherever a countdown gates a scored result, and that it changes time only.
8. **Status and recording indicators are labelled in the UI language system.** Recording states, timers, and progress announcements are real strings in the translation registry, labelled for assistive technology, and worded for the interaction as it actually works now (a toggle says "press again to send", a hold button says "hold"). A hardcoded status line in one language is a defect even when it is the product's own primary language.
9. **Focus is not obscured by fixed or sticky elements (WCAG 2.2 SC 2.4.11, Focus Not Obscured — Minimum; this skill's stricter rule follows SC 2.4.12, Focus Not Obscured — Enhanced).** The AA floor under SC 2.4.11 is that a focused component is not entirely hidden. This skill's stricter no-covering rule follows SC 2.4.12 and is project policy: when an element receives keyboard focus, no sticky header, fixed bottom action bar, floating audio or chat bar, or consent banner may cover any part of it. Give the scrollable content `scroll-margin-top` / `scroll-margin-bottom` at least equal to the fixed elements' heights, and prove it by tabbing through the surface, not by reading the CSS.
10. **Pointer targets meet the minimum size (WCAG 2.2 SC 2.5.8, T

skills/agent-workflow/accessibility-design-guard/SKILL.md from the repo, MIT licence. Read it before pasting. Muse asks before it acts.