| 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:
- Structure & landmarks (one
<main>, nav/header/footer, skip link, heading order)
- Keyboard & focus (command menu, mobile sidebar, dialogs: trap/Escape/focus-return, visible focus,
aria-expanded/aria-current)
- Names, roles, contrast (icon-button labels, decorative
aria-hidden, ≥4.5:1 text contrast in
light AND dark)
- Content & media (
lang, descriptive links, labelled copy buttons, alt text)
- 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.
