Embed badge
Show
Style
[](https://versuz.dev/claude-md/community-access-accessibility-agents)A CLAUDE.md is just a markdown file at the root of your repo. Copy the content below into your own project's CLAUDE.md to give your agent the same context.
npx versuz@latest install community-access-accessibility-agents --kind=claude-mdcurl -o CLAUDE.md https://raw.githubusercontent.com/Community-Access/accessibility-agents/HEAD/CLAUDE.md# Accessibility-First Development This workspace enforces WCAG AA accessibility standards for all web UI code. ## Hook-Based Enforcement Accessibility review is enforced by three global hooks, not just instructions: 1. **Proactive detection** (`UserPromptSubmit`) — Detects web projects automatically and injects the delegation instruction on every prompt. 2. **Edit gate** (`PreToolUse`) — Blocks Edit/Write to UI files (`.jsx`, `.tsx`, `.vue`, `.css`, `.html`, etc.) until accessibility-lead has been consulted. Uses `permissionDecision: "deny"`. 3. **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. ## Mandatory Accessibility Check 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: 1. Consider which accessibility specialist agents are needed for the task 2. Apply the relevant specialist knowledge before generating code 3. 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. ## Available Specialist Agents 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 | ## Knowledge Domains 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 | ## Agent Teams 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. ## Decision Matrix - **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. ## Context Discovery When starting any accessibility audit, review, or remediation task, proactively check the workspace for existing context before proceeding: 1. **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. 2. **Previous audit reports:** Check for existing `ACCESSIBILITY-AUDIT.md`, `WEB-ACCESSIBILITY-AUDIT.md`, `DOCUMENT-ACCESSIBILITY-AUDIT.md`, and `MARKDOWN-ACCESSIBILITY-AUDIT.md` in the workspace root. If found, note the date, overall score, and issue count. Offer comparison/delta mode so the user can track remediation progress. 3. **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 Features VS Code 1.113 (March 2026) builds on the 1.112 platform improvements and adds several capabilities that directly improve accessibility agent workflows: ### Monorepo Customization Discovery 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](docs/advanced/advanced-scanning-patterns.md#monorepo-customization-discovery-vs-code-1112) for details. ### Agent Debugging - **`/troubleshoot`** - Type `/troubleshoot` in 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 Across Agent Types - **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.json` definitions. ### Chat Customizations Editor - **`Chat: Open Chat Customizations`** - Centralized UI for managing instructions, prompt files, custom agents, skills, MCP servers, and plugins across agent types. ### Nested Subagents - **`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. ### Image Analysis 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 ### Integrated Browser 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 ### Permission Levels - **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](docs/configuration.md) for detailed guidance on when to use each level. ## Scan Configuration 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.json` for Office document scanning - `.a11y-pdf-config.json` for PDF scanning - `.a11y-web-config.json` for web accessibility scanning ## Audit Report Quality Requirements When generating any accessibility audit report (web, document, or markdown), the report MUST include all of these sections to be considered complete: 1. **Metadata** - audit date, tool versions, scope (URLs/files audited), scan configuration used 2. **Executive summary** - overall score (0-100, A-F grade), total issues by severity, pass/fail verdict 3. **Findings** - each issue with: rule ID, WCAG criterion, severity, affected element/location, description, remediation guidance 4. **Severity breakdown** - counts by Critical/Serious/Moderate/Minor 5. **Remediation priorities** - ordered list of what to fix first based on impact and effort 6. **Next steps** - recommended follow-up actions, re-scan timeline 7. **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. ## Non-Negotiable Standards - 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 ## Advanced Documentation 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.