---
name: docs-a11y
description: Audit and improve the accessibility of the timepicker-ui documentation site (docs-app/) - landmarks, heading order, skip links, keyboard nav, focus management in the command menu / sidebar / dialogs, color contrast, alt text, ARIA on custom components, Radix usage, reduced motion - against WCAG 2.2 AA. Use when the user wants an a11y audit/fix of the docs site. Drives the docs-accessibility subagent in an audit → approve → apply flow. Does NOT cover the library (use /a11y for that).
---

# Docs Accessibility (a11y)

Make the `timepicker-ui` documentation site (`docs-app/`, Next.js 16) usable by keyboard and
assistive technology. This skill is a thin orchestrator: the real work is done by the
**`docs-accessibility`** subagent. The skill exists to hold the **approval gate** the subagent
can't run itself.

Standard: **WCAG 2.2 AA**. Scope is **`docs-app/` only** - the library is `/a11y`.

## Arguments (optional)
- A focus area narrows the run, e.g. `/docs-a11y nav`, `/docs-a11y command-menu`,
  `/docs-a11y contrast`, `/docs-a11y headings`, `/docs-a11y keyboard`. No argument = full audit.
- `--apply-all` skips the per-area approval prompt and applies the whole audited plan (still reports
  + verifies). Use only for an explicitly unattended run.

## Workflow

### Phase 1 — Audit (read-only)
Dispatch the `docs-accessibility` subagent (Task tool, `subagent_type: docs-accessibility`) in
**audit mode**, with the focus area if given. Ask for a prioritized, file-level plan grouped into:
1. Structure & landmarks (one `<main>`, nav/header/footer, skip link, heading order)
2. Keyboard & focus (command menu, mobile sidebar, dialogs: trap/Escape/focus-return, visible focus,
   `aria-expanded`/`aria-current`)
3. Names, roles, contrast (icon-button labels, decorative `aria-hidden`, ≥4.5:1 text contrast in
   light AND dark)
4. Content & media (`lang`, descriptive links, labelled copy buttons, alt text)
5. Motion & responsiveness (`prefers-reduced-motion`, reflow at 320px / 400% zoom)
Each finding cites its WCAG reference and the exact file + change. No edits.

### Phase 2 — Present & approve (gate)
Relay the plan concisely (grouped, with references). **Use AskUserQuestion** to approve all, pick
which groups/items to apply, or skip. Capture the approved set. Do not skip this gate unless
`--apply-all` was passed.

### Phase 3 — Apply
Dispatch `docs-accessibility` again in **apply mode** with the exact approved list. It implements
fixes (landmarks, headings, `aria-*`, focus management, labels, contrast/markup) in docs-app's own
TS/App-Router style and line endings, using Radix primitives correctly and adding no heavy deps.

### Phase 4 — Verify & report
- Offer to run `npm run build` / `npm run lint` (and an axe/Lighthouse a11y pass if tooling is
  available) inside `docs-app/`. Report real output; never assume green.
- Summarize what changed, grouped by the five areas, with the file list.
- Give the manual checklist: keyboard-only walkthrough (header → command menu → sidebar → a docs
  page), Escape/focus-return on the menus, a screen-reader pass on one page, and a contrast check in
  both light and dark themes.
- Flag anything that's actually a library a11y bug (seen via a live demo) for `/a11y`, and any
  visual/content redesign for `docs-site`.

## Guardrails
- `docs-app/` only; never edit the library in `app/` or `dist/`.
- Match docs-app conventions and line endings (not the library's CRLF rule).
- Accessibility, not redesign; no new heavy a11y dependencies without flagging.
- This skill audits/fixes; git and deploy stay with the user.