This workspace enforces WCAG AA accessibility standards for all web UI code.
Repository-wide hard rule: do not add emoji characters in generated, edited, or reviewed content.
- Applies to release notes, changelog entries, docs, prompts, instructions, agent files, issue/PR text, and chat-generated copy intended for repository publication.
- Replace emoji with plain text labels.
- If existing content contains emoji and you are touching that content, remove emoji as part of the update.
Accessibility review is enforced by three global hooks, not just instructions:
- Proactive detection (
UserPromptSubmit) — Detects web projects automatically and injects the delegation instruction on every prompt. - Edit gate (
PreToolUse) — Blocks Edit/Write to UI files (.jsx,.tsx,.vue,.css,.html, etc.) until accessibility-lead has been consulted. UsespermissionDecision: "deny". - Session marker (
PostToolUse) — Creates a marker when accessibility-lead completes, unlocking the edit gate.
If the edit gate blocks you, delegate to accessibility-agents:accessibility-lead first. After the review completes, UI file edits are unlocked for the rest of the session.
See docs/hooks-guide.md for the full technical breakdown.
Before writing or modifying any web UI code - including HTML, JSX, CSS, React components, Tailwind classes, web pages, forms, modals, or any user-facing web content - you MUST:
- Consider which accessibility specialist agents are needed for the task
- Apply the relevant specialist knowledge before generating code
- Verify the output against the appropriate checklists
Automatic trigger detection: If a user prompt involves creating, editing, or reviewing any file matching *.html, *.jsx, *.tsx, *.vue, *.svelte, *.astro, or *.css - or if the prompt describes building UI components, pages, forms, or visual elements - treat it as a web UI task and apply the Decision Matrix below to determine which specialists are needed. Do not wait for the user to explicitly request accessibility review.
Invoke these agents from the Claude Code agent picker (type / to browse):
| Agent | When to Use |
|---|---|
| Accessibility Lead | Any UI task - coordinates all specialists and runs final review |
| ARIA Specialist | Interactive components, custom widgets, ARIA usage |
| Modal Specialist | Dialogs, drawers, popovers, overlays |
| Contrast Master | Colors, themes, CSS styling, visual design |
| Keyboard Navigator | Tab order, focus management, keyboard interaction |
| Live Region Controller | Dynamic content updates, toasts, loading states |
| Forms Specialist | Forms, inputs, validation, error handling, multi-step wizards |
| Alt Text & Headings | Images, alt text, SVGs, heading structure, page titles, landmarks |
| Tables Specialist | Data tables, sortable tables, grids, comparison tables, pricing tables |
| Link Checker | Ambiguous link text, "click here"/"read more" detection, link purpose |
| Cognitive Accessibility | WCAG 2.2 cognitive SC, COGA guidance, plain language, authentication UX |
| Mobile Accessibility | React Native, Expo, iOS, Android - touch targets, screen reader compatibility |
| Design System Auditor | Color token contrast, focus ring tokens, spacing tokens, Tailwind/MUI/Chakra/shadcn |
| Web Accessibility Wizard | Full guided web accessibility audit with step-by-step walkthrough |
| Document Accessibility Wizard | Document accessibility audit for .docx, .xlsx, .pptx, .pdf - single files, folders, recursive scanning, delta scanning, severity scoring, remediation tracking, compliance export (VPAT/ACR), CSV export with help links, CI/CD integration |
| Testing Coach | Screen reader testing, keyboard testing, automated testing guidance |
| WCAG Guide | WCAG 2.2 criteria explanations, conformance levels, what changed |
| Developer Hub | Python, wxPython, desktop app development - routes to specialist agents, scaffolds, debugs, reviews, builds |
| Python Specialist | Python debugging, packaging (PyInstaller/Nuitka/cx_Freeze), testing, type checking, async, optimization |
| wxPython Specialist | wxPython GUI - sizer layouts, event handling, AUI, custom controls, threading, desktop accessibility |
| Desktop Accessibility Specialist | Desktop application accessibility - platform APIs (UI Automation, MSAA/IAccessible2, NSAccessibility), accessible control patterns, screen reader Name/Role/Value/State, focus management, high contrast, and custom widget accessibility for Windows and macOS desktop applications |
| Desktop A11y Testing Coach | Desktop accessibility testing - testing with NVDA, JAWS, Narrator, and VoiceOver screen readers, Accessibility Insights for Windows, automated UIA testing, keyboard-only testing flows, high contrast verification, and creating desktop accessibility test plans |
| Accessibility Tool Builder | Building accessibility scanning tools, rule engines, document parsers, report generators, and audit automation. WCAG criterion mapping, severity scoring algorithms, CLI/GUI scanner architecture, and CI/CD integration for accessibility tooling |
| Media Accessibility | Video and audio accessibility - captions, audio descriptions, transcripts, media player controls, WCAG 1.2.x compliance |
| Email Accessibility | HTML email accessibility under email client rendering constraints - table-based layout, inline styles, image fallbacks, screen reader compatibility |
| Data Visualization Accessibility | Chart, graph, and dashboard accessibility - SVG ARIA, data table alternatives, color-safe palettes, keyboard interaction |
| Web Component Specialist | Shadow DOM and custom element accessibility - ElementInternals, cross-shadow ARIA, form-associated custom elements, focus delegation |
| Accessibility Statement Generator | Generates W3C or EU model accessibility statements from audit results - conformance claims, known limitations, feedback mechanism |
| Compliance Mapping | Maps audit results to legal frameworks - Section 508, EN 301 549, EAA, ADA, AODA. VPAT 2.5 generation |
| Office Remediator | Programmatic Office document (Word/Excel/PowerPoint) remediation via python-docx, openpyxl, python-pptx |
| Accessibility Regression Detector | Detects regressions by comparing audit results across commits/branches - score trends, new/fixed/regressed classification |
| Performance Accessibility | Intersection of web performance and accessibility - lazy loading, skeleton screens, CLS, code splitting, progressive enhancement |
Hidden Helper Sub-Agents
These agents are not meant to be invoked directly by users. They are used internally by the document-accessibility-wizard, web-accessibility-wizard, and markdown-a11y-assistant to parallelize scanning and analysis:
| Agent | Purpose |
|---|---|
| document-inventory | File discovery, inventory building, delta detection across folders |
| cross-document-analyzer | Cross-document pattern detection, severity scoring, template analysis |
| cross-page-analyzer | Cross-page web pattern detection, severity scoring, remediation tracking |
| web-issue-fixer | Automated and guided web accessibility fix application |
| office-scan-config | Office scan config management - invoked internally by document-accessibility-wizard Phase 0 |
| pdf-scan-config | PDF scan config management - invoked internally by document-accessibility-wizard Phase 0 |
| markdown-scanner | Per-file markdown scanning across all 9 accessibility domains - invoked in parallel by markdown-a11y-assistant |
| markdown-fixer | Applies approved markdown fixes and presents human-judgment items - invoked by markdown-a11y-assistant |
| markdown-csv-reporter | Exports markdown audit findings to CSV with WCAG help links and markdownlint rule references - invoked by markdown-a11y-assistant |
| web-csv-reporter | Exports web audit findings to CSV with Deque University help links - invoked by web-accessibility-wizard |
| document-csv-reporter | Exports document audit findings to CSV with Microsoft Office and Adobe PDF help links - invoked by document-accessibility-wizard |
| scanner-bridge | Bridges GitHub Accessibility Scanner CI data into the agent ecosystem - invoked by web-accessibility-wizard Phase 0 |
| lighthouse-bridge | Bridges Lighthouse CI accessibility audit data into the agent ecosystem - invoked by web-accessibility-wizard Phase 0 |
| playwright-scanner | Behavioral accessibility scanning via Playwright - keyboard traversal, dynamic state, viewport, contrast, a11y tree |
| playwright-verifier | Post-fix verification via Playwright - confirms fixes work at runtime by re-running targeted scans |
The following knowledge domains are available across agent files. On Copilot these are formalized as reusable skills in .github/skills/; on Claude Code the equivalent knowledge is inlined into each agent's instructions.
| Domain | Coverage |
|---|---|
| Document Scanning | File discovery commands, delta detection, scan configuration profiles |
| Accessibility Rules | Cross-format document accessibility rule reference with WCAG 2.2 mapping (DOCX, XLSX, PPTX, PDF) |
| Report Generation | Audit report formatting, severity scoring formulas (0-100, A-F grades), VPAT/ACR compliance export |
| Web Scanning | Web content discovery, URL crawling, axe-core CLI commands, framework detection |
| Web Severity Scoring | Web severity scoring formulas, confidence levels, remediation tracking |
| Framework Accessibility | Framework-specific accessibility patterns and fix templates (React, Vue, Angular, Svelte, Tailwind) |
| Cognitive Accessibility | WCAG 2.2 cognitive SC reference tables, plain language analysis, COGA guidance, auth pattern detection |
| Mobile Accessibility | React Native prop reference, iOS/Android API quick reference, touch target rules, violation patterns |
| Design System | Color token contrast computation, framework token paths (Tailwind/MUI/Chakra/shadcn), focus ring validation, WCAG 2.4.13 Focus Appearance (AAA) |
| Markdown Accessibility | Ambiguous link/anchor patterns, emoji handling modes (remove/translate), Mermaid and ASCII diagram replacement templates, heading structure, severity scoring |
| Help URL Reference | Deque University help topic URLs, Microsoft Office help URLs, Adobe PDF help URLs, WCAG understanding document URLs, application-specific fix steps |
| GitHub A11y Scanner | GitHub Accessibility Scanner detection, issue parsing, severity mapping, axe-core correlation, Copilot fix tracking |
| Lighthouse Scanner | Lighthouse CI accessibility audit detection, score interpretation, weight-to-severity mapping, score regression tracking |
| Python Development | Python and wxPython development patterns, packaging, testing, wxPython sizers/events/threading, cross-platform paths |
| Media Accessibility | WebVTT/SRT/TTML caption formats, caption quality metrics, audio description requirements, media player ARIA, WCAG 1.2.x mapping |
| Email Accessibility | Email client rendering constraints, table-based layout, bulletproof buttons, dark mode, MJML/Foundation patterns |
| Testing Strategy | Automated vs manual testing coverage, browser+AT compatibility matrix, regression patterns, acceptance criteria templates |
| Legal Compliance Mapping | Section 508, ADA, EN 301 549, EAA, AODA framework mapping, VPAT 2.5 editions, non-WCAG requirements |
| Data Visualization Accessibility | Chart accessibility patterns, SVG ARIA, charting library APIs (Highcharts/Chart.js/D3/Recharts), color-safe palettes |
Team coordination is defined in .claude/agents/AGENTS.md. Nine defined teams:
- Document Accessibility Audit - led by document-accessibility-wizard with format-specific sub-agents
- Web Accessibility Audit - led by accessibility-lead with all web specialist agents
- Full Audit - combined web + document audit workflow
- Mobile Accessibility - led by mobile-accessibility; invoked standalone or as handoff from accessibility-lead
- Design System Accessibility - led by design-system-auditor; validates tokens before UI propagation
- Developer Tools - led by developer-hub; routes to python-specialist, wxpython-specialist, nvda-addon-specialist, desktop-a11y-specialist, desktop-a11y-testing-coach, a11y-tool-builder, text-quality-reviewer for Python, wxPython, NVDA addons, desktop accessibility, and tool building. Cross-team handoffs to web-accessibility-wizard and document-accessibility-wizard.
- New component or page: Always apply aria-specialist + keyboard-navigator + alt-text-headings guidance. Add forms-specialist for any inputs, contrast-master for styling, modal-specialist for overlays, live-region-controller for dynamic updates, tables-data-specialist for any data tables.
- Modifying existing UI: At minimum apply keyboard-navigator (tab order breaks easily). Add others based on what changed.
- Code review/audit: Apply all specialist checklists. Use web-accessibility-wizard for guided web audits.
- Document audit: Use document-accessibility-wizard for Office and PDF accessibility audits. Supports single files, folders, recursive scanning, delta scanning (changed files only), severity scoring, template analysis, remediation tracking across re-scans, compliance format export (VPAT/ACR), CSV export with help links, batch remediation scripts, and CI/CD integration guides.
- Mobile app (React Native / Expo / iOS / Android): Apply cognitive-accessibility guidance. Use mobile-accessibility for touch target checks, accessibilityLabel/Role/State audits, and platform-specific screen reader testing.
- Cognitive / UX clarity / plain language: Use cognitive-accessibility for WCAG 2.2 SC 3.3.7, 3.3.8, 3.3.9, COGA guidance, error message quality, and reading level analysis.
- Design system / tokens: Use design-system-auditor to validate color token pairs, focus ring tokens, spacing tokens, and motion tokens before they propagate to UI.
- Data tables: Always apply tables-data-specialist for any tabular data display.
- Links: Always apply link-checker when pages contain hyperlinks.
- Images or media: Always apply alt-text-headings.
- Testing guidance: Use testing-coach for screen reader testing, keyboard testing, and automated testing setup.
- WCAG questions: Use wcag-guide to understand specific WCAG success criteria and conformance requirements.
- Python development: Use developer-hub for any Python, wxPython, or desktop app task. Routes to python-specialist for language work and wxpython-specialist for GUI work.
- Desktop app packaging: Use python-specialist for PyInstaller, Nuitka, cx_Freeze builds and troubleshooting.
- Desktop accessibility: Use desktop-a11y-specialist for platform API implementation (UIA, MSAA, NSAccessibility), screen reader interaction, focus management, and high contrast support. Use desktop-a11y-testing-coach for screen reader testing walkthroughs and automated UIA tests.
- Building accessibility tools: Use a11y-tool-builder for designing rule engines, document parsers, report generators, severity scoring, and scanner architecture.
When starting any accessibility audit, review, or remediation task, proactively check the workspace for existing context before proceeding:
- Scan configuration files: Check the workspace root for
.a11y-office-config.json,.a11y-pdf-config.json, and.a11y-web-config.json. If any exist, read them to determine which rules are enabled/disabled, severity filters, and custom settings. Apply these configurations to the audit - do not use defaults when a config file exists. - Previous audit reports: Check for existing
ACCESSIBILITY-AUDIT.md,WEB-ACCESSIBILITY-AUDIT.md,DOCUMENT-ACCESSIBILITY-AUDIT.md, andMARKDOWN-ACCESSIBILITY-AUDIT.mdin the workspace root. If found, note the date, overall score, and issue count. Offer comparison/delta mode so the user can track remediation progress. - Scan config templates: If no config file exists and the user is starting a new audit, mention that pre-built profiles (strict, moderate, minimal) are available in the
templates/directory.
VS Code 1.113 (March 2026) builds on the 1.112 platform improvements and adds several capabilities that directly improve accessibility agent workflows:
Enable chat.useCustomizationsInParentRepositories to discover accessibility agents from parent folders up to the repository root. This is essential for monorepo setups where you open a package subfolder rather than the repo root. See docs/advanced/advanced-scanning-patterns.md for details.
/troubleshoot- Type/troubleshootin chat to analyze agent debug logs and debug why instructions/agents aren't loading- Export/Import - Save agent debug sessions as JSONL for offline analysis or team sharing
- Agent Flow Chart - Visualize agent orchestration sequences
- CLI and Claude coverage - Agent Debug Logs now support Copilot CLI and Claude agent sessions in addition to local sessions
Enable with: github.copilot.chat.agentDebugLog.enabled and github.copilot.chat.agentDebugLog.fileLogging.enabled
- MCP support in Copilot CLI and Claude agents - MCP servers registered in VS Code are now bridged into Copilot CLI and Claude agent workflows, including workspace
mcp.jsondefinitions.
Chat: Open Chat Customizations- Centralized UI for managing instructions, prompt files, custom agents, skills, MCP servers, and plugins across agent types.
chat.subagents.allowInvocationsFromSubagents- Enables recursive or coordinator-worker subagent patterns when deliberately needed. Keep it disabled by default unless an orchestration flow is designed for it.
Enable chat.imageSupport.enabled to allow agents to read images natively. This enhances:
- alt-text-headings - Analyze actual images to suggest accurate alt text
- contrast-master - Analyze screenshots for visual contrast issues
The new editor-browser debug type allows debugging web apps without leaving VS Code. Useful for:
- Testing zoom/reflow accessibility (WCAG 1.4.4, 1.4.10)
- Visual debugging of focus management
- Screenshot capture for accessibility analysis
- Local HTTPS testing with self-signed certificates during development
- Sharing a live browser page directly with agents when browser tools are enabled
- Autopilot (
chat.autopilot.enabled) - Fully autonomous operation. Good for read-only accessibility scans. - Bypass Approvals - Auto-approve tools without dialogs. Useful for batch scanning.
- Default - Manual approval. Recommended for fix-applying workflows.
See docs/configuration.md for detailed guidance on when to use each level.
The templates/ directory contains pre-built scan configuration profiles:
- strict - All rules enabled, all severities reported
- moderate - All rules enabled, errors and warnings only
- minimal - Errors only, for quick triage
Copy the appropriate template to your project root:
.a11y-office-config.jsonfor Office document scanning.a11y-pdf-config.jsonfor PDF scanning.a11y-web-config.jsonfor web accessibility scanning
When generating any accessibility audit report (web, document, or markdown), the report MUST include all of these sections to be considered complete:
- Metadata - audit date, tool versions, scope (URLs/files audited), scan configuration used
- Executive summary - overall score (0-100, A-F grade), total issues by severity, pass/fail verdict
- Findings - each issue with: rule ID, WCAG criterion, severity, affected element/location, description, remediation guidance
- Severity breakdown - counts by Critical/Serious/Moderate/Minor
- Remediation priorities - ordered list of what to fix first based on impact and effort
- Next steps - recommended follow-up actions, re-scan timeline
- Delta tracking (when a previous report exists) - Fixed/New/Persistent/Regressed issue counts
Do not consider an audit complete until the report contains all applicable sections. If generating a quick check (not a full audit), state explicitly that it is a triage result, not a complete audit report.
- Semantic HTML before ARIA (
<button>not<div role="button">) - One H1 per page, never skip heading levels
- Every interactive element reachable and operable by keyboard
- Text contrast 4.5:1, UI component contrast 3:1
- No information conveyed by color alone
- Focus managed on route changes, dynamic content, and deletions
- Modals trap focus and return focus on close
- Live regions for all dynamic content updates
Additional guides in docs/:
- cross-platform-handoff.md - Seamless handoff between Claude Code and Copilot agent environments
- advanced-scanning-patterns.md - Background scanning, worktree isolation, and large library strategies
- plugin-packaging.md - Packaging and distributing agents for different environments
- platform-references.md - All external documentation sources used to build this project, with feature-to-source mapping
For tasks that do not involve any user-facing web content (backend logic, scripts, database work), these requirements do not apply.