A11y Audit
Run structured accessibility audits with WCAG-oriented issue planning, discovery fixtures, and optional tracker dry-runs before you ship web UI.
Overview
A11y Audit is an agent skill most often used in Ship (also Build frontend, Launch geo) that runs WCAG-oriented accessibility scans and structured issue planning with safe tracker dry-runs.
Install
npx skills add https://github.com/snapsynapse/skill-a11y-audit --skill a11y-auditWhat is this skill?
- a11y-audit bundle v15 with changelog-driven issue planning and markdown+issues dry-run validation
- plan-issues.js dry-run reads project context, severity thresholds, priority, WCAG labels, and duplicate detection
- Discovery path preserves cross-origin sitemap URLs with eval-9 and eval-10 runnable fixtures in-repo
- Issue tracker integration docs include a safe dry-run path aligned to references/issue-trackers.md
- Local scan.js workflow with auto-installed deps/ and standards-aware issue metadata
- Skill bundle version 15 (2026-04-23) with v14 discovery fixtures eval-9 and eval-10
- Runnable eval-2 fixture covers strongest local mitigation for issue mode short of live tracker writes
- plan-issues.js dry-run adds priority, WCAG labels, additional standards, and duplicate marking from existing-key index
Adoption & trust: 1 installs on skills.sh; 2 GitHub stars; 1/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You are about to ship a web UI but lack a repeatable way to turn accessibility scan results into prioritized, de-duplicated WCAG-labeled issues.
Who is it for?
Indie builders shipping customer-facing web apps who want agent-driven a11y workflows with local scripts and eval-backed discovery behavior.
Skip if: Teams that only need a one-click browser extension audit with no scripting, or non-web products with no DOM surface to scan.
When should I use this skill?
You need to audit web accessibility, plan WCAG-prioritized issues, or validate discovery and issue dry-runs before tracker writes.
What do I get? / Deliverables
You get discovery-correct URL coverage, scored findings, and dry-run issue plans you can promote to markdown reports or trackers after review.
- Accessibility scan results with WCAG-oriented labels and priorities
- Dry-run issue plan (markdown + issues) suitable for tracker import after human review
- Discovery output that preserves sitemap URLs for comprehensive page coverage
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Accessibility auditing is a pre-release quality gate—canonical on Ship when you review whether the product meets WCAG expectations. The skill produces prioritized review findings and issue payloads, not net-new feature code—best shelved under review within Ship.
Where it fits
Scan new component routes locally and feed WCAG-labeled fixes back into the UI PR.
Run markdown+issues dry-run to validate severity thresholds before opening blocker a11y tickets.
Execute eval-9/10 discovery fixtures to confirm sitemap sampling survives redirects and cross-origin URLs.
Audit public marketing pages so accessibility gaps do not undermine organic landing experiences.
Attach structured issue exports when users report keyboard or screen-reader failures on production URLs.
How it compares
Executable audit + issue-planning skill bundle—not a design-system component library or a legal compliance certification service.
Common Questions / FAQ
Who is a11y-audit for?
Solo developers and small teams shipping web products who want scripted accessibility discovery, scanning, and WCAG-labeled issue planning from their coding agent.
When should I use a11y-audit?
In Build frontend while fixing components, in Ship review before release, and in Launch geo when public pages must meet accessibility expectations for broader discoverability and trust.
Is a11y-audit safe to install?
Scripts may read your site and filesystem; review the Security Audits panel on this Prism page and prefer dry-run issue modes until you trust tracker credentials and network behavior.
SKILL.md
READMESKILL.md - A11y Audit
# Auto-installed dependencies for scan.js deps/ --- skill_bundle: a11y-audit file_role: reference version: 15 version_date: 2026-04-23 previous_version: 14 change_summary: > Strengthened markdown+issues dry-run validation with context-aware issue planning and a runnable eval-2 fixture. --- # Changelog ## v15 -- 2026-04-23 - Expanded `scripts/plan-issues.js` so the dry-run path now reads project context, applies configured severity thresholds, adds priority and WCAG labels, records additional standards, and marks duplicates from a supplied existing-key index. - Added runnable fixture coverage for `eval-2`, covering the strongest local mitigation path for issue mode short of authenticated live tracker writes. - Updated `references/issue-trackers.md` so the documented safe dry-run path matches the richer helper behavior. ## v14 -- 2026-04-23 - Added `evals/run-discover-fixture.js`, a reusable mocked-network fixture runner for `discover.js`. - Added runnable fixture assets for `eval-9` (cross-origin sitemap preservation) and `eval-10` (deterministic discovery sampling). - Validated both discovery fixtures locally so the two discovery-related regressions now have in-repo reproduction paths, not just notes in `evals/evals.json`. ## v13 -- 2026-04-23 - Discovery now preserves published sitemap URLs instead of rewriting them onto the runtime origin. This includes `robots.txt` sitemap entries, sitemap indexes, nested sitemap URLs, and redirect targets. - Discovery sampling is now deterministic. Candidate selection uses stable spread indexes and fingerprint ranking now breaks ties by URL, eliminating noisy CI diffs across repeated runs. - `discover.js` is importable without changing CLI behavior, which makes mocked-network regression validation possible inside the repo. - `report.js` delta comparison is now page-aware. A rule that moves between pages or template groups with the same instance count is reported as changed rather than unchanged. - Added and validated eval coverage for the resolved issues: `eval-9` (cross-origin sitemap preservation), `eval-10` (deterministic discovery), and `eval-11` (page-aware delta changes). ## v12 -- 2026-03-26 - **Self-contained dependencies:** scan.js now resolves axe-core and puppeteer from skill-local `deps/` → project → global → auto-install. The skill works against any project without requiring accessibility tooling to be pre-installed. - **Quick Fixes:** report.js includes actionable one-liner remediation hints for ~17 common axe rules, sorted by impact severity. - **Delta comparison:** `report.js --previous <prior-audit.json>` shows fixed rules (strikethrough), new rules, changed instance counts with direction arrows, and net totals. - **Null-label fix:** API enrichment labels no longer show "null" when the API manifest lacks count data for an entity type. ## v11 -- 2026-03-26 - **discover.js:** Template-aware page discovery with sitemap-first approach. Falls back to HTML navigation crawl if no sitemap exists. - **DOM fingerprinting:** Loads candidate pages and scores structural complexity (tables, details, forms, interactive attrs). Picks the most and least complex pages per group instead of alphabetic spread. - **API entity enrichment:** Reads `/api/v1/index.json` (or similar) and annotates groups with entity names/counts (e.g., "25 regulations"). - **Shared template detection:** report.js cross-references per-page violation fingerprints with discover groups. Surfaces which template groups share identical issues so developers fix the shared template once. - **No-sitemap fallback validated:** HTML crawl (depth 2) found 132 pages and all key template groups on AI Regulation Reference. - **Validated on AI Regulation Reference:** 746 pages → 16 groups → 22 scanned → 12 serious violations found on templates the previous top-level-only scan missed entirely. ## v10 -- 2026-03-26 - **report.js:** New deterministi