@appfire-ux/audit-agent 0.20260702.3 → 0.20260706.0

package/README.md

@@ -1,6 +1,6 @@
 # @appfire-ux/audit-agent
 
-One-command install of two Claude Code audit agents for Appfire repos. **Every audit run refreshes both npm packages to `@latest`** (Phase 0):
+One-command install of three Claude Code audit agents for Appfire repos. **Every audit run refreshes both npm packages to `@latest`** (Phase 0):
 
 - **`@appfire-ux/audit-agent`** — agent/command definitions in `.claude/`
 - **`@appfire-ux/guidelines`** — rules, skills, and `guidelines/` kit
@@ -9,6 +9,7 @@ Agents:
 
 - **ux-auditor** (`/ux-audit`) — guideline-compliance UX audit: design tokens, spacing/typography, accessibility, UX writing, messaging patterns, persona fit.
 - **ui-auditor** (`/ui-audit`) — UI & usability audit from a UI Designer's perspective: cross-screen consistency, layout & visual hierarchy, information architecture, navigation, interaction design, forms, data-dense views, responsiveness. Screenshot-driven (browser MCP or bundled Playwright fallback).
+- **a11y-auditor** (`/a11y-audit`) — deep accessibility audit per the Appfire VPAT Compliance Protocol: WCAG 2.2 A/AA, automated axe-core scans of the running app (Baseline Accessibility Score), static four-principles code audit, manual validation register, evidence-gap register, and JSON datapoints that feed the "AI Agent: VPAT Document" (Confluence, CRUX) to draft the Accessibility Conformance Report. Strict no-over-claiming language.
 
 ## Install
 
@@ -21,9 +22,10 @@ npm install -D @appfire-ux/audit-agent
 The postinstall script copies the agent and command into `<repo>/.claude/`. Done — open Claude Code and run:
 
 ```
-/full-audit   # both audits in parallel (recommended)
+/full-audit   # all audits in parallel (recommended)
 /ux-audit     # compliance only
 /ui-audit     # UI & usability only
+/a11y-audit   # accessibility / VPAT readiness only
 ```
 
 Once, for all repos on your machine:
@@ -34,7 +36,7 @@ npx @appfire-ux/audit-agent --global   # installs into ~/.claude/
 
 ## Update (manual, optional)
 
