git:20260416.676123a to git:20260922.cd88753

1 added, 254 removed. Audit A to B.

- # 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.

+ @AGENTS.md