a11y-audit · plugin87 — Claude Code skill: what it does, how to install
Audits UI and design against WCAG 2.2 and ARIA patterns. It checks contrast, keyboard navigation, and screen-reader readiness with concrete severity ratings.
npx skills add plugin87/ux-ui-agent-skills --skill a11y-audit -a claude-codeWhat a11y-audit does
The skill evaluates components against WCAG 2.2 (AA/AAA levels) and ARIA specifications. It runs checks using a POUR-organized checklist across P0, P1, and P2 priority levels. Target requirements include keyboard navigation, visible focus states with at least 3:1 contrast, screen-reader semantics, and target sizes of at least 24×24 pixels.
Contrast is never guessed. Instead, the workflow runs Node.js scripts measure_render.mjs and verify_states.mjs via gate.mjs on rendered HTML, or contrast.py for raw color values. It also verifies WCAG 2.2 additions like Focus Not Obscured (2.4.11), Target Size (2.5.8), Accessible Authentication (3.3.8), and reduced-motion rules. The output is a structured findings table with specific fixes.
Simply copying the skill directory triggers a KIT_MISSING failure. The tool depends on shared checklists and gate scripts, so you must initialize the repository files using npx ux-ui-agent-skills init.
What it helps with
- audit UI components against WCAG 2.2 AA and AAA criteria
- measure text and element contrast ratios using gate scripts
- verify keyboard navigation and visible focus indicators
- generate an accessibility findings table with P0, P1, and P2 fixes
Example prompts for the agent
- Run an a11y audit on
src/components/Modal.tsx - Check contrast ratios and hover states in
index.htmlwith--darkflag - Review the checkout flow for WCAG 2.2 and screen-reader compliance
How to install a11y-audit
1Skills CLI (Vercel)
npx skills add plugin87/ux-ui-agent-skills --skill a11y-audit -a claude-code2Manually: put the files in place
~/.claude/skills/a11y-audit/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/a11y-audit/
1Skills CLI (Vercel)
npx skills add plugin87/ux-ui-agent-skills --skill a11y-audit -a codex2Manually: put the files in place
.agents/skills/a11y-audit/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add plugin87/ux-ui-agent-skills --skill a11y-audit -a cursor2Manually: put the files in place
.cursor/skills/a11y-audit/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install plugin87/ux-ui-agent-skills a11y-audit2Manually: put the files in place
.github/skills/a11y-audit/SKILL.md1Skills CLI (Vercel)
npx skills add plugin87/ux-ui-agent-skills --skill a11y-audit -a gemini-cli2Platform CLI
gemini skills install https://github.com/plugin87/ux-ui-agent-skills --path .claude/skills/a11y-auditManually: put the files in place
.devin/skills/a11y-audit/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add plugin87/ux-ui-agent-skills --skill a11y-audit -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about a11y-audit
How do I install a11y-audit in Claude Code?
Run npx skills add plugin87/ux-ui-agent-skills --skill a11y-audit -a claude-code. Then run npx ux-ui-agent-skills init to set up the necessary checklist and script files.
What does the a11y-audit skill do?
It tests web UI components against WCAG 2.2 and ARIA guidelines, executing verification scripts for contrast and outputting prioritized fixes for each issue.
Why does the skill report a KIT_MISSING error?
This occurs when only the individual skill folder is installed without the supporting kit files. Run npx ux-ui-agent-skills init to install the required checklists and scripts.
Source text
SKILL.md · MIT
---
name: a11y-audit
description: Audit a UI or design against WCAG 2.2 AA/AAA and ARIA patterns, returning criterion-referenced findings with severity and specific fixes. Use when the user wants an accessibility check, contrast verification, keyboard/screen-reader review, or wants to confirm a component meets POUR.
---
# Skill: Accessibility Audit
> **Step 0: is the kit here?** This skill reads files from the kit. Check once:
> `ls ${CLAUDE_SKILL_DIR}/../../../tokens >/dev/null 2>&1 && echo KIT_OK || echo KIT_MISSING`
> On `KIT_MISSING` only the skill folders were installed, which is what
> `npx skills add` does. Say so plainly, point the user at
> `npx ux-ui-agent-skills init` or the plugin install, and stop. Do not guess the
> contents of a file you could not open.
Evaluate against WCAG 2.2 and the project's ARIA patterns.
## Steps
1. Read `${CLAUDE_SKILL_DIR}/../../../accessibility/wcag-checklist.md` (POUR-organized, P0/P1/P2) and `${CLAUDE_SKILL_DIR}/../../../accessibility/aria-patterns.md`.
2. Check the mandatory P0 set per component: keyboard navigable, focus visible (≥3:1), screen-reader name/role/state, contrast (4.5:1 text / 3:1 UI), target size ≥24×24, no color-only signaling.
3. Verify WCAG 2.2 additions: Focus Not Obscured (2.4.11), Target Size (2.5.8), Accessible Authentication (3.3.8).
4. **Contrast: measure, don't eyeball.** For rendered HTML, RUN the real-render gates and report their actual output (CLAUDE.md → Verification Protocol): `node ${CLAUDE_SKILL_DIR}/../../../scripts/gate.mjs measure_render.mjs <file> [--dark]` (every text element) AND `node ${CLAUDE_SKILL_DIR}/../../../scripts/gate.mjs verify_states.mjs <file> [--dark]` (every interactive element in default/hover/focus; catches hover-state failures). For loose color pairs, `python3 ${CLAUDE_SKILL_DIR}/../../../scripts/contrast.py "<fg>" "<bg>"`. Never state a ratio you did not measure.
5. Check reduced-motion handling (`${CLAUDE_SKILL_DIR}/../../../taste/motion-choreography.md`).
## Output
A findings table: WCAG criterion (e.g. 1.4.3) · severity (P0/P1/P2) · what fails · specific fix. Confirm passes explicitly. Accessibility may never be traded for aesthetics.
© plugin87 · MIT · plugin87/ux-ui-agent-skills
Similar skills
Everything for Frontend and UI →a11y-audit by other authors comes first.