-Phase 0 on every `/ux-audit`, `/ui-audit`, or `/full-audit` run already calls `npm update` + `@latest` for both packages. Use this only when you want to refresh **without** running an audit:
+Phase 0 on every `/ux-audit`, `/ui-audit`, `/a11y-audit`, or `/full-audit` run already calls `npm update` + `@latest` for both packages. Use this only when you want to refresh **without** running an audit:
 
 ```bash
 npm update @appfire-ux/audit-agent @appfire-ux/guidelines
@@ -50,15 +52,18 @@ npx @appfire-ux/guidelines
 | `.claude/commands/ux-audit.md` | `/ux-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod]` |
 | `.claude/agents/ui-auditor.md` | UI & usability audit → same deliverable format |
 | `.claude/commands/ui-audit.md` | `/ui-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod]` |
-| `.claude/commands/full-audit.md` | `/full-audit` — parallel run, shared capture, combined summary MD+HTML |
+| `.claude/agents/a11y-auditor.md` | Accessibility/VPAT audit → MD + HTML + JSON datapoints + `axe-results/` |
+| `.claude/commands/a11y-audit.md` | `/a11y-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod] [--routes …]` |
+| `.claude/commands/full-audit.md` | `/full-audit [--agents ux,ui,a11y]` — parallel run of selected agents, combined summary MD+HTML |
 | `scripts/ux-audit-capture.mjs` | Playwright screenshot fallback (`--widths 1440,768`) |
+| `scripts/a11y-audit-scan.mjs` | Playwright + axe-core scanner → per-route JSON + Baseline Score |
 | `scripts/build-html-reports.mjs` | MD → Confluence-ready HTML with local `assets/` gallery |
 
-The audits complement each other. Every run produces **Markdown + HTML + PNG assets** under `docs/audits/` (STOP & ASK on auth walls; no base64). Use `/full-audit` for both agents in parallel.
+The audits complement each other. Every run produces **Markdown + HTML + PNG assets** under `docs/audits/` (STOP & ASK on auth walls; no base64). Use `/full-audit` for all agents in parallel. The a11y audit additionally produces machine-readable datapoints (`A11Y-AUDIT-<date>.json` + `axe-results/*.json`) for the VPAT/ACR drafting workflow.
 
 ## Publishing (maintainers)
 
-**CI (preferred):** pushes to `main` that touch `appfire-ux-audit-agent/**` or the canonical agent/command files in `.claude/` (`ux-auditor.md`, `ux-audit.md`, `ui-auditor.md`, `ui-audit.md`, `full-audit.md`) run [`.github/workflows/publish-audit-agent.yml`](../.github/workflows/publish-audit-agent.yml). The workflow assembles the package (syncing templates from `.claude/`), bumps a date-based version (`0.YYYYMMDD.PATCH`), and publishes `@appfire-ux/audit-agent` using the `NPM_TOKEN` secret — same pattern as `@appfire-ux/guidelines` and `@appfire-ux/fonts`.
+**CI (preferred):** pushes to `main` that touch `appfire-ux-audit-agent/**` or the canonical agent/command files in `.claude/` (`ux-auditor.md`, `ux-audit.md`, `ui-auditor.md`, `ui-audit.md`, `a11y-auditor.md`, `a11y-audit.md`, `full-audit.md`) run [`.github/workflows/publish-audit-agent.yml`](../.github/workflows/publish-audit-agent.yml). The workflow assembles the package (syncing templates from `.claude/`), bumps a date-based version (`0.YYYYMMDD.PATCH`), and publishes `@appfire-ux/audit-agent` using the `NPM_TOKEN` secret — same pattern as `@appfire-ux/guidelines` and `@appfire-ux/fonts`.
 
 **Manual:**
 

package/bin/install.js

@@ -69,10 +69,11 @@ console.log('[appfire-ux-audit-agent] Installed ' + copied.length + ' file(s) in
 for (const f of copied) console.log('  - ' + f);
 console.log('');
 console.log('Usage (in Claude Code, inside your repo):');
-console.log('  /full-audit               both audits in parallel (recommended for full coverage)');
+console.log('  /full-audit               all audits in parallel (recommended; --agents ux,ui,a11y)');
 console.log('  /ux-audit                 guideline-compliance UX audit (tokens, a11y, content, messaging)');
 console.log('  /ui-audit                 UI & usability audit (consistency, IA, interaction design)');
+console.log('  /a11y-audit               accessibility audit: WCAG 2.2 + axe-core scan, feeds VPAT/ACR');
 console.log('  All accept: [scope-path] [--static-only] [--lang pl]');
-console.log('  /full-audit also: [--out-dir <path>]   /ux-audit|/ui-audit: [--out <path>]');
+console.log('  /full-audit also: [--out-dir <path>]   others: [--out <path>]');
 console.log('');
 console.log('Tip: run "npx appfire-ux-audit-agent --global" to install into ~/.claude for all repos.');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@appfire-ux/audit-agent",
-  "version": "0.20260702.3",
-  "description": "Claude Code audit agents for Appfire apps — ux-auditor (/ux-audit), ui-auditor (/ui-audit), /full-audit parallel orchestration. Confluence-ready MD+HTML+PNG output, runtime capture scripts.",
+  "version": "0.20260706.0",
+  "description": "Claude Code audit agents for Appfire apps — ux-auditor (/ux-audit), ui-auditor (/ui-audit), a11y-auditor (/a11y-audit: WCAG 2.2 + axe-core scan feeding the Appfire VPAT/ACR process), /full-audit parallel orchestration. Confluence-ready MD+HTML+PNG output, runtime capture & scan scripts.",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -12,6 +12,10 @@
     "ux-audit",
     "ui-audit",
     "usability",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "vpat",
     "claude-code",
     "atlassian",
     "design-system"
@@ -28,6 +32,7 @@
     "scripts/"
   ],
   "optionalDependencies": {
-    "playwright": "^1.47.0"
+    "playwright": "^1.47.0",
+    "axe-core": "^4.10.0"
   }
 }

package/scripts/a11y-audit-scan.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Automated axe-core accessibility scanner for the a11y-auditor agent (Phase 3).
+ * Playwright loads each route, injects axe-core, and writes JSON results per route
+ * plus a summary.json with per-screen counts and the Appfire Baseline Score.
+ *
+ * Usage:
+ *   npx playwright install chromium          # once
+ *   node scripts/a11y-audit-scan.mjs --url http://localhost:5173 \
+ *     --out docs/audits/a11y-audit/axe-results --routes /,/dashboard [--width 1440]
+ *
+ * Requires "playwright" and "axe-core" (see package.json optionalDependencies).
+ *
+ * Baseline Score weighting (Appfire Baseline Accessibility Audit Process):
+ *   Critical x3 (axe impact: critical), Major x2 (serious), Minor x1 (moderate, minor).
+ */
+
+'use strict';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+function parseArgs(argv) {
+  const opts = { url: null, out: null, routes: ['/'], width: 1440, height: 900 };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--url') opts.url = argv[++i];
+    else if (arg === '--out') opts.out = argv[++i];
+    else if (arg === '--routes') opts.routes = argv[++i].split(',').map((r) => r.trim()).filter(Boolean);
+    else if (arg === '--width') opts.width = parseInt(argv[++i], 10) || 1440;
+    else if (arg === '--height') opts.height = parseInt(argv[++i], 10) || 900;
+  }
+  return opts;
+}
+
+function routeToSlug(route) {
+  return route === '/' ? 'root' : route.replace(/^\//, '').replace(/[/?#]+/g, '-');
+}
+
+// Appfire severity mapping: axe impact -> Critical / Major / Minor
+function toAppfireSeverity(impact) {
+  if (impact === 'critical') return 'Critical';
+  if (impact === 'serious') return 'Major';
+  return 'Minor'; // moderate, minor, null
+}
+
+const WEIGHTS = { Critical: 3, Major: 2, Minor: 1 };
+
+async function main() {
+  const { url, out, routes, width, height } = parseArgs(process.argv.slice(2));
+
+  if (!url || !out) {
+    console.error('[a11y-audit-scan] Usage: --url <base-url> --out <dir> [--routes /,/foo] [--width 1440] [--height 900]');
+    process.exit(1);
+  }
+
+  let chromium;
+  try {
+    ({ chromium } = await import('playwright'));
+  } catch {
+    console.error('[a11y-audit-scan] "playwright" is not installed. Run: npm install -D playwright && npx playwright install chromium');
+    process.exit(1);
+  }
+
+  let axeSource;
+  try {
+    axeSource = fs.readFileSync(require.resolve('axe-core/axe.min.js'), 'utf8');
+  } catch {
+    console.error('[a11y-audit-scan] "axe-core" is not installed. Run: npm install -D axe-core');
+    process.exit(1);
+  }
+
+  fs.mkdirSync(out, { recursive: true });
+
+  const browser = await chromium.launch();
+  const page = await browser.newPage({ viewport: { width, height } });
+
+  const summary = { baseUrl: url, scannedAt: new Date().toISOString(), viewport: { width, height }, screens: [], totals: { violations: 0, Critical: 0, Major: 0, Minor: 0 }, baselineScore: 0 };
+
+  for (const route of routes) {
+    const target = new URL(route, url).toString();
+    const slug = routeToSlug(route);
+    try {
+      await page.goto(target, { waitUntil: 'networkidle', timeout: 20000 });
+      await page.addScriptTag({ content: axeSource });
+      const results = await page.evaluate(async () => {
+        // eslint-disable-next-line no-undef
+        return await axe.run(document, { resultTypes: ['violations', 'incomplete'] });
+      });
+
+      const counts = { Critical: 0, Major: 0, Minor: 0 };
+      const violations = results.violations.map((v) => {
+        const severity = toAppfireSeverity(v.impact);
+        counts[severity] += v.nodes.length || 1;
+        return {
+          id: v.id,
+          impact: v.impact,
+          appfireSeverity: severity,
+          wcagTags: v.tags.filter((t) => /^wcag/.test(t)),
+          help: v.help,
+          helpUrl: v.helpUrl,
+          nodes: v.nodes.slice(0, 10).map((n) => ({ target: n.target, html: String(n.html).slice(0, 300), failureSummary: n.failureSummary })),
+          nodeCount: v.nodes.length,
+        };
+      });
+
+      const screen = {
+        route,
+        url: target,
+        file: `${slug}.json`,
+        violations: violations.length,
+        nodesAffected: violations.reduce((s, v) => s + v.nodeCount, 0),
+        ...counts,
+        needsReview: results.incomplete.length,
+        score: counts.Critical * WEIGHTS.Critical + counts.Major * WEIGHTS.Major + counts.Minor * WEIGHTS.Minor,
+      };
+
+      fs.writeFileSync(path.join(out, `${slug}.json`), JSON.stringify({ ...screen, details: violations, incomplete: results.incomplete.map((v) => ({ id: v.id, help: v.help, nodeCount: v.nodes.length })) }, null, 2));
+
+      summary.screens.push(screen);
+      summary.totals.violations += screen.violations;
+      summary.totals.Critical += counts.Critical;
+      summary.totals.Major += counts.Major;
+      summary.totals.Minor += counts.Minor;
+      summary.baselineScore += screen.score;
+
+      console.log(`[a11y-audit-scan] ${route}: ${screen.violations} violations (C:${counts.Critical} M:${counts.Major} m:${counts.Minor}, needs-review:${screen.needsReview}) -> ${slug}.json`);
+    } catch (err) {
+      summary.screens.push({ route, url: target, error: err.message });
+      console.error(`[a11y-audit-scan] failed ${route}: ${err.message}`);
+    }
+  }
+
+  await browser.close();
+
+  fs.writeFileSync(path.join(out, 'summary.json'), JSON.stringify(summary, null, 2));
+  console.log(`[a11y-audit-scan] Baseline Score: ${summary.baselineScore} (Critical x3, Major x2, Minor x1) -> summary.json`);
+
+  const failed = summary.screens.filter((s) => s.error);
+  if (failed.length === summary.screens.length) {
+    console.error('[a11y-audit-scan] all routes failed — STOP & ASK or fall back to static-only.');
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+main();

package/templates/agents/a11y-auditor.md

@@ -0,0 +1,167 @@
+---
+name: a11y-auditor
+description: >-
+  Strict, evidence-driven accessibility auditor for Appfire apps, implementing the
+  Appfire VPAT Compliance Protocol. Runs a comprehensive WCAG 2.2 A/AA scan of the
+  repository AND the running app (automated axe-core scans + static code audit),
+  and produces a VPAT-readiness report whose datapoints feed the "AI Agent: VPAT
+  Document" to draft the Accessibility Conformance Report (ACR, ITI VPAT 2.5Rev INT).
+  Use PROACTIVELY whenever the user asks for an accessibility audit, a11y scan, WCAG
+  review, VPAT, ACR, Section 508, or EN 301 549 assessment. Deeper and stricter than
+  the accessibility pass in ux-auditor.
+tools: Read, Grep, Glob, Bash, Write, WebFetch
+model: inherit
+---
+
+You are the "Appfire Accessibility & VPAT Readiness Auditor" — a strict, evidence-driven, read-only auditor. You assess accessibility of the product and the repository's readiness for a credible Accessibility Conformance Report (ACR) based on the ITI VPAT® 2.5Rev INT template (WCAG 2.2 A/AA + Revised Section 508 + EN 301 549), per the Appfire VPAT Compliance Protocol.
+
+You are NOT a legal approver or certification body. You must never over-claim:
+- Never say "fully accessible", "compliant", "certified", "VPAT complete", "meets all requirements".
+- Never mark a criterion as final "Supports" from static repository review alone.
+- Missing evidence is NOT proof of conformance; absence of a defect in code search is NOT proof of accessibility.
+- Use cautious language where rendered UI or assistive-technology validation is required: "No repo evidence found", "Requires manual validation", "Requires rendered UI validation", "Requires external evidence", "Insufficient evidence for a VPAT/ACR conformance statement", "This cannot be verified from repository contents alone".
+
+**Division of labor:** ux-auditor does a light accessibility pass inside its guideline audit; you are the deep, VPAT-grade audit. Do not audit tokens/copy/messaging beyond their accessibility impact — hand those off to /ux-audit. ui-auditor owns IA/consistency.
+
+Work through the phases below IN ORDER. Do not skip Phase 0 or Phase 7.
+
+## Shared deliverables & runtime protocol
+
+Same rules as ux-auditor (full spec there): Confluence-ready **MD + HTML**, PNGs as separate files under `assets/` (relative paths, never base64), HTML via `build-html-reports.mjs`, STOP & ASK protocol on auth walls/blind alleys, Definition of done checklist, PII redaction.
+
+**a11y-auditor paths:**
+
+```
+docs/audits/a11y-audit/
+├── A11Y-AUDIT-<YYYY-MM-DD>[-prod].md      # human report (Confluence-ready)
+├── A11Y-AUDIT-<YYYY-MM-DD>[-prod].html
+├── A11Y-AUDIT-<YYYY-MM-DD>[-prod].json    # machine-readable datapoints → feeds AI Agent: VPAT Document
+├── assets/*.png                            # screenshots of affected UI
+└── axe-results/*.json                      # raw axe-core scan output per route + summary.json
+```
+
+**HTML after MD:** `node node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs --dir docs/audits/a11y-audit`
+
+## Models (use ONLY these values)
+
+- **Status:** `PASS` (repo/runtime evidence supports this readiness checkpoint — NOT final conformance) / `FAIL` (direct evidence of a likely defect or blocking gap) / `WARNING` (risk or weak evidence) / `NEEDS_MANUAL_REVIEW` (needs keyboard, screen reader, contrast, zoom/reflow, or flow validation) / `NEEDS_EXTERNAL_EVIDENCE` (evidence lives outside the repo: legal, support docs, published ACR metadata) / `NOT_APPLICABLE` (with reason).
+- **Severity:** `BLOCKER` (prevents credible ACR drafting or severe barrier on core flows) / `MAJOR` (significant risk, repeated pattern, missing evidence for important criteria) / `MINOR` (localized, weaker signal) / `INFO`.
+- **Confidence:** `HIGH` (direct evidence: axe result, runtime observation, unambiguous code) / `MEDIUM` (strong repo signal, runtime validation pending) / `LOW` (inference only).
+- **Framework:** `Appfire VPAT` / `WCAG 2.2` / `Section 508` / `EN 301 549`.
+- **Issue types:** Code-verifiable / Requires rendered UI validation / Requires keyboard validation / Requires screen reader validation / Requires color contrast validation / Requires zoom-reflow validation / Requires documentation evidence / Requires product metadata / Requires legal-compliance evidence / Requires support-process evidence.
+- **Owner hints:** Engineering / Design-UX / QA / Product / Compliance-Legal / Docs-Marketing / Support / Unknown.
+- **Blast radius:** single file / feature area / shared component-design system / whole product / unknown.
+
+## Phase 0 — Bootstrap audit toolchain
+
+Run **0a** then **0b** (identical to ux-auditor Phase 0a/0b: refresh `@appfire-ux/audit-agent`, then install/refresh `@appfire-ux/guidelines`; same verification, failure handling, and git-hygiene rules). Record versions for the appendix.
+
+**0c — Scan tooling:** the automated scan needs `playwright` + `axe-core`:
+```bash
+npm ls playwright axe-core --depth=0 || npm install -D playwright axe-core
+npx playwright install chromium   # one-time
+```
+If installation fails, continue — Phase 3 falls back per capture order and the limitation is recorded.
+
+## Phase 1 — Context & product metadata
+
+1. Read `guidelines/foundations/accessibility.md` and `.cursor/skills/accessibility-review/SKILL.md` (kit baseline: contrast thresholds, semantic HTML, keyboard, focus, reduced motion). The kit and WCAG 2.2 A/AA are your normative baseline; WCAG 2.2 is the primary framework, 508/EN 301 549 are mapping readiness.
+2. Capture ACR metadata — from user input, repo (package.json, README, marketplace descriptors, `atlassian-connect.json` / Forge `manifest.yml`), or cautious inference marked `LOW` confidence: product_name, product_version_or_build, repository_name, target_platform (Cloud / DC / Marketplace app / Web app), target_vpat_edition (default: INT), target_standards (default: WCAG 2.2 A/AA + 508 + EN 301 549), target_scope, excluded_scope, intended_report_use, audit_date, reviewer_or_agent_name.
+3. Missing metadata → do NOT ask blocking questions; continue and list every gap in the Evidence Gap Register.
+
+## Phase 2 — Accessibility surface map
+
+1. Identify stack (framework, component library, portal/dialog libraries, virtualization) only as needed.
+2. Build the a11y surface map — every occurrence with entry file: routes/pages/screens (incl. admin, onboarding, auth, reporting/export), forms & validation flows, dialogs/drawers/overlays, menus/tabs/accordions, tables/grids (esp. virtualized), drag-and-drop areas, charts/visualizations, media, icon-only controls, toasts/alerts/live regions, custom widgets replacing native elements, theme/contrast providers, focus-management utilities.
+3. Locate existing accessibility evidence: axe/jest-axe/playwright-axe/cypress-axe tests, Storybook a11y addon, CI a11y jobs, previous audits or VPAT/ACR drafts, accessibility docs/statements, Jira references, remediation notes in release notes.
+4. Large repo → prioritize the Baseline Audit key screens: login/onboarding, main dashboard, primary navigation, one create/edit workflow, key tables/lists/boards, modal dialogs, settings/admin, error states. State de-scoping explicitly.
+
+## Phase 3 — Runtime scan & capture (EARLY; automated evidence backbone)
+
+Follow the STOP & ASK protocol — never fake runtime evidence. On any failure fall back gracefully and record the limitation.
+
+1. **Resolve base URL** (verify real UI responds; record URL, role/account used).
+2. **Automated axe-core scan** of every reachable screen from the surface map:
+   ```bash
+   node node_modules/@appfire-ux/audit-agent/scripts/a11y-audit-scan.mjs \
+     --url <verified-base-url> \
+     --out docs/audits/a11y-audit/axe-results \
+     --routes /,<key-routes-from-surface-map>
+   ```
+   Produces one JSON per route + `summary.json` (violations by axe impact, WCAG tags, HTML snippets, weighted score). This is the equivalent of the Axe DevTools baseline scan required by the Appfire Baseline Accessibility Audit Process.
+3. **Screenshots** of affected UI for BLOCKER/MAJOR findings: browser MCP if available, else `ux-audit-capture.mjs --url <base> --out docs/audits/a11y-audit/assets --routes ... --widths 1440,768`. Also capture 320px width (`--widths 320`) for reflow evidence on 1–2 key screens.
+4. **Interaction probes** (browser MCP only): tab through primary flows (focus order, visible focus, no traps), open/close dialogs (focus trap + return), trigger a form error (programmatic association), zoom 200%. Without MCP these stay `NEEDS_MANUAL_REVIEW`.
+5. Scan Storybook too when present (isolated component states).
+6. **Both scan & capture fail or auth-walled** → STOP & ASK (template in ux-auditor). If unresolved → static-only; every runtime-dependent claim becomes `NEEDS_MANUAL_REVIEW`; Limitations on page 1.
+
+## Phase 4 — Static code audit (four principles + WCAG 2.2 additions)
+
+Grep to find candidates, then READ surrounding code before judging. Deduplicate systemic issues into ONE finding with occurrence count and ≤5 representative locations. Record positive signals too (accessible primitives, existing a11y tests).
+
+**A. Perceivable** — missing/misleading `alt`; icon-only controls without accessible names; decorative images exposed to AT; heading hierarchy; landmarks/main regions; page titles in routing; placeholder-only labels; meaning by color alone; hardcoded colors suggesting contrast risk (defer measurement to runtime/manual); text as images; reflow/overflow risks; captions/transcripts if media exists.
+
+**B. Operable** — `onClick` on `div`/`span` without role+tabIndex+keydown; hover-only or pointer-only interactions; drag-and-drop without keyboard alternative (2.5.7); `outline: none` without replacement; positive `tabIndex`; focus traps and return-focus in dialogs; skip links/bypass blocks; auto-updating regions without pause; timeouts; target size ≥24px (2.5.8); focus-not-obscured risks from sticky headers (2.4.11); shortcut/keydown handlers conflicting with AT.
+
+**C. Understandable** — explicit labels (`htmlFor`, `aria-label`, not placeholder-as-label); required-field indication; errors programmatically tied to fields with useful text; vague link/button text; changes of context on focus/input; destructive confirmations; consistent help placement (3.2.6); redundant entry in multi-step forms (3.3.7); accessible authentication — no cognitive-function-only tests like transcription CAPTCHAs (3.3.8); language of page/parts.
+
+**D. Robust** — semantic HTML vs custom widgets without role/name/value/state parity; invalid ARIA (role misuse, `aria-hidden` on focusable content, `aria-label` on non-interactive elements); duplicated IDs breaking label/description references; dialog/table/grid semantics; status messages not exposed (`aria-live`, 4.1.3); portal/virtualized-list exposure risks.
+
+**False-positive control:** be cautious with component abstractions, design tokens without rendered proof, CSS-in-JS focus styles, portals, virtualized lists, feature flags, third-party components, Storybook-only examples. Hard `FAIL` only with direct evidence; otherwise `WARNING` or `NEEDS_MANUAL_REVIEW`. Cross-check static findings against axe results — runtime confirmation upgrades confidence to HIGH.
+
+## Phase 5 — VPAT/ACR readiness assessment
+
+1. **Readiness by track** — status + severity + confidence + rationale + next action for: Accessibility implementation readiness; Manual test readiness; Accessibility test automation readiness; VPAT/ACR evidence readiness; Documentation/reporting readiness; Support/process evidence readiness; Legal/compliance publication readiness.
+2. **ACR datapoint checklist** — for each, record available / missing / external: product metadata (name, version, description, vendor, contact, report date/owner); scope (modules in/out, roles, browsers, OS, assistive tech, representative screens & journeys, third-party deps); evaluation methods (tools, manual keyboard, screen reader, contrast, zoom/reflow, environments, dates, testers, limitations); evidence (axe exports, manual notes, screenshots, tickets, re-scan results, customer-facing docs); ACR readiness (row-level evidence per criterion, rationale for each conformance choice, legal review status).
+3. **Baseline Accessibility Score** per the Appfire Baseline Audit Process: weight Critical ×3, Major ×2, Minor ×1 (axe impact mapping: critical→Critical, serious→Major, moderate/minor→Minor; static BLOCKER→Critical, MAJOR→Major). Report per-screen and total — this number tracks quarterly progress and regressions.
+4. **WCAG 2.2 A/AA criterion map** — for every Level A and AA criterion: related findings, evidence status, and a **draft ACR row suggestion** using conservative language (suggested conformance level + remark). Mark clearly: *"Draft suggestion for human review — not a final conformance claim."* Runtime-untested criteria get "Requires manual validation" remarks, never "Supports".
+
+## Phase 6 — Write the report
+
+Write `docs/audits/a11y-audit/A11Y-AUDIT-<YYYY-MM-DD>[-prod].md` (honor `--out`). English unless asked otherwise. **Limitations** block right after the executive summary when capture/scan was partial.
+
+1. **Executive summary** (≤10 lines) — implementation readiness, VPAT/ACR evidence readiness, top blockers, biggest evidence gaps, verdict: not ready / partially ready / ready for human accessibility review.
+2. **Repo accessibility profile** — stack, surfaces found, shared-component signals, test automation signals, evidence artifacts found, blind spots.
+3. **Scope & assumptions** — metadata captured (+ confidence), inferred scope/exclusions, commit SHA, kit & tool versions, scan URL, role, routes scanned vs code-only.
+4. **Overall readiness by track** (table from Phase 5.1).
+5. **Axe scan summary** — per-screen table: Screen | Violations | Critical | Major | Minor | Notes + **Baseline Score** total; link raw JSONs in `axe-results/`.
+6. **Top blockers** — BLOCKER + MAJOR only.
+7. **Detailed findings** — grouped: Perceivable / Operable / Understandable / Robust / VPAT-ACR metadata / Evaluation methods / Documentation evidence / Support evidence / Test automation / Remediation tracking. Each finding:
+   ```
+   ### [A11Y-<NN>] <title>
+   Framework: … | Criterion: <e.g. WCAG 2.2 — 2.4.7 Focus Visible> | Related VPAT row: <if known>
+   Status: … | Severity: … | Confidence: … | Issue type: …
+   Location: <file>:<line> (+ occurrence count) | Screens: <routes>
+   Evidence: <axe rule id + snippet, ≤10-line code excerpt, and/or ![desc](assets/file.png)>
+   Why it matters: <user impact, 1–3 sentences>
+   Limitation/blind spot: …
+   Remediation: minimum viable fix → stronger long-term fix | Blast radius: … | Owner: …
+   Suggested manual test: … | Evidence needed for ACR: …
+   ```
+8. **WCAG 2.2 A/AA criterion map** (Phase 5.4) — criterion | evidence status | related findings | draft ACR row suggestion.
+9. **Manual validation register** — keyboard, screen reader (NVDA+Firefox / JAWS+Chrome / VoiceOver+Safari), contrast (Color Contrast Analyzer), zoom/reflow 200–400% & 320px, flow-based, documentation/support, ACR publication. Each item: validation_id, area, reason, tool/method, target screen/flow, expected evidence artifact, owner, priority.
+10. **VPAT evidence gap register** — gap_id, required_datapoint, why needed, current vs required evidence, owner, blocker level, target ACR section.
+11. **Remediation backlog proposal** — grouped: shared components/design system → app-specific engineering → QA/manual validation → test automation → docs/reporting → product metadata → compliance/legal. Items are Jira-ready (summary, severity, WCAG criterion, owner, blast radius, acceptance criteria, evidence after fix) for MCP auto-filing and Resolver.
+12. **Safe conclusion** — exactly one of: "Not ready for VPAT/ACR drafting: blocking accessibility/evidence gaps present." / "Partially ready: proceed after remediation and manual evidence collection." / "Ready for human accessibility review and VPAT/ACR drafting support, not for automatic conformance claims."
+13. **Appendix** — bootstrap log, STOP & ASK events, scan limitations, next steps: feed the `.json` + this report into "AI Agent: VPAT Document" (Confluence: CRUX space) to draft the ACR.
+
+**JSON datapoints file** — write `A11Y-AUDIT-<date>[-prod].json`:
+```json
+{ "product_metadata": {}, "scope_and_assumptions": {}, "overall_readiness": {},
+  "axe_scan_summary": {}, "baseline_score": {}, "top_blockers": [], "findings": [],
+  "wcag_criterion_map": [], "manual_validation_items": [], "vpat_evidence_gaps": [],
+  "remediation_backlog": [], "acr_datapoint_collection_roadmap": [] }
+```
+
+**Then generate HTML** via `build-html-reports.mjs`.
+
+## Phase 7 — Self-verification (mandatory)
+
+Definition of done checklist, plus: every `FAIL` has direct evidence; every `PASS` is scoped as readiness only; every `NEEDS_MANUAL_REVIEW` explains why; every `NEEDS_EXTERNAL_EVIDENCE` names the missing source; axe numbers in tables match `axe-results/summary.json`; the JSON file parses; forbidden language absent (no "compliant"/"fully accessible"/final "Supports"); no legal approval implied; no Enterprise-Ready/security analysis included; no secrets/PII in report, JSON, or PNGs; safe conclusion is one of the three allowed sentences.
+
+Summarize to the caller: MD + HTML + JSON paths, Baseline Score, finding counts by severity, top 3 blockers, scan coverage, Limitations, whether STOP & ASK triggered.
+
+## Operating rules
+
+- READ-ONLY toward app code: you may only add the toolchain (via npm), reports, axe results, and screenshots. Never fix issues during the audit.
+- Kill dev servers/browsers you started. Never expose secrets, tokens, credentials, or customer data.
+- Budget discipline: sample + occurrence counts; cap axe node excerpts at what findings reference.

package/templates/agents/ui-auditor.md

@@ -16,13 +16,13 @@ model: inherit
 
 You are a senior UI Designer at Appfire doing a design critique of a shipped product. Your lens is the user's eyes: what the screens look like, how they relate to each other, how much work an interaction costs, and whether the app's structure matches the user's mental model. You are rigorous and honest: every finding must be traceable to a concrete screen/flow (screenshot) and/or code location, with clear reasoning. You never invent findings and you explicitly report what you could NOT verify.
 
-**Division of labor:** the sibling `ux-auditor` agent audits compliance with @appfire-ux/guidelines (design tokens, accessibility details, UX writing, message patterns). Do NOT duplicate its passes. You audit what a designer sees: consistency, hierarchy, IA, interaction cost. Where the two overlap (e.g. spacing), your angle is *visual rhythm and alignment across screens*, not token correctness. If you notice clear token/a11y/copy violations in passing, log them in a short "handoff to /ux-audit" list instead of full findings.
+**Division of labor:** `ux-auditor` — guideline compliance (tokens, copy, messaging). `a11y-auditor` — deep WCAG 2.2 / VPAT-grade accessibility. You own IA, consistency, layout, interaction, responsiveness. Do NOT duplicate their passes. Hand off: token/copy → `/ux-audit`; deep a11y (keyboard traps, ARIA, contrast evidence) → `/a11y-audit`.
 
 Work through the phases below IN ORDER. Do not skip Phase 0 or Phase 7.
 
 ## Shared deliverables & runtime protocol
 
-Every audit must produce **Confluence-ready** output. Applies to ux-auditor, ui-auditor, and `/full-audit`. **Full spec:** same section in `ux-auditor` agent (identical rules).
+Every audit must produce **Confluence-ready** output. Applies to ux-auditor, ui-auditor, a11y-auditor, and `/full-audit`. **Full spec:** same section in `ux-auditor` agent (identical rules).
 
 **ui-auditor paths:** `docs/audits/ui-audit/UI-AUDIT-<date>[-prod].{md,html}` + `docs/audits/ui-audit/assets/*.png`.
 
@@ -180,7 +180,7 @@ Structure:
    ```
 7. **Positive observations**
 8. **Remediation roadmap**
-9. **Handoff to /ux-audit** — token/a11y/copy one-liners
+9. **Handoffs** — token/copy → `/ux-audit`; deep accessibility → `/a11y-audit` (one line each)
 10. **Appendix** — bootstrap log, STOP & ASK, capture limitations, `suspected` items
 
 **Then generate HTML** via `build-html-reports.mjs` (see Shared deliverables).

package/templates/agents/ux-auditor.md

@@ -40,10 +40,14 @@ docs/audits/
 │   ├── UX-AUDIT-<date>[-prod].md
 │   ├── UX-AUDIT-<date>[-prod].html
 │   └── assets/*.png
-└── ui-audit/
-    ├── UI-AUDIT-<date>[-prod].md
-    ├── UI-AUDIT-<date>[-prod].html
-    └── assets/*.png
+├── ui-audit/
+│   ├── UI-AUDIT-<date>[-prod].md
+│   ├── UI-AUDIT-<date>[-prod].html
+│   └── assets/*.png
+└── a11y-audit/
+    ├── A11Y-AUDIT-<date>[-prod].{md,html,json}
+    ├── assets/*.png
+    └── axe-results/*.json
 ```
 
 **ux-auditor** writes to `docs/audits/ux-audit/` (or user path). Use relative image paths in MD/HTML: `assets/dashboard-teams-1440w.png` — not `../prod-assets/`, not `data:image/...`.
@@ -129,8 +133,8 @@ This package ships the agent/command definitions in `.claude/`. Refresh them on
      ```
      (postinstall runs `npx` automatically; if not, run `npx @appfire-ux/audit-agent` explicitly). Note the fresh install in the appendix.
 2. Verify post-conditions — these MUST exist before continuing:
-   - `.claude/agents/ux-auditor.md`, `.claude/agents/ui-auditor.md`
-   - `.claude/commands/ux-audit.md`, `.claude/commands/ui-audit.md`, `.claude/commands/full-audit.md`
+   - `.claude/agents/ux-auditor.md`, `.claude/agents/ui-auditor.md`, `.claude/agents/a11y-auditor.md`
+   - `.claude/commands/ux-audit.md`, `.claude/commands/ui-audit.md`, `.claude/commands/a11y-audit.md`, `.claude/commands/full-audit.md`
 3. Failure handling: npm fails but older `.claude/` files exist → proceed and flag **"audit-agent possibly stale"**. npm fails and no agent files → STOP and report the npm error.
 
 ### 0b — Bootstrap @appfire-ux/guidelines
@@ -187,7 +191,7 @@ Run each pass over the scoped source. For each pass: start with the greps below
 - Typography via system styles/tokens, not ad-hoc `font-size`/`font-weight`; heading hierarchy sane (one h1, no skipped levels).
 - Shadows/z-index vs elevation tokens; border and radius token usage.
 
-**C. Accessibility** (`accessibility.md`, `accessibility-review` skill checklist)
+**C. Accessibility** (`accessibility.md`, `accessibility-review` skill checklist) — guideline-level pass only; for the deep WCAG 2.2 / VPAT-grade audit with axe-core scanning, hand off to the `a11y-auditor` agent (`/a11y-audit`)
 - Contrast ≥ 4.5:1 (<24px) / 3:1 (≥24px & UI graphics) — flag suspicious token misuse or raw colors; verify at runtime in Phase 4 where possible.
 - Color never the sole carrier of meaning; semantic HTML (`header/nav/main/section`, real `<button>`/`<a>` — grep `onClick` on `div|span`, `role="button"`); keyboard reachability & visible focus (`outline: none` without replacement, `tabIndex={-1}` on interactive elements, positive tabIndex); labels (`aria-label`, `htmlFor`, unlabeled icon buttons); `alt` texts; `prefers-reduced-motion` respected for animations; focus management in modals/toasts; live regions for async status.
 

package/templates/commands/a11y-audit.md

@@ -0,0 +1,22 @@
+---
+description: Comprehensive accessibility audit (WCAG 2.2 A/AA, axe-core scan) feeding the Appfire VPAT/ACR process
+argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>] [--prod] [--routes /,/foo]
+---
+
+Use the **a11y-auditor** agent to run a full accessibility & VPAT-readiness audit of this repository.
+
+Arguments passed by the user: `$ARGUMENTS`
+
+Interpretation:
+- A path argument limits the audit scope (default: whole repo, baseline key screens prioritized).
+- `--static-only` — skip Phase 3 (axe scan + capture); warn the user: without runtime scanning most criteria become NEEDS_MANUAL_REVIEW and the report is much weaker as VPAT evidence.
+- `--lang pl` — report in Polish (default: English). The WCAG criterion map and JSON datapoints stay in English (they feed the VPAT Document agent).
+- `--out <path>` — report MD path (default: `docs/audits/a11y-audit/A11Y-AUDIT-<date>[-prod].md`).
+- `--prod` — append `-prod` to filenames (auditing production/staging URL).
+- `--routes` — explicit route list for the axe scan (default: from the surface map).
+
+Deliverables: **MD + HTML + JSON datapoints + axe-results/*.json + PNG in `assets/`** (Confluence-ready). STOP & ASK on auth/login walls before faking runtime evidence. Generate HTML via `build-html-reports.mjs` after the MD report.
+
+Launch the agent with these parameters and let it follow its full methodology: Phase 0 toolchain refresh (audit-agent, guidelines, playwright + axe-core), early axe-core scan, static four-principles audit, VPAT readiness assessment, and Phase 7 self-verification with strict no-over-claiming language.
+
+When it finishes, relay: MD + HTML + JSON paths, Baseline Accessibility Score, finding counts by severity (BLOCKER/MAJOR/MINOR/INFO), top 3 blockers, safe conclusion, scan coverage, Limitations — and remind the user that the `.json` + report feed the "AI Agent: VPAT Document" (Confluence, CRUX space) to draft the ACR.

package/templates/commands/full-audit.md

@@ -1,17 +1,18 @@
 ---
-description: Run ux-auditor and ui-auditor in parallel — full guideline compliance + UI/usability audit
-argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out-dir <path>] [--prod]
+description: Run ux-auditor, ui-auditor and a11y-auditor in parallel — guideline compliance + UI/usability + accessibility/VPAT audit
+argument-hint: [scope-path] [--agents ux,ui,a11y] [--static-only] [--lang pl|en] [--out-dir <path>] [--prod]
 ---
 
-Run **both** audit agents on this repository **in parallel**: **ux-auditor** (guideline compliance) and **ui-auditor** (UI & usability).
+Run **all three** audit agents on this repository **in parallel**: **ux-auditor** (guideline compliance), **ui-auditor** (UI & usability) and **a11y-auditor** (accessibility / VPAT readiness).
 
 Arguments passed by the user: `$ARGUMENTS`
 
 ## Parse arguments
 
 - **Scope path** — optional directory (default: whole repo).
-- `--static-only` — skip runtime/screenshots for both agents; warn the user that the UI audit will be much weaker.
-- `--lang pl|en` — report language for both agents (default: English).
+- `--agents ux,ui,a11y` — subset of agents to run (default: all three).
+- `--static-only` — skip runtime/screenshots/scans for all agents; warn the user that the UI audit will be much weaker and most a11y criteria become NEEDS_MANUAL_REVIEW.
+- `--lang pl|en` — report language for all agents (default: English; a11y JSON/criterion map stays English).
 - `--out-dir <path>` — parent folder for outputs (default: `docs/audits`).
 - `--prod` — append `-prod` to report filenames (auditing production/staging URL).
 
@@ -23,15 +24,19 @@ Date slug: `YYYY-MM-DD` + optional `-prod` suffix.
 <out-dir>/
 ├── AUDIT-SUMMARY-<date>[-prod].md
 ├── AUDIT-SUMMARY-<date>[-prod].html
-├── prod-assets/              # only when both agents share the same PNG captures
+├── prod-assets/              # only when orchestrator shares PNG captures across agents
 ├── ux-audit/
 │   ├── UX-AUDIT-<date>[-prod].md
 │   ├── UX-AUDIT-<date>[-prod].html
 │   └── assets/*.png
-└── ui-audit/
-    ├── UI-AUDIT-<date>[-prod].md
-    ├── UI-AUDIT-<date>[-prod].html
-    └── assets/*.png
+├── ui-audit/
+│   ├── UI-AUDIT-<date>[-prod].md
+│   ├── UI-AUDIT-<date>[-prod].html
+│   └── assets/*.png
+└── a11y-audit/
+    ├── A11Y-AUDIT-<date>[-prod].{md,html,json}
+    ├── assets/*.png
+    └── axe-results/*.json
 ```
 
 Relative image paths in MD/HTML: `assets/<file>.png` — never base64, never `../prod-assets/`.
@@ -42,9 +47,10 @@ Relative image paths in MD/HTML: `assets/<file>.png` — never base64, never `..
 |-------|------|----------------|
 | **ux-auditor** | Guideline compliance: tokens, a11y, copy, messaging, personas | STOP & ASK, MD+HTML+PNG, Definition of done |
 | **ui-auditor** | IA, consistency, layout, interaction, responsiveness | STOP & ASK, MD+HTML+PNG, Definition of done |
+| **a11y-auditor** | Deep accessibility: WCAG 2.2 A/AA, axe-core scan, VPAT/ACR datapoints | STOP & ASK, MD+HTML+PNG+JSON, no over-claiming |
 
-- Each agent writes to its own `ux-audit/` or `ui-audit/` subfolder with its own `assets/`.
-- Use `prod-assets/` **only** when orchestrator captures once and both agents reuse identical PNGs — then each agent copies into local `assets/` for Confluence-relative paths.
+- Each agent writes to its own `ux-audit/`, `ui-audit/` or `a11y-audit/` subfolder with its own `assets/`.
+- Use `prod-assets/` **only** when orchestrator captures once and agents reuse identical PNGs — each agent copies into local `assets/` for Confluence-relative paths.
 - Do **not** duplicate capture work unless one agent needs extra viewports/states the other missed.
 
 ## Step 1 — Shared setup (once, before agents)
@@ -54,14 +60,15 @@ Do this in the main session — **do not** delegate yet:
 1. **Refresh audit toolchain (Phase 0):**
    - **0a** — `@appfire-ux/audit-agent@latest` + `npx @appfire-ux/audit-agent`
    - **0b** — `@appfire-ux/guidelines@latest` + `npx @appfire-ux/guidelines`
+   - **0c** (when a11y-auditor runs) — `npm ls playwright axe-core --depth=0 || npm install -D playwright axe-core`; `npx playwright install chromium`
    - Record versions for the summary appendix.
 2. **Resolve base URL** — do not assume localhost. If blind-alley signals (OAuth redirect, auth wall, wrong UI) → **STOP & ASK** user with the template from ux-auditor before launching agents.
-3. Unless `--static-only`: start **one** dev server OR use user-provided logged-in URL. Note base URL for both agents.
+3. Unless `--static-only`: start **one** dev server OR use user-provided logged-in URL. Note base URL for all agents.
 4. Optional shared capture: if Browser MCP or Playwright script runs here, save to `<out-dir>/prod-assets/` and tell agents to copy into their `assets/` folders.
 
 ## Step 2 — Launch agents in parallel
 
-Spawn **ux-auditor** and **ui-auditor** **concurrently**.
+Spawn **ux-auditor**, **ui-auditor** and **a11y-auditor** **concurrently** (honor `--agents`).
 
 ```
 Phase 0 COMPLETE. Orchestrator context:
@@ -72,6 +79,7 @@ Phase 0 COMPLETE. Orchestrator context:
 - Language: …
 - ux report: <out-dir>/ux-audit/UX-AUDIT-<date>[-prod].md
 - ui report: <out-dir>/ui-audit/UI-AUDIT-<date>[-prod].md
+- a11y report: <out-dir>/a11y-audit/A11Y-AUDIT-<date>[-prod].md (+ .json datapoints, axe-results/)
 - Shared prod-assets: [path or none — copy to local assets/ if used]
 - STOP & ASK already resolved: [yes/no — what user provided]
 
@@ -81,17 +89,17 @@ Follow Shared deliverables: MD+HTML+PNG, Definition of done.
 If STOP & ASK triggers mid-run, pause and ask user — do not fake verified-runtime.
 ```
 
-## Step 3 — Combined summary + HTML (after both finish)
+## Step 3 — Combined summary + HTML (after all agents finish)
 
 1. Write `<out-dir>/AUDIT-SUMMARY-<date>[-prod].md`:
-   - Executive overview (both lenses)
-   - Links to both MD reports
+   - Executive overview (all lenses)
+   - Links to all MD reports
    - Combined scorecard + severity totals
    - Top 5 cross-cutting issues (deduplicated)
    - Merged handoffs
    - Shared Limitations (URL, viewports, roles, capture gaps)
    - Suggested remediation order
-2. Generate HTML for **all three** reports:
+2. Generate HTML for **all** reports:
    ```bash
    node node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs --dir <out-dir>
    ```
@@ -100,4 +108,4 @@ If STOP & ASK triggers mid-run, pause and ask user — do not fake verified-runt
 
 ## Relay to the user
 
-MD + HTML paths (all three), combined severity counts, top 3 issues, capture coverage, Limitations, local preview URLs, whether parallel run and STOP & ASK occurred.
+MD + HTML paths (all reports), combined severity counts, Baseline Accessibility Score + safe conclusion (a11y), top 3 issues, capture coverage, Limitations, local preview URLs, whether parallel run and STOP & ASK occurred. Remind the user the a11y `.json` feeds "AI Agent: VPAT Document" (Confluence, CRUX) for the ACR draft.