From 3c2e48b01a30cebb28e87b6931eedb7a525a081b Mon Sep 17 00:00:00 2001 From: Sudeep Ghatak Date: Fri, 12 Jun 2026 13:19:25 +1200 Subject: [PATCH 1/2] Web accessibility audit tool --- docs/README.skills.md | 1 + skills/web-accessibility-audit/SKILL.md | 198 ++++++++++++++++++ .../references/wcag-2.2-checklist.md | 124 +++++++++++ .../scripts/axe-audit.mjs | 134 ++++++++++++ 4 files changed, 457 insertions(+) create mode 100644 skills/web-accessibility-audit/SKILL.md create mode 100644 skills/web-accessibility-audit/references/wcag-2.2-checklist.md create mode 100644 skills/web-accessibility-audit/scripts/axe-audit.mjs diff --git a/docs/README.skills.md b/docs/README.skills.md index d88fd1125..e754c6cc4 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -352,6 +352,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [vardoger-analyze](../skills/vardoger-analyze/SKILL.md)
`gh skills install github/awesome-copilot vardoger-analyze` | Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'. | None | | [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-commands` | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None | | [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-localization` | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None | +| [web-accessibility-audit](../skills/web-accessibility-audit/SKILL.md)
`gh skills install github/awesome-copilot web-accessibility-audit` | Audit web pages and UI components for accessibility against WCAG 2.2 Level AA, then fix the issues at the source-code level. Triggers on requests like "accessibility audit", "is this WCAG compliant", "check a11y", "does this work with a screen reader", "fix color contrast", "keyboard navigation broken", "add ARIA / alt text", or "make this accessible". Combines automated scanning (axe-core, Lighthouse, pa11y) with manual keyboard, focus, semantics, and contrast checks, then produces a prioritized, standards-referenced report. Use this whenever accessibility, a11y, WCAG, Section 508, ADA, ARIA, screen readers, focus management, or inclusive design come up — even if the user does not say the word "audit". | `references/wcag-2.2-checklist.md`
`scripts/axe-audit.mjs` | | [web-coder](../skills/web-coder/SKILL.md)
`gh skills install github/awesome-copilot web-coder` | Expert 10x engineer with comprehensive knowledge of web development, internet protocols, and web standards. Use when working with HTML, CSS, JavaScript, web APIs, HTTP/HTTPS, web security, performance optimization, accessibility, or any web/internet concepts. Specializes in translating web terminology accurately and implementing modern web standards across frontend and backend development. | `references/accessibility.md`
`references/architecture-patterns.md`
`references/browsers-engines.md`
`references/css-styling.md`
`references/data-formats-encoding.md`
`references/development-tools.md`
`references/glossary.md`
`references/html-markup.md`
`references/http-networking.md`
`references/javascript-programming.md`
`references/media-graphics.md`
`references/performance-optimization.md`
`references/security-authentication.md`
`references/servers-infrastructure.md`
`references/web-apis-dom.md`
`references/web-protocols-standards.md` | | [web-design-reviewer](../skills/web-design-reviewer/SKILL.md)
`gh skills install github/awesome-copilot web-design-reviewer` | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` | | [webapp-testing](../skills/webapp-testing/SKILL.md)
`gh skills install github/awesome-copilot webapp-testing` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `assets/test-helper.js` | diff --git a/skills/web-accessibility-audit/SKILL.md b/skills/web-accessibility-audit/SKILL.md new file mode 100644 index 000000000..1002d128b --- /dev/null +++ b/skills/web-accessibility-audit/SKILL.md @@ -0,0 +1,198 @@ +--- +name: web-accessibility-audit +description: 'Audit web pages and UI components for accessibility against WCAG 2.2 Level AA, then fix the issues at the source-code level. Triggers on requests like "accessibility audit", "is this WCAG compliant", "check a11y", "does this work with a screen reader", "fix color contrast", "keyboard navigation broken", "add ARIA / alt text", or "make this accessible". Combines automated scanning (axe-core, Lighthouse, pa11y) with manual keyboard, focus, semantics, and contrast checks, then produces a prioritized, standards-referenced report. Use this whenever accessibility, a11y, WCAG, Section 508, ADA, ARIA, screen readers, focus management, or inclusive design come up — even if the user does not say the word "audit".' +--- + +# Web Accessibility Audit + +This skill audits a web page or component against [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA, explains *why* each finding matters for real users, and remediates issues in the source code rather than papering over them in the rendered DOM. + +Accessibility is not a checkbox exercise. Roughly one in six people live with a disability, and the same fixes that help them — clear focus states, real semantics, sufficient contrast — make the UI faster and more robust for everyone. Automated tools catch only ~30–40% of WCAG issues, so this skill pairs them with the manual checks that find the rest. + +## Scope of Application + +- Static sites (HTML/CSS/JS) +- SPA frameworks: React / Vue / Angular / Svelte +- Full-stack frameworks: Next.js / Nuxt / SvelteKit / Remix +- CMS-rendered pages: WordPress / Drupal / Sitecore +- Design-system and component-library work (audit a single component in isolation) + +## Prerequisites + +| Need | Why | Required? | +|------|-----|-----------| +| Running page **or** component source | Automated scans need a live DOM; remediation needs the source | One of the two | +| Browser automation (Playwright MCP recommended) | Run axe-core in-page, capture focus order, test at multiple viewports | Recommended | +| Node.js | Run the bundled `scripts/axe-audit.mjs` and `npx` tools | For automated scan | +| Access to source code | Fixes are applied at the source, not the rendered output | Required for fixes | + +If nothing is running, you can still do a **static source audit** — read the markup/components and flag issues by inspection — but say so in the report, because automated coverage and contrast/focus checks will be partial. + +## Workflow Overview + +```mermaid +flowchart TD + A[1. Scope & Baseline] --> B[2. Automated Scan] + B --> C[3. Manual Checks] + C --> D[4. Triage by WCAG level + severity] + D --> E[5. Remediate at Source] + E --> F[6. Re-verify] + F --> G{Issues remain?} + G -->|Yes| C + G -->|No| H[Audit Report] +``` + +--- + +## Step 1: Scope & Baseline + +Confirm before scanning — guessing wastes effort: + +- **What** is in scope? A URL, a route, a single component, or the whole site? +- **Conformance target?** Default to **WCAG 2.2 Level AA** (the legal baseline for most of EN 301 549, ADA Title II, and Section 508). Ask if the user needs AAA or a specific standard. +- **Audience constraints?** e.g. "must work with VoiceOver", "keyboard-only users", "must pass our CI axe gate". + +Detect the stack from the workspace so fixes land in the right place: `package.json` (framework + deps), `tailwind.config.*`, `*.module.css`, `styled-components`/`@emotion` usage, `app/` vs `pages/`. + +## Step 2: Automated Scan + +Run automated tools first — they are fast and catch the unambiguous violations, leaving your attention for the judgment calls. + +Use the bundled script, which runs axe-core against a live URL and writes JSON + a readable summary: + +```bash +node scripts/axe-audit.mjs http://localhost:3000 --tags wcag2a,wcag2aa,wcag22aa +``` + +Complementary tools (use what is available): + +| Tool | Best at | Invocation | +|------|---------|------------| +| **axe-core** | Rule-based WCAG violations, low false positives | bundled script / `@axe-core/playwright` | +| **Lighthouse** | Quick a11y score + common issues | `npx lighthouse --only-categories=accessibility` | +| **pa11y** | CI-friendly, HTML CodeSniffer ruleset | `npx pa11y ` | + +If using Playwright MCP directly, inject axe in-page: navigate, then evaluate `axe.run()` and collect `violations`. Capture results per route. + +> Automated tools report *violations* (definite) and *incomplete* (needs a human). Never report "0 issues = accessible" — that only means no machine-detectable issues. Say exactly that. + +## Step 3: Manual Checks + +These find the majority of real barriers and cannot be automated. Walk through each; details and the full success-criterion mapping are in [references/wcag-2.2-checklist.md](references/wcag-2.2-checklist.md). + +### Keyboard & Focus (WCAG 2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11) +- Tab through the entire page using **only** the keyboard. Every interactive element must be reachable and operable. +- Focus order follows visual/reading order; no keyboard traps. +- The focused element is always **visibly** indicated (2.4.7) and not hidden behind sticky headers (2.4.11, new in 2.2). +- Custom widgets (menus, dialogs, comboboxes) implement the expected key interactions (Esc, arrows, Enter/Space). + +### Semantics & Screen Reader (WCAG 1.3.1, 4.1.2, 2.4.6) +- Prefer **native elements** (`