git:20260323.5adb40d to git:20260328.e3296c3

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

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

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

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

Enable with: `github.copilot.chat.agentDebugLog.enabled` and `github.copilot.chat.agentDebugLog.fileLogging.enabled`

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

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