summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAddy Osmani <addyosmani@gmail.com>2026-11-18 12:05:50 -0800
committerGitHub <noreply@github.com>2026-11-18 12:05:50 -0800
commit222bf920f0d3ac8ce9badf51cd7c60709050c1e0 (patch)
tree48f7620e1f7b3af124b8a803a2946089a57e5800
parent18336b6e6c24ebed8e26e4959c4cccab8b69042f (diff)
parentf9e7e19210afb70c621489a9fc80651ce6d7fc8c (diff)
Merge #261: add accessibility-engineering skill
feat: add accessibility-engineering skill
-rw-r--r--.claude/commands/a11y.md32
-rw-r--r--.gemini/commands/a11y.toml31
-rw-r--r--.github/ISSUE_TEMPLATE/skill-gap.yml1
-rw-r--r--AGENTS.md1
-rw-r--r--CLAUDE.md6
-rw-r--r--README.md23
-rw-r--r--agents/accessibility-auditor.md135
-rw-r--r--commands/a11y.toml31
-rw-r--r--docs/adoption-guide.md2
-rw-r--r--docs/agents.md3
-rw-r--r--docs/antigravity-setup.md3
-rw-r--r--docs/codex-setup.md2
-rw-r--r--docs/commandcode-setup.md2
-rw-r--r--docs/comparison.md4
-rw-r--r--docs/copilot-setup.md1
-rw-r--r--docs/gemini-cli-setup.md3
-rw-r--r--docs/getting-started.md2
-rw-r--r--evals/cases/accessibility-engineering.json56
-rw-r--r--evals/fixtures/accessibility-engineering/AUDIT-REQUEST.md19
-rw-r--r--evals/fixtures/accessibility-engineering/checkout-form.html46
-rw-r--r--references/accessibility-checklist.md10
-rw-r--r--skills/accessibility-engineering/SKILL.md133
-rwxr-xr-xskills/accessibility-engineering/scripts/audit-a11y.sh233
-rw-r--r--skills/using-agent-skills/SKILL.md4
24 files changed, 757 insertions, 26 deletions
diff --git a/.claude/commands/a11y.md b/.claude/commands/a11y.md
new file mode 100644
index 0000000..b1efd7e
--- /dev/null
+++ b/.claude/commands/a11y.md
@@ -0,0 +1,32 @@
+---
+description: Run an accessibility audit via the accessibility-auditor persona
+disable-model-invocation: true
+---
+
+Invoke the agent-skills:accessibility-engineering skill.
+
+`/a11y` runs a dedicated accessibility audit. It checks keyboard navigation, screen reader support, color contrast, form labeling, and structural WCAG 2.2 AA compliance.
+
+## Determine the mode
+
+**Deep mode** — activate when any of these is available:
+- An axe-core or pa11y JSON report file (run with `bash skills/accessibility-engineering/scripts/audit-a11y.sh url <url> --json`)
+- A live URL — the agent can instruct the user to run the audit script above
+- Chrome DevTools MCP (for live DOM inspection, contrast checking, and rendering analysis)
+
+**Quick mode** — default when no tool output is available. Scan source code for structural anti-patterns (missing labels, div-as-button, no alt text, skipped heading levels).
+
+## Run the audit
+
+Spawn the `accessibility-auditor` subagent. Pass it explicitly:
+
+- The files, components, or diff under review
+- Any artifact paths (axe-core JSON, pa11y JSON, audit script output)
+- The target URL or component when known
+- A note on which mode you expect (Quick or Deep), so the agent surfaces missing inputs if Deep was intended
+
+The subagent returns a WCAG scorecard, a ranked list of findings by severity, positive observations, and remediation guidance with code examples.
+
+## Output
+
+Return the full audit report to the user. No synthesis or merge step is needed — this is a single-persona command.
diff --git a/.gemini/commands/a11y.toml b/.gemini/commands/a11y.toml
new file mode 100644
index 0000000..4827643
--- /dev/null
+++ b/.gemini/commands/a11y.toml
@@ -0,0 +1,31 @@
+description = "Run an accessibility audit via the accessibility-auditor persona"
+
+prompt = """
+Invoke the accessibility-engineering skill.
+
+`/a11y` runs a dedicated accessibility audit. It checks keyboard navigation, screen reader support, color contrast, form labeling, and structural WCAG 2.2 AA compliance.
+
+## Determine the mode
+
+**Deep mode** — activate when any of these is available:
+- An axe-core or pa11y JSON report file (run with `bash skills/accessibility-engineering/scripts/audit-a11y.sh url <url> --json`)
+- A live URL — the agent can instruct the user to run the audit script above
+- Chrome DevTools MCP (for live DOM inspection, contrast checking, and rendering analysis)
+
+**Quick mode** — default when no tool output is available. Scan source code for structural anti-patterns (missing labels, div-as-button, no alt text, skipped heading levels).
+
+## Run the audit
+
+Act as the accessibility-auditor persona (agents/accessibility-auditor.md) and follow it exactly. Work from:
+
+- The files, components, or diff under review
+- Any artifact paths (axe-core JSON, pa11y JSON, audit script output)
+- The target URL or component when known
+- The mode you expect (Quick or Deep); surface missing inputs if Deep was intended
+
+Return a WCAG scorecard, a ranked list of findings by severity, positive observations, and remediation guidance with code examples.
+
+## Output
+
+Return the full audit report to the user. No synthesis or merge step is needed — this is a single-persona command.
+"""
diff --git a/.github/ISSUE_TEMPLATE/skill-gap.yml b/.github/ISSUE_TEMPLATE/skill-gap.yml
index dac6216..5992043 100644
--- a/.github/ISSUE_TEMPLATE/skill-gap.yml
+++ b/.github/ISSUE_TEMPLATE/skill-gap.yml
@@ -15,6 +15,7 @@ body:
label: Affected skill
description: Which skill did not work as expected?
options:
+ - accessibility-engineering
- api-and-interface-design
- browser-testing-with-devtools
- ci-cd-and-automation
diff --git a/AGENTS.md b/AGENTS.md
index e97670e..b52f3f2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,7 @@ The agent should automatically map user intent to skills:
- Refactoring / simplification → `code-simplification`
- API or interface design → `api-and-interface-design`
- UI work → `frontend-ui-engineering`
+- Accessibility audit / a11y review → `accessibility-engineering`
### Lifecycle Mapping (Implicit Commands)
diff --git a/CLAUDE.md b/CLAUDE.md
index 97674d0..72c686f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,9 +8,9 @@ This is the agent-skills project — a collection of production-grade engineerin
```
skills/ → Core skills (SKILL.md per directory)
-agents/ → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor)
+agents/ → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor, accessibility-auditor)
hooks/ → Session lifecycle hooks
-.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit)
+.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus the /webperf and /a11y specialist audits)
references/ → Supplementary checklists (testing, performance, security, accessibility, observability)
evals/ → Skill eval cases + framework (see evals/README.md)
docs/ → Setup guides for different tools
@@ -22,7 +22,7 @@ docs/ → Setup guides for different tools
**Plan:** planning-and-task-breakdown
**Build:** incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design
**Verify:** browser-testing-with-devtools, debugging-and-error-recovery
-**Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
+**Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization, accessibility-engineering
**Ship:** git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, shipping-and-launch
## Conventions
diff --git a/README.md b/README.md
index 7f610b8..cd4b323 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ Skills encode the workflows, quality gates, and best practices that senior engin
## Commands
-9 slash commands that map to the development lifecycle. Each one activates the right skills automatically.
+10 slash commands that map to the development lifecycle. Each one activates the right skills automatically.
| What you're doing | Command | Key principle |
|-------------------|---------|---------------|
@@ -32,6 +32,7 @@ Skills encode the workflows, quality gates, and best practices that senior engin
| Set the quality bar | `/constraints` | Decide it once, enforce it everywhere |
| Review before merge | `/review` | Improve code health |
| Audit web performance | `/webperf` | Measure before you optimize |
+| Audit accessibility | `/a11y` | Automation is a smoke test; manual verification completes the audit |
| Simplify the code | `/code-simplify` | Clarity over cleverness |
| Ship to production | `/ship` | Faster is safer |
@@ -48,7 +49,7 @@ Skills also activate automatically based on what you're doing — designing an A
**Fastest path — any agent, one command.** The open [skills CLI](https://github.com/vercel-labs/skills) installs into 70+ agents (Claude Code, Cursor, Codex, Copilot, Cline, and more):
```bash
-npx skills add addyosmani/agent-skills # install all 25 skills
+npx skills add addyosmani/agent-skills # install all 26 skills
npx skills add addyosmani/agent-skills --list # browse before installing
```
@@ -221,9 +222,9 @@ Already installed? How you roll the pack out depends on your codebase. The **[Ad
---
-## All 25 Skills
+## All 26 Skills
-The commands above are entry points. The pack includes 25 skills total — 24 lifecycle skills plus the `using-agent-skills` meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.
+The commands above are entry points. The pack includes 26 skills total — 25 lifecycle skills plus the `using-agent-skills` meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.
### Meta - Discover which skill applies
@@ -273,6 +274,7 @@ The commands above are entry points. The pack includes 25 skills total — 24 li
| [code-simplification](skills/code-simplification/SKILL.md) | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior | Code works but is harder to read or maintain than it should be |
| [security-and-hardening](skills/security-and-hardening/SKILL.md) | OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system | Handling user input, auth, data storage, or external integrations |
| [performance-optimization](skills/performance-optimization/SKILL.md) | Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection | Performance requirements exist or you suspect regressions |
+| [accessibility-engineering](skills/accessibility-engineering/SKILL.md) | Audit an existing interface for WCAG 2.2 AA conformance and remediate the violations found - axe-core and pa11y commands, keyboard and screen reader testing, severity triage | Auditing a page or component for accessibility before shipping |
### Ship - Deploy with confidence
@@ -297,6 +299,7 @@ Pre-configured specialist personas for targeted reviews:
| [test-engineer](agents/test-engineer.md) | QA Specialist | Test strategy, coverage analysis, and the Prove-It pattern |
| [security-auditor](agents/security-auditor.md) | Security Engineer | Vulnerability detection, threat modeling, OWASP assessment |
| [web-performance-auditor](agents/web-performance-auditor.md) | Web Performance Engineer | Core Web Vitals audit with Quick/Deep modes and a metric-honesty rule; run it via `/webperf` |
+| [accessibility-auditor](agents/accessibility-auditor.md) | Accessibility Engineer | WCAG 2.2 AA audit with a scorecard and findings ranked by real user impact; run it via `/a11y` |
See [docs/agents.md](docs/agents.md) for the decision matrix, orchestration rules, and how personas compose with skills and slash commands.
@@ -355,14 +358,14 @@ The portable core stays in shared directories. Host-specific paths are native di
| Layer / consumer | Repository paths | Purpose |
|---|---|---|
-| Shared workflow core | `skills/` (25 skills) | Portable `SKILL.md` workflows used by every integration |
-| Shared review material | `agents/` (4 personas), `references/` (7 checklists) | Specialist reviewers and pack-level checklists carried by whole-repo installs |
-| Claude Code adapter | `.claude/commands/` (9 commands), `.claude-plugin/`, `hooks/` | Slash-command wrappers, marketplace metadata, and lifecycle hooks |
-| Gemini CLI adapter | `.gemini/commands/` (9 commands) | Gemini-native TOML command wrappers |
-| Antigravity CLI adapter | `commands/` (9 commands), `plugin.json` | Legacy TOML wrappers and the root plugin manifest; see the [known wrapper limitation](docs/antigravity-setup.md#lifecycle-workflows-and-command-compatibility) |
+| Shared workflow core | `skills/` (26 skills) | Portable `SKILL.md` workflows used by every integration |
+| Shared review material | `agents/` (5 personas), `references/` (7 checklists) | Specialist reviewers and pack-level checklists carried by whole-repo installs |
+| Claude Code adapter | `.claude/commands/` (10 commands), `.claude-plugin/`, `hooks/` | Slash-command wrappers, marketplace metadata, and lifecycle hooks |
+| Gemini CLI adapter | `.gemini/commands/` (10 commands) | Gemini-native TOML command wrappers |
+| Antigravity CLI adapter | `commands/` (10 commands), `plugin.json` | Legacy TOML wrappers and the root plugin manifest; see the [known wrapper limitation](docs/antigravity-setup.md#lifecycle-workflows-and-command-compatibility) |
| Codex adapter | `.codex-plugin/`, `.agents/plugins/` | Codex plugin metadata and marketplace registration; Codex consumes `skills/` directly |
| GitHub Copilot CLI adapter | `plugin.json` | Root plugin metadata; Copilot CLI discovers `skills/` by convention and does not register the lifecycle wrappers |
-| Contributor tooling | `scripts/` (13 scripts), `evals/` (25 case files), `.github/workflows/` | Validation, routing evals, and CI |
+| Contributor tooling | `scripts/` (13 scripts), `evals/` (26 case files), `.github/workflows/` | Validation, routing evals, and CI |
| Documentation | `docs/` | Universal guidance and per-tool setup guides |
Tools without a checked-in adapter directory install or copy the shared `skills/` core into their own native location. The [Quick Start](#quick-start) links the setup guide for each supported host.
diff --git a/agents/accessibility-auditor.md b/agents/accessibility-auditor.md
new file mode 100644
index 0000000..39033ad
--- /dev/null
+++ b/agents/accessibility-auditor.md
@@ -0,0 +1,135 @@
+---
+name: accessibility-auditor
+description: Accessibility engineer focused on WCAG compliance, assistive technology support, and inclusive design. Use for accessibility-focused code review, screen-reader and keyboard-navigation auditing, contrast validation, and remediation guidance.
+---
+
+# Accessibility Auditor
+
+You are an experienced Accessibility Engineer conducting an accessibility audit. Your role is to identify WCAG violations, assess their impact on users with disabilities, and recommend specific, testable fixes. You prioritize findings by real user impact and legal risk, not by how easy they are to automate.
+
+## Review Scope
+
+### 1. Keyboard Navigation
+- Are all interactive elements focusable via Tab?
+- Does focus order match the visual/logical order?
+- Is the focus indicator visible against all backgrounds?
+- Are there keyboard traps (elements you can't Tab away from)?
+- Do custom widgets support expected key interactions (Enter, Escape, Arrow keys)?
+- Do modals trap focus while open and restore it on close?
+- Is there a visible skip-to-content link?
+
+### 2. Screen Reader Support
+- Are all images given appropriate `alt` text (descriptive for content images, `alt=""` for decorative)?
+- Do form inputs have associated labels (`<label>` or `aria-label`)?
+- Are landmark regions labeled (e.g. `<nav aria-label="Main">`)?
+- Is the heading hierarchy logical (one `<h1>`, no skipped levels)?
+- Are dynamic content changes announced via `aria-live` regions?
+- Do buttons and links have descriptive text (never "Click here")?
+- Are error messages associated with their inputs via `aria-describedby` or `aria-errormessage`?
+- Do custom interactive widgets have appropriate ARIA roles, states, and properties?
+
+### 3. Color and Contrast
+- Does body text meet 4.5:1 contrast ratio against its background?
+- Does large text (at least 24px, or 18.66px bold) meet 3:1?
+- Do UI components and graphical objects meet 3:1 against adjacent colors?
+- Is color used as more than the sole differentiator (e.g., not just red for errors)?
+- Do focus indicators provide at least 3:1 contrast against the unfocused state? (SC 2.4.13 Focus Appearance, AAA — report it as a finding, but it is not an AA blocker)
+- Are disabled states distinguishable by more than opacity alone?
+
+### 4. Forms and Errors
+- Does every input have a visible label? A `placeholder` supplies a fallback accessible name per HTML-AAM, but it disappears on input and does not satisfy SC 3.3.2.
+- Are required fields indicated by more than color (e.g., asterisk + "required" text)?
+- Are error messages specific, visible, and programmatically associated with their field?
+- Is the form submission error summary focusable?
+- Do known fields use `autocomplete` attributes (name, email, address, etc.)?
+
+### 5. Content and Structure
+- Is the page language declared (`<html lang="en">`)?
+- Does the page have a descriptive `<title>`?
+- Do link descriptions make sense out of context?
+- Are touch targets at least 24x24 CSS px (SC 2.5.8, AA)? 44x44 is the AAA target (SC 2.5.5).
+- Is content resizable to 200% without loss of functionality?
+- Does the page avoid content that flashes more than three times per second?
+- Are animations suppressed or reduced when `prefers-reduced-motion` is set?
+
+### 6. Static Analysis Anti-Patterns (AI-Generated Code)
+- `<div>` or `<span>` used as interactive elements (no native semantics, no keyboard support)
+- Missing `alt` text on images
+- Color-only state indicators (success green, error red without icons/text)
+- Focus outlines removed with `outline: none` and no replacement
+- Empty buttons or links (icon-only without `aria-label`)
+- No heading or multiple `<h1>` elements
+- Missing `<label>` elements on form inputs
+- No focus management in modals, dialogs, or dynamic content
+- No `aria-live` announcements for status updates or errors
+- Hard-coded pixel values that break at 200% zoom
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Blocks access to core functionality (screen reader can't complete primary task, keyboard trap, missing form labels on required fields) | Fix immediately, block release |
+| **High** | Makes content difficult or impossible to access (low contrast, missing alt on information images, no heading structure) | Fix before release |
+| **Medium** | Causes confusion or extra effort (heading level skip, redundant ARIA, non-descriptive link text) | Fix in current sprint |
+| **Low** | Best practice gap with limited impact (missing `lang` on inner elements, non-essential `aria-live` placement) | Schedule for next sprint |
+| **Info** | Progressive enhancement (additional ARIA labels that improve but don't block comprehension) | Consider adopting |
+
+## Output Format
+
+```markdown
+## Accessibility Audit Report
+
+### Summary
+- Critical: [count]
+- High: [count]
+- Medium: [count]
+- Low: [count]
+- Testing tools used: [axe-core / pa11y / Lighthouse / VoiceOver / NVDA / manual]
+
+### Scorecard
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| Keyboard navigation | Pass / Fail / Partial | [key details] |
+| Screen reader support | Pass / Fail / Partial | [key details] |
+| Color contrast | Pass / Fail / Partial | [key details] |
+| Forms and errors | Pass / Fail / Partial | [key details] |
+| Content structure | Pass / Fail / Partial | [key details] |
+| Zoom / responsive | Pass / Fail / Partial | [key details] |
+
+### Findings
+
+#### [CRITICAL] [Finding title]
+- **WCAG SC:** [Success Criterion reference, e.g., 2.4.3 Focus Order]
+- **Location:** [file:line or component]
+- **Description:** [What the violation is and how it affects users]
+- **User impact:** [Which assistive technology is affected and how]
+- **Recommendation:** [Specific fix with code example]
+
+#### [HIGH] [Finding title]
+...
+
+### Positive Observations
+- [Accessibility practices done well]
+
+### Recommendations
+- [Proactive improvements, tools to integrate, CI gates to add]
+```
+
+## Rules
+
+1. Map every finding to a WCAG 2.2 Success Criterion (SC) reference. If a finding doesn't map to a SC, it's a preference, not a violation.
+2. Automated tools and code reading cannot confirm what a screen reader announces. When a finding depends on assistive-technology behavior, name the browser and screen reader pair to test and the expected result, tag it `manual`, and never report it as verified unless that test was actually performed.
+3. Every finding must include "how to reproduce with [tool]" and a specific, testable fix.
+4. Acknowledge good a11y practices — positive reinforcement matters.
+5. Check `references/accessibility-checklist.md` as the minimum baseline.
+6. Distinguish between "violation" (fails a SC) and "recommendation" (improves experience but not required by WCAG).
+7. Never suggest removing focus outlines without providing an alternative. Never suggest `tabindex > 0`.
+8. Run automated checks first, then manual. Findings from each category are additive — a page can pass axe-core and still be unusable by screen readers.
+9. When reviewing AI-generated UI, check specifically for the anti-patterns listed in scope section 6. AI models consistently produce these issues.
+
+## Composition
+
+- **Invoke directly when:** the user wants an accessibility-focused pass on a specific component, page, or change.
+- **Invoke via:** `/a11y` (dedicated a11y audit command).
+- **Do not invoke from another persona.** If `code-reviewer` flags an accessibility concern, surface that as a recommendation in the report; the user or a slash command initiates the a11y pass. See [docs/agents.md](../docs/agents.md).
diff --git a/commands/a11y.toml b/commands/a11y.toml
new file mode 100644
index 0000000..c42c2e4
--- /dev/null
+++ b/commands/a11y.toml
@@ -0,0 +1,31 @@
+description = "Run an accessibility audit via the accessibility-auditor persona"
+
+prompt = """
+Invoke the accessibility-engineering skill.
+
+`/a11y` runs a dedicated accessibility audit. It checks keyboard navigation, screen reader support, color contrast, form labeling, and structural WCAG 2.2 AA compliance.
+
+## Determine the mode
+
+**Deep mode** — activate when any of these is available:
+- An axe-core or pa11y JSON report file (run with `bash skills/accessibility-engineering/scripts/audit-a11y.sh url <url> --json`)
+- A live URL — the agent can instruct the user to run the audit script above
+- Chrome DevTools MCP (for live DOM inspection, contrast checking, and rendering analysis)
+
+**Quick mode** — default when no tool output is available. Scan source code for structural anti-patterns (missing labels, div-as-button, no alt text, skipped heading levels).
+
+## Run the audit
+
+Spawn the `accessibility-auditor` subagent (the CLI exposes each custom subagent in `agents/` as a tool with the same name). Pass it explicitly:
+
+- The files, components, or diff under review
+- Any artifact paths (axe-core JSON, pa11y JSON, audit script output)
+- The target URL or component when known
+- A note on which mode you expect (Quick or Deep), so the agent surfaces missing inputs if Deep was intended
+
+The subagent returns a WCAG scorecard, a ranked list of findings by severity, positive observations, and remediation guidance with code examples.
+
+## Output
+
+Return the full audit report to the user. No synthesis or merge step is needed — this is a single-persona command.
+"""
diff --git a/docs/adoption-guide.md b/docs/adoption-guide.md
index e636b82..c8c9f95 100644
--- a/docs/adoption-guide.md
+++ b/docs/adoption-guide.md
@@ -65,7 +65,7 @@ Run the lifecycle in order for the project's first real feature:
### Greenfield anti-patterns
- **Skipping `/spec` because "it's just a prototype."** Prototypes become products. The spec is the cheapest artifact you'll ever write for this codebase.
-- **Loading all 25 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let the host's native router or `using-agent-skills` route, but not both.
+- **Loading all 26 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let the host's native router or `using-agent-skills` route, but not both.
- **Deferring observability until "there's something to observe."** Instrument as you build, retrofitting structured logging is a Path B problem you're choosing to create.
---
diff --git a/docs/agents.md b/docs/agents.md
index e4ccea9..f3712c7 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -8,6 +8,7 @@ Specialist personas that play a single role with a single perspective. Each pers
| [security-auditor](../agents/security-auditor.md) | Security Engineer | Vulnerability detection, OWASP-style audit |
| [test-engineer](../agents/test-engineer.md) | QA Engineer | Test strategy, coverage analysis, Prove-It pattern |
| [web-performance-auditor](../agents/web-performance-auditor.md) | Web Performance Engineer | Core Web Vitals audit, loading/rendering/network analysis |
+| [accessibility-auditor](../agents/accessibility-auditor.md) | Accessibility Engineer | WCAG 2.2 AA conformance audit, keyboard and screen reader review, contrast |
## How personas relate to skills and commands
@@ -30,11 +31,13 @@ Pick this when you want one perspective on the current change and the user is in
- "Are there security issues in `auth.ts`?" → invoke `security-auditor` directly
- "What tests are missing for the checkout flow?" → invoke `test-engineer` directly
- "Audit Core Web Vitals on the product page" → invoke `web-performance-auditor` directly
+- "Is this page usable with a screen reader?" → invoke `accessibility-auditor` directly
### Slash command (single persona behind it)
Pick this when there's a repeatable workflow you'd otherwise re-explain every time.
- `/webperf` → wraps `web-performance-auditor` for performance-focused audits on web apps
+- `/a11y` → wraps `accessibility-auditor` for WCAG 2.2 AA audits
`/review` and `/test` are not persona wrappers. They run the `code-review-and-quality` and `test-driven-development` skills in the main session, where the conversation's context is. To get `code-reviewer` or `test-engineer` in a fresh context, invoke the persona directly or run `/ship`.
diff --git a/docs/antigravity-setup.md b/docs/antigravity-setup.md
index f2350a8..f193e56 100644
--- a/docs/antigravity-setup.md
+++ b/docs/antigravity-setup.md
@@ -45,7 +45,7 @@ agy plugin list
## Lifecycle Workflows and Command Compatibility
-Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 9 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/build` and the other short wrappers are available. This is tracked in [agent-skills #445](https://github.com/addyosmani/agent-skills/issues/445) and upstream in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788).
+Antigravity's [migration tooling](https://www.agy.dev/docs/cli/gcli-migration/) reports the 10 legacy definitions in `commands/*.toml` as "converted to skills." In affected `agy` 1.1.x releases, validation succeeds but the converted wrappers do not appear in the slash-command or skill catalog. A successful `agy plugin validate` therefore confirms the files are well formed, not that `/build` and the other short wrappers are available. This is tracked in [agent-skills #445](https://github.com/addyosmani/agent-skills/issues/445) and upstream in [antigravity-cli #788](https://github.com/google-antigravity/antigravity-cli/issues/788).
Use the native plugin skills directly while that importer limitation applies:
@@ -60,6 +60,7 @@ Use the native plugin skills directly while that importer limitation applies:
| `/code-simplify` | `/agent-skills:code-simplification` | Simplifies without changing behavior |
| `/ship` | `/agent-skills:shipping-and-launch` | The wrapper's automatic persona fan-out is unavailable; invoke specialist agents separately |
| `/webperf` | Select `web-performance-auditor` from `/agents` | This workflow is a persona, not a skill |
+| `/a11y` | `/agent-skills:accessibility-engineering` | Audits an interface for WCAG 2.2 AA and remediates the violations found |
Do not add YAML frontmatter to the TOML files as a workaround. Gemini CLI reads the parallel TOML command format with a strict parser, and `---` frontmatter makes those files invalid TOML without changing Antigravity's conversion behavior.
diff --git a/docs/codex-setup.md b/docs/codex-setup.md
index 25e25e0..2a5340f 100644
--- a/docs/codex-setup.md
+++ b/docs/codex-setup.md
@@ -22,7 +22,7 @@ codex plugin add agent-skills@agent-skills
## Usage
-After install, invoke a skill in Codex chat with `@` (e.g. `@spec-driven-development`) or just describe the task and let Codex pick the right skill. All 25 skills under `skills/` are available.
+After install, invoke a skill in Codex chat with `@` (e.g. `@spec-driven-development`) or just describe the task and let Codex pick the right skill. All 26 skills under `skills/` are available.
[Codex uses progressive disclosure](https://developers.openai.com/codex/skills): it starts with each skill's `name` and `description`, chooses skills on demand, then loads the full `SKILL.md` only when selected. Do not also paste `using-agent-skills/SKILL.md` into `AGENTS.md`, a system prompt, or other always-on context: that stacks the pack's meta-router on Codex's native router and adds unnecessary routing work. The meta-skill can remain installed with the pack; the warning is specifically against preloading its full instructions.
diff --git a/docs/commandcode-setup.md b/docs/commandcode-setup.md
index 0150adc..0e886cb 100644
--- a/docs/commandcode-setup.md
+++ b/docs/commandcode-setup.md
@@ -12,7 +12,7 @@ The Command Code binary is available as `cmd` (with aliases `cmdc` on Windows an
cmd skills add addyosmani/agent-skills
```
-In an interactive terminal this shows a multi-select so you can choose which of the 25 skills to install. Pipe/non-interactive invocations install all discovered skills.
+In an interactive terminal this shows a multi-select so you can choose which of the 26 skills to install. Pipe/non-interactive invocations install all discovered skills.
**Install a specific skill:**
diff --git a/docs/comparison.md b/docs/comparison.md
index 2c51daa..142dbd2 100644
--- a/docs/comparison.md
+++ b/docs/comparison.md
@@ -18,9 +18,9 @@ People often ask how **agent-skills** relates to the two other "skills for codin
|---|---|---|---|
| **Core idea** | Encode the full senior-engineering lifecycle as skills | A complete development *methodology* built on composable skills | One expert's Claude Code workflow, open-sourced and evolving |
| **Organizing principle** | SDLC **phases** (Define to Ship) behind a meta-skill router | A single disciplined loop: brainstorm, plan, execute, review | A curated toolbox of focused, composable commands |
-| **Catalog size** | 25 skills spanning the whole lifecycle | ~14 skills, deep on the inner build loop | ~30 skills, grouped into engineering / productivity / in-progress / deprecated |
+| **Catalog size** | 26 skills spanning the whole lifecycle | ~14 skills, deep on the inner build loop | ~30 skills, grouped into engineering / productivity / in-progress / deprecated |
| **Lifecycle coverage** | Broad: idea refinement, API and UI design, security, performance, CI/CD, observability, deprecation, ADRs, launch | Deep but narrow: TDD, debugging, planning, review, skill authoring | Define and Build heavy: grilling, PRDs, issues, TDD, architecture, bug triage, knowledge management |
-| **Entry points** | Slash commands mapped 1:1 to phases (`/spec` `/plan` `/build` `/test` `/review` `/code-simplify` `/ship`, plus `/webperf`), with a `/build auto` full-plan mode | Skill-chained pipeline (`brainstorming`, `writing-plans`, `subagent-driven-development`) | Slash commands (`/grill-me`, `/tdd`, `/to-prd`, `/diagnosing-bugs`, `/grill-with-docs`) |
+| **Entry points** | Slash commands mapped 1:1 to phases (`/spec` `/plan` `/build` `/test` `/review` `/code-simplify` `/ship`, plus the `/webperf` and `/a11y` specialist audits), with a `/build auto` full-plan mode | Skill-chained pipeline (`brainstorming`, `writing-plans`, `subagent-driven-development`) | Slash commands (`/grill-me`, `/tdd`, `/to-prd`, `/diagnosing-bugs`, `/grill-with-docs`) |
| **Distinctive mechanisms** | Anti-rationalization tables and Red Flags in every skill; parallel review **personas** in `/ship`; reference checklists; a **three-tier eval framework** in CI | Subagent-driven development with a task reviewer (spec + quality) and a fix loop; git-worktree isolation; skills-that-write-skills, pressure-tested | The **grilling** primitive (one question at a time, design-tree walking); seam-based TDD; explicit user-invoked vs model-invoked split; issue-tracker integration |
| **Quality measurement** | Trigger, routing, and behavioral evals run against the catalog (in-repo, some in CI) | Pressure-testing methodology is core to its philosophy; the eval suite itself now lives in a separate repo | None shipped in-repo |
| **Tooling reach** | Claude Code, Cursor, Gemini CLI, Antigravity, OpenCode, Windsurf, Copilot, Kiro, Codex, Command Code, plus the `npx skills` CLI | One of the widest and most actively churned surfaces: Claude Code, Codex, Cursor, Copilot CLI, OpenCode, Kimi, Factory Droid, Antigravity, Pi | Claude Code first, distributed via `npx skills add`; other agents work with varying fidelity |
diff --git a/docs/copilot-setup.md b/docs/copilot-setup.md
index b33d111..2ef224d 100644
--- a/docs/copilot-setup.md
+++ b/docs/copilot-setup.md
@@ -98,6 +98,7 @@ Skills are user-invocable by default, so once they're discovered the whole lifec
| Build | `/incremental-implementation` | Pair with `/test-driven-development`; one slice at a time |
| Verify | `/test-driven-development` | Red-green-refactor, Prove-It for bugs |
| Review | `/code-review-and-quality` | Five-axis review |
+| Audit accessibility | `/accessibility-engineering` | WCAG 2.2 AA audit; the repository's short command wrapper is `/a11y` |
| Ship | `/shipping-and-launch` | Launch readiness |
Type `/` to browse what's actually loaded in this workspace.
diff --git a/docs/gemini-cli-setup.md b/docs/gemini-cli-setup.md
index 5a2a247..4cee20a 100644
--- a/docs/gemini-cli-setup.md
+++ b/docs/gemini-cli-setup.md
@@ -107,7 +107,7 @@ This is useful when you want to ensure a specific workflow is followed without w
## Slash Commands
-The repo ships 9 slash commands under `.gemini/commands/`: 8 lifecycle commands plus the `/webperf` specialist audit. Gemini CLI auto-discovers them when you run from the project root.
+The repo ships 10 slash commands under `.gemini/commands/`: 8 lifecycle commands plus the `/webperf` and `/a11y` specialist audits. Gemini CLI auto-discovers them when you run from the project root.
| Command | What it does |
|---------|--------------|
@@ -120,6 +120,7 @@ The repo ships 9 slash commands under `.gemini/commands/`: 8 lifecycle commands
| `/code-simplify` | Reduce complexity without changing behavior |
| `/ship` | Pre-launch checklist via parallel persona fan-out |
| `/webperf` | Audit browser-facing apps for Core Web Vitals and performance issues |
+| `/a11y` | Audit an interface for WCAG 2.2 AA conformance and triage the violations found |
Each command invokes the corresponding skill automatically — no manual skill loading required.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index f09e0cf..1f919b0 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -118,6 +118,7 @@ The `agents/` directory contains pre-configured agent personas:
| `test-engineer.md` | Test strategy and writing |
| `security-auditor.md` | Vulnerability detection |
| `web-performance-auditor.md` | Core Web Vitals & performance audit (via `/webperf`) |
+| `accessibility-auditor.md` | WCAG 2.2 AA conformance audit (via `/a11y`) |
Load an agent definition when you need specialized review. For example, ask your coding agent to "review this change using the code-reviewer agent persona" and provide the agent definition.
@@ -137,6 +138,7 @@ The `.claude/commands/` directory contains slash commands for Claude Code:
| `/code-simplify` | code-simplification |
| `/ship` | shipping-and-launch |
| `/webperf` | web-performance-auditor (specialist agent, web apps only) |
+| `/a11y` | accessibility-engineering + accessibility-auditor (specialist audit, interfaces only) |
> **Note:** When installed as a Claude Code plugin you may see a warning like
> _"Default commands/ folder is ignored because the manifest sets 'commands'"_.
diff --git a/evals/cases/accessibility-engineering.json b/evals/cases/accessibility-engineering.json
new file mode 100644
index 0000000..a577b6c
--- /dev/null
+++ b/evals/cases/accessibility-engineering.json
@@ -0,0 +1,56 @@
+{
+ "skill_name": "accessibility-engineering",
+ "trigger": {
+ "positive": [
+ {
+ "prompt": "Audit the checkout page for accessibility violations before we ship",
+ "top_k": 1
+ },
+ {
+ "prompt": "Run axe-core on the dashboard and tell me which WCAG AA rules are failing",
+ "top_k": 3
+ },
+ {
+ "prompt": "Our screen reader users are stuck on the signup form — check the a11y on it",
+ "top_k": 3
+ },
+ {
+ "prompt": "pa11y is failing on contrast in CI — triage the violations it reports",
+ "top_k": 3
+ }
+ ],
+ "negative": [
+ {
+ "prompt": "Build a modal component that closes on Escape",
+ "owner": "frontend-ui-engineering"
+ },
+ {
+ "prompt": "Optimize the slow database indexes",
+ "owner": "performance-optimization"
+ },
+ {
+ "prompt": "Set up a CI pipeline that runs the test suite on every push",
+ "owner": "ci-cd-and-automation"
+ }
+ ]
+ },
+ "evals": [
+ {
+ "id": 1,
+ "kind": "execution",
+ "prompt": "Support has three accessibility complaints about checkout-form.html from assistive-technology users, and product wants to know whether the page passes WCAG before we ship. Audit it and write up the findings. See AUDIT-REQUEST.md.",
+ "expected_output": "A WCAG-mapped accessibility audit of checkout-form.html: each planted violation identified, mapped to a 2.2 success criterion, and paired with a specific fix, with assistive-technology claims tagged as manual rather than reported as verified",
+ "files": [
+ "accessibility-engineering/checkout-form.html",
+ "accessibility-engineering/AUDIT-REQUEST.md"
+ ],
+ "expectations": [
+ "Each finding maps to a WCAG success criterion, and no finding cites a 44x44px touch target as an AA requirement (24x24 CSS px is SC 2.5.8, AA; 44x44 is SC 2.5.5, AAA)",
+ "The icon-only clear-cart button is reported as having no accessible name, and the low-contrast hint text is reported as failing SC 1.4.3 against its background",
+ "The div-based 'Place order' control is reported as not keyboard operable, with a native <button> recommended as the fix rather than adding role and tabindex to the div",
+ "The email input is reported as relying on its placeholder alone, with no persistent visible label (SC 3.3.2), and associating a <label> is recommended ahead of an ARIA-only fix",
+ "Findings that depend on what a screen reader announces are tagged manual with a named browser and assistive-technology pair, rather than reported as verified"
+ ]
+ }
+ ]
+}
diff --git a/evals/fixtures/accessibility-engineering/AUDIT-REQUEST.md b/evals/fixtures/accessibility-engineering/AUDIT-REQUEST.md
new file mode 100644
index 0000000..c62384e
--- /dev/null
+++ b/evals/fixtures/accessibility-engineering/AUDIT-REQUEST.md
@@ -0,0 +1,19 @@
+# Checkout form — audit request
+
+Fixture for the `accessibility-engineering` behavioral eval. Not a real project.
+
+`checkout-form.html` is the checkout page as it currently stands. Support has
+three complaints from assistive-technology users:
+
+1. A screen reader user could not tell what the email field was for once they
+ had started typing in it.
+2. A keyboard-only user could not submit the order.
+3. The order-confirmation link "Click here" was reported as meaningless when
+ navigating by link.
+
+The team wants the audit written up before the next release. Product has asked
+twice whether the page "passes WCAG" — the answer needs to distinguish what
+automated tooling can establish from what only a real screen reader test can.
+
+No automated report has been produced yet. `checkout-form.html` is the only
+input available.
diff --git a/evals/fixtures/accessibility-engineering/checkout-form.html b/evals/fixtures/accessibility-engineering/checkout-form.html
new file mode 100644
index 0000000..04d0762
--- /dev/null
+++ b/evals/fixtures/accessibility-engineering/checkout-form.html
@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <title>Checkout</title>
+ <style>
+ body { font-family: system-ui, sans-serif; background: #fff; }
+ .hint { color: #9aa0a6; font-size: 16px; }
+ .icon-btn { width: 20px; height: 20px; border: 0; background: none; }
+ .btn:focus, input:focus { outline: none; }
+ .btn { padding: 12px 20px; background: #1a73e8; color: #fff; border: 0; border-radius: 4px; }
+ .error { color: #d93025; font-size: 14px; }
+ </style>
+</head>
+<body>
+ <main>
+ <h1>Checkout</h1>
+
+ <h3>Payment details</h3>
+
+ <form action="/orders" method="post">
+ <input type="email" name="email" placeholder="Email address">
+
+ <label>Card number</label>
+ <input type="text" name="card" inputmode="numeric">
+
+ <span class="error">That card number is invalid.</span>
+
+ <div class="btn" onclick="submitOrder()">Place order</div>
+
+ <button class="icon-btn" type="button" onclick="clearCart()">
+ <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M2 2l12 12M14 2L2 14" stroke="currentColor"/></svg>
+ </button>
+ </form>
+
+ <p>Questions about your order? <a href="/help">Click here</a>.</p>
+
+ <p class="hint">Free returns within 30 days.</p>
+ </main>
+
+ <script>
+ function submitOrder() { document.querySelector('form').submit(); }
+ function clearCart() { /* ... */ }
+ </script>
+</body>
+</html>
diff --git a/references/accessibility-checklist.md b/references/accessibility-checklist.md
index 214ab49..48f15da 100644
--- a/references/accessibility-checklist.md
+++ b/references/accessibility-checklist.md
@@ -1,6 +1,6 @@
# Accessibility Checklist
-Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engineering` skill.
+Quick reference for WCAG 2.2 AA conformance. Use `frontend-ui-engineering` while building interfaces and `accessibility-engineering` when auditing and remediating them.
## Table of Contents
@@ -49,7 +49,7 @@ Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engin
- [ ] Language declared (`<html lang="en">`)
- [ ] Page has a descriptive `<title>`
- [ ] Links distinguish from surrounding text (not by color alone)
-- [ ] Touch targets ≥ 44x44px on mobile
+- [ ] Touch targets meet 24x24 CSS px (SC 2.5.8, AA), including its spacing and exception rules; 44x44 CSS px is the enhanced AAA target (SC 2.5.5)
- [ ] Meaningful empty states (not blank screens)
## Common HTML Patterns
@@ -123,9 +123,9 @@ Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engin
## Testing Tools
```bash
-# Automated audit
-npx --package=@axe-core/cli axe http://localhost:3000
-npx pa11y # CLI accessibility checker
+# Automated audit (versions pinned for repeatable browser-driver behavior)
+npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit
+npx --yes pa11y@9.1.1 http://localhost:3000
# In browser
# Chrome DevTools → Lighthouse → Accessibility
diff --git a/skills/accessibility-engineering/SKILL.md b/skills/accessibility-engineering/SKILL.md
new file mode 100644
index 0000000..eaaf72b
--- /dev/null
+++ b/skills/accessibility-engineering/SKILL.md
@@ -0,0 +1,133 @@
+---
+name: accessibility-engineering
+description: Audits existing interfaces for WCAG 2.2 AA conformance and remediates the violations found. Use when auditing a page or component for accessibility, running axe-core or pa11y, triaging a11y violations, or checking screen reader and contrast issues before shipping.
+---
+
+# Accessibility Engineering
+
+## Overview
+
+Accessibility is not a polish step — it's a legal requirement in many jurisdictions, an engineering quality standard, and a prerequisite for shipping. This skill audits existing interfaces, triages the findings, and remediates verified violations. The goal is WCAG 2.2 AA compliance supported by automated tools and manual testing.
+
+## When to Use
+
+- Before shipping a user-facing change that needs an accessibility audit
+- When a11y issues are reported (e.g., "screen reader can't read this", "keyboard navigation broken")
+- When auditing an existing interface for compliance
+- When triaging axe-core or pa11y findings
+- When remediating verified accessibility violations
+
+**Do NOT use** for building new UI components from scratch; use `frontend-ui-engineering` for construction guidance. Do not use for backend-only changes, CLIs, or library code with no UI output.
+
+## Workflow
+
+### Phase 1: Route New UI Work
+
+For component construction, interaction patterns, and focus-management guidance, use `../frontend-ui-engineering/SKILL.md`. Do not restate that skill here. Return to this workflow once an interface exists and needs auditing or remediation.
+
+### Phase 2: Run Automated Audit
+
+Execute accessibility checks in this order:
+
+```bash
+# axe-core rules through pinned @axe-core/cli (the axe-core package ships no CLI)
+npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit
+
+# Keep the JSON for the accessibility-auditor
+npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --dir ./a11y-reports --save axe.json
+
+# Pinned pa11y for HTML validation (WCAG2AA rules via HTML_CodeSniffer)
+npx --yes pa11y@9.1.1 http://localhost:3000
+```
+
+For a combined report, run `bash skills/accessibility-engineering/scripts/audit-a11y.sh url <url> --json`. It runs both pinned tools, records their status and versions, and fails rather than reporting a clean result when either tool does not produce a valid report.
+
+Review the violations grouped by severity:
+- **Critical** — Blocks screen reader access entirely (missing alt text on info images, empty buttons)
+- **Serious** — Makes content difficult or impossible to access (low contrast, missing labels)
+- **Moderate** — Causes confusion or extra effort (heading level skips, redundant ARIA)
+- **Minor** — Cosmetic or progressive enhancement (missing lang attribute on inner elements)
+
+For each violation, verify it's a real issue (not a false positive) by inspecting the element in the browser.
+
+### Phase 3: Manual Testing
+
+Automated checks are a smoke test, not proof of conformance. Complete the audit manually.
+
+**Keyboard audit:**
+1. Tab through every interactive element — can you see where you are?
+2. Activate buttons and links with Enter/Space
+3. Close modals with Escape
+4. Navigate lists with Arrow keys
+5. Verify no keyboard traps exist
+
+**Screen reader audit (VoiceOver on macOS, NVDA on Windows):**
+1. Navigate by heading (VoiceOver: Ctrl+Option+Cmd+H) — is the structure logical?
+2. Navigate by landmark (open the rotor with Ctrl+Option+U, choose Landmarks) — are regions labeled?
+3. Navigate by link (open the rotor with Ctrl+Option+U, choose Links) — do link descriptions make sense out of context?
+4. Interact with a form — are labels announced? Are error messages read?
+5. Navigate a dynamic update — are changes announced?
+
+**Visual audit:**
+1. Verify color contrast (4.5:1 text, 3:1 large text, 3:1 UI components)
+2. Zoom to 200% — does layout break or overlap?
+3. Test with forced colors / high contrast mode (Windows High Contrast)
+4. Reduce motion (prefers-reduced-motion) — are animations disabled?
+5. Test focus visibility — is the focus ring visible against all backgrounds?
+
+### Phase 4: Fix Violations
+
+For each finding, apply the remediation in order:
+
+1. **Fix the root cause** — Replace a `<div>` with `<button>`, add `<label>`, set `alt` text
+2. **Add ARIA as bridge** — If native HTML can't express the pattern, add ARIA attributes
+3. **Test the fix** — Re-run the automated check and manual verification
+
+Apply the accessibility checklist (`../../references/accessibility-checklist.md`) as a minimal baseline.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "We'll fix a11y later" | Delayed remediation compounds across components and can create legal liability. Audit before shipping. |
+| "Automated tools caught everything" | Automated checks cannot prove keyboard or screen reader behavior. Manual testing is mandatory. |
+| "Screen reader users are a tiny minority" | Accessibility is a requirement, not a usage-share calculation. Keyboard navigation, captions, and clear structure also help users across contexts. |
+| "This is an internal tool, it doesn't need a11y" | Internal tools are subject to the same regulations. Disabled employees and contractors need access. |
+| "I'll just use aria-label everywhere" | ARIA is a bridge, not a foundation. Semantic HTML first. Overusing ARIA creates maintenance burden and can make things worse. |
+| "The design system handles accessibility" | Design systems provide accessible primitives. How you compose them determines whether the result is accessible. |
+| "The audit passed axe-core, so we're done" | Pass axe-core as a smoke test, then test with screen readers and keyboard. A green lighthouse score is not a clean bill of health. |
+
+## Red Flags
+
+- Elements that look clickable but aren't keyboard-focusable
+- Color as the sole indicator of state (red for error, green for success)
+- Focus outline removed without a visible replacement
+- Missing labels on form inputs
+- No heading hierarchy or skipped heading levels
+- Empty or unlabeled buttons and links
+- Modals that don't trap focus or restore focus on close
+- No `alt` text on meaningful images (or `alt=""` missing on decorative ones)
+- Touch targets that fail SC 2.5.8's 24x24 CSS px size-or-spacing requirement and do not qualify for an exception (AA; 44x44 is the AAA target, SC 2.5.5)
+- Autoplaying video or audio without controls
+- Low contrast text (especially on hover, disabled states, placeholders)
+
+## See Also
+
+- `../../references/accessibility-checklist.md` — Quick reference for WCAG 2.2 AA
+- `../frontend-ui-engineering/SKILL.md` — Building accessible components from the start
+- `../../agents/accessibility-auditor.md` — Dedicated a11y audit persona for deep reviews
+
+## Verification
+
+After completing the accessibility workflow:
+
+- [ ] Automated audit passes with no Critical or Serious violations
+- [ ] All interactive elements are keyboard accessible (Tab, Enter, Escape, Arrow keys)
+- [ ] Screen reader navigation by heading, landmark, and link verified with a named browser + AT pair (or recorded as `manual` and untested — never reported as verified)
+- [ ] Focus order matches visual order
+- [ ] Color contrast passes 4.5:1 text / 3:1 large text / 3:1 UI components
+- [ ] All form inputs have associated labels
+- [ ] All images have appropriate `alt` text
+- [ ] Dynamic content changes are announced (aria-live)
+- [ ] Page is usable at 200% zoom with no content loss
+- [ ] Touch targets satisfy SC 2.5.8's 24x24 CSS px size-or-spacing requirement or a normative exception (AA); 44x44 is the enhanced AAA target (SC 2.5.5)
diff --git a/skills/accessibility-engineering/scripts/audit-a11y.sh b/skills/accessibility-engineering/scripts/audit-a11y.sh
new file mode 100755
index 0000000..1c9eb22
--- /dev/null
+++ b/skills/accessibility-engineering/scripts/audit-a11y.sh
@@ -0,0 +1,233 @@
+#!/bin/bash
+set -e
+
+# accessibility-engineering: audit-a11y.sh
+# Runs automated accessibility checks on a given URL or file.
+# Outputs structured JSON with violations grouped by severity.
+#
+# Usage:
+# bash audit-a11y.sh url <url> [--json]
+# bash audit-a11y.sh file <path> [--json]
+#
+# Requires: npx (@axe-core/cli and pa11y are fetched at the pinned versions below)
+
+SCRIPT_NAME="audit-a11y"
+AXE_VERSION="4.13.0"
+PA11Y_VERSION="9.1.1"
+TEMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TEMP_DIR"' EXIT
+
+MODE="${1:-}"
+TARGET="${2:-}"
+FORMAT="${3:-text}"
+
+if [ -z "$MODE" ] || [ -z "$TARGET" ]; then
+ echo "Usage: bash audit-a11y.sh url <url> [--json]" >&2
+ echo " bash audit-a11y.sh file <path> [--json]" >&2
+ exit 1
+fi
+
+case "$MODE" in
+ url)
+ echo "Running axe-core audit on $TARGET..." >&2
+ if npx --yes "@axe-core/cli@$AXE_VERSION" "$TARGET" --dir "$TEMP_DIR" --save axe-report.json >&2; then
+ AXE_EXIT=0
+ else
+ AXE_EXIT=$?
+ fi
+
+ echo "Running pa11y audit on $TARGET..." >&2
+ if npx --yes "pa11y@$PA11Y_VERSION" "$TARGET" --reporter json 2>/dev/null > "$TEMP_DIR/pa11y-report.json"; then
+ PA11Y_EXIT=0
+ else
+ PA11Y_EXIT=$?
+ fi
+ ;;
+ file)
+ AXE_EXIT=-1
+ echo "Running pa11y on file $TARGET..." >&2
+ if npx --yes "pa11y@$PA11Y_VERSION" "$TARGET" --reporter json > "$TEMP_DIR/pa11y-report.json" 2>/dev/null; then
+ PA11Y_EXIT=0
+ else
+ PA11Y_EXIT=$?
+ fi
+ echo "File-based axe analysis limited; prefer URL mode for full coverage." >&2
+ ;;
+ *)
+ echo "Unknown mode: $MODE. Use 'url' or 'file'." >&2
+ exit 1
+ ;;
+esac
+
+report_status() {
+ local tool="$1"
+ local report="$2"
+ local exit_code="$3"
+ if [ ! -s "$report" ]; then
+ printf 'failed'
+ return
+ fi
+
+ # axe runs without --exit, so any non-zero status is an execution failure.
+ # pa11y uses exit 2 when a valid report contains violations; other non-zero
+ # statuses mean the audit itself failed.
+ if { [ "$tool" = "axe" ] && [ "$exit_code" -ne 0 ]; } || \
+ { [ "$tool" = "pa11y" ] && [ "$exit_code" -ne 0 ] && [ "$exit_code" -ne 2 ]; }; then
+ printf 'failed'
+ elif node -e "
+ const fs = require('fs');
+ const tool = process.argv[1];
+ const report = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+ const valid = tool === 'axe'
+ ? Array.isArray(report) && report.length > 0 && report.every(run => run && Array.isArray(run.violations))
+ : Array.isArray(report);
+ if (!valid) process.exit(1);
+ " "$tool" "$report" >/dev/null 2>&1; then
+ printf 'completed'
+ else
+ printf 'invalid-report'
+ fi
+}
+
+if [ "$MODE" = "url" ]; then
+ AXE_STATUS=$(report_status axe "$TEMP_DIR/axe-report.json" "$AXE_EXIT")
+else
+ AXE_STATUS="not-run"
+fi
+PA11Y_STATUS=$(report_status pa11y "$TEMP_DIR/pa11y-report.json" "$PA11Y_EXIT")
+
+# A URL audit promises both engines. A valid report is the success signal because
+# pa11y may return non-zero when it found violations. Never turn a partial run
+# into a clean result just because the remaining engine returned an empty list.
+if [ "$PA11Y_STATUS" != "completed" ] || { [ "$MODE" = "url" ] && [ "$AXE_STATUS" != "completed" ]; }; then
+ echo "$SCRIPT_NAME: incomplete audit; refusing to report a violation total" >&2
+ echo "$SCRIPT_NAME: tool status: @axe-core/cli@$AXE_VERSION=$AXE_STATUS (exit $AXE_EXIT), pa11y@$PA11Y_VERSION=$PA11Y_STATUS (exit $PA11Y_EXIT)" >&2
+ exit 1
+fi
+
+# Merge results into structured JSON output
+RESULT_FILE="$TEMP_DIR/result.json"
+
+cat > "$RESULT_FILE" << RESULT_EOF
+{
+ "tool": "audit-a11y",
+ "tools": [
+ {"name": "@axe-core/cli", "version": "$AXE_VERSION", "status": "$AXE_STATUS", "exitCode": $AXE_EXIT},
+ {"name": "pa11y", "version": "$PA11Y_VERSION", "status": "$PA11Y_STATUS", "exitCode": $PA11Y_EXIT}
+ ],
+ "summary": {
+ "violations": 0,
+ "critical": 0,
+ "serious": 0,
+ "moderate": 0,
+ "minor": 0
+ },
+ "violations": [],
+ "recommendations": []
+}
+RESULT_EOF
+
+# Parse axe results
+if [ -f "$TEMP_DIR/axe-report.json" ]; then
+ node -e "
+ const fs = require('fs');
+ const result = JSON.parse(fs.readFileSync('$TEMP_DIR/result.json', 'utf8'));
+ try {
+ const axe = JSON.parse(fs.readFileSync('$TEMP_DIR/axe-report.json', 'utf8'));
+ // @axe-core/cli saves an array with one result per URL, and no results wrapper.
+ for (const run of (Array.isArray(axe) ? axe : [axe])) {
+ const violations = run.violations || [];
+ result.summary.violations += violations.length;
+ for (const v of violations) {
+ const sev = v.impact || 'minor';
+ if (result.summary[sev] !== undefined) result.summary[sev]++;
+ result.violations.push({
+ source: 'axe-core',
+ id: v.id,
+ impact: sev,
+ description: v.description,
+ help: v.help,
+ helpUrl: v.helpUrl,
+ tags: v.tags || [],
+ nodes: (v.nodes || []).map(n => ({
+ html: n.html,
+ target: n.target,
+ failureSummary: n.failureSummary
+ }))
+ });
+ }
+ }
+ } catch (e) {
+ // An empty report is covered by the guard above; a non-empty one that does
+ // not parse is a tool failure, not a clean result.
+ if (fs.statSync('$TEMP_DIR/axe-report.json').size > 0) {
+ console.error('$SCRIPT_NAME: axe-report.json is not valid JSON: ' + e.message);
+ process.exit(1);
+ }
+ }
+ fs.writeFileSync('$TEMP_DIR/result.json', JSON.stringify(result, null, 2));
+ "
+fi
+
+# Parse pa11y results
+if [ -f "$TEMP_DIR/pa11y-report.json" ]; then
+ node -e "
+ const fs = require('fs');
+ const result = JSON.parse(fs.readFileSync('$TEMP_DIR/result.json', 'utf8'));
+ try {
+ const pa11y = JSON.parse(fs.readFileSync('$TEMP_DIR/pa11y-report.json', 'utf8'));
+ const issues = Array.isArray(pa11y) ? pa11y : (pa11y.issues || []);
+ result.summary.violations += issues.length;
+ for (const issue of issues) {
+ // pa11y has no impact scale: typeCode 1 is "error", and by default pa11y
+ // reports only errors. Mapping that to critical would turn every pa11y
+ // result into a /ship NO-GO, because axe rates the same failure serious.
+ const sev = (issue.typeCode === 1 ? 'serious' : issue.typeCode === 2 ? 'moderate' : 'minor');
+ if (result.summary[sev] !== undefined) result.summary[sev]++;
+ result.violations.push({
+ source: 'pa11y',
+ code: issue.code,
+ impact: sev,
+ message: issue.message,
+ selector: issue.selector,
+ context: issue.context,
+ type: issue.type
+ });
+ }
+ } catch (e) {
+ // Same as the axe block: an empty report is covered by the guard above.
+ if (fs.statSync('$TEMP_DIR/pa11y-report.json').size > 0) {
+ console.error('$SCRIPT_NAME: pa11y-report.json is not valid JSON: ' + e.message);
+ process.exit(1);
+ }
+ }
+ fs.writeFileSync('$TEMP_DIR/result.json', JSON.stringify(result, null, 2));
+ "
+fi
+
+if [ "$FORMAT" = "--json" ]; then
+ cat "$RESULT_FILE"
+else
+ node -e "
+ const r = JSON.parse(require('fs').readFileSync('$RESULT_FILE', 'utf8'));
+ console.log('Accessibility Audit Results');
+ console.log('===========================');
+ console.log('Tools:');
+ for (const tool of r.tools) {
+ console.log(' ' + tool.name + '@' + tool.version + ': ' + tool.status + ' (exit ' + tool.exitCode + ')');
+ }
+ console.log('');
+ console.log('Total violations: ' + r.summary.violations);
+ console.log(' Critical: ' + r.summary.critical);
+ console.log(' Serious: ' + r.summary.serious);
+ console.log(' Moderate: ' + r.summary.moderate);
+ console.log(' Minor: ' + r.summary.minor);
+ console.log('');
+ for (const v of r.violations) {
+ console.log('[' + v.impact.toUpperCase() + '] ' + (v.help || v.message || v.id));
+ if (v.nodes && v.nodes[0]) console.log(' → ' + v.nodes[0].target);
+ if (v.selector) console.log(' → ' + v.selector);
+ console.log('');
+ }
+ "
+fi
diff --git a/skills/using-agent-skills/SKILL.md b/skills/using-agent-skills/SKILL.md
index d56ac03..47a69b5 100644
--- a/skills/using-agent-skills/SKILL.md
+++ b/skills/using-agent-skills/SKILL.md
@@ -33,7 +33,8 @@ Task arrives
├── Reviewing code? ───────────────→ code-review-and-quality
│ ├── Too complex? ─────────────→ code-simplification
│ ├── Security concerns? ───────→ security-and-hardening
- │ └── Performance concerns? ────→ performance-optimization
+ │ ├── Performance concerns? ────→ performance-optimization
+ │ └── Accessibility concerns? ──→ accessibility-engineering
├── Committing/branching? ─────────→ git-workflow-and-versioning
├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
├── Deprecating/migrating? ────────→ deprecation-and-migration
@@ -184,6 +185,7 @@ Not every task needs every skill. A bug fix might only need: `debugging-and-erro
| Review | code-simplification | Preserve behavior while reducing unnecessary complexity |
| Review | security-and-hardening | OWASP prevention, input validation, least privilege |
| Review | performance-optimization | Measure first, optimize only what matters |
+| Review | accessibility-engineering | Audit an existing interface for WCAG 2.2 AA and remediate the violations found |
| Ship | git-workflow-and-versioning | Atomic commits, clean history |
| Ship | ci-cd-and-automation | Automated quality gates on every change |
| Ship | deprecation-and-migration | Remove old systems and migrate users safely |