# Accessibility-First Development

This workspace enforces WCAG AA accessibility standards for all web UI code.

## 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 skills 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 skills are needed. Do not wait for the user to explicitly request accessibility review.

## Available Skills

The following skills are available in `skills/` and provide domain-specific accessibility knowledge:

- **accessibility-lead** - Orchestrator. Decides which specialists to invoke and runs the final review.
- **aria-specialist** - ARIA roles, states, properties, widget patterns. Enforces the first rule of ARIA.
- **modal-specialist** - Dialogs, drawers, popovers, alerts. Focus trapping, focus return, escape behavior.
- **contrast-master** - Color contrast ratios, dark mode, focus indicators, color independence.
- **keyboard-navigator** - Tab order, focus management, skip links, arrow key patterns, SPA route changes.
- **live-region-controller** - Dynamic content announcements, toasts, loading states, search results.
- **forms-specialist** - Labels, errors, validation, fieldsets, autocomplete, multi-step wizards.
- **alt-text-headings** - Alt text, SVGs, icons, heading hierarchy, landmarks, page titles.
- **tables-data-specialist** - Table markup, scope, caption, headers, sortable columns, ARIA grids.
- **link-checker** - Ambiguous link text, "click here" detection, missing new-tab warnings.
- **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 for WCAG compliance.
- **web-accessibility-wizard** - Full guided web accessibility audit with step-by-step walkthrough.
- **document-accessibility-wizard** - Office and PDF document accessibility audit.
- **markdown-a11y-assistant** - Markdown documentation audit covering links, alt text, headings, tables, emoji, diagrams.
- **testing-coach** - Screen reader testing, keyboard testing, automated testing guidance.
- **wcag-guide** - WCAG 2.2 criteria explanations, conformance levels, what changed.
- **word-accessibility** - Microsoft Word (DOCX) document accessibility scanning.
- **excel-accessibility** - Microsoft Excel (XLSX) spreadsheet accessibility scanning.
- **powerpoint-accessibility** - Microsoft PowerPoint (PPTX) presentation accessibility scanning.
- **pdf-accessibility** - PDF conformance per PDF/UA and the Matterhorn Protocol.
- **epub-accessibility** - ePub document accessibility scanning per EPUB Accessibility 1.1.
- **office-remediator** - Programmatic Office document (Word/Excel/PowerPoint) remediation via python-docx, openpyxl, python-pptx.

### GitHub Workflow Skills

- **github-hub** - Routes GitHub management tasks to the right specialist from plain English.
- **daily-briefing** - Morning overview of open issues, PR queue, CI status, security alerts.
- **pr-review** - PR diff analysis with confidence per finding, delta tracking, and inline comments.
- **issue-tracker** - Issue triage with priority scoring, duplicate detection, action inference.
- **analytics** - Repository health scoring (0-100/A-F), velocity metrics, bottleneck detection.
- **insiders-a11y-tracker** - Track accessibility changes in VS Code Insiders and custom repos.
- **repo-admin** - Collaborator management, branch protection rules, access audits.
- **team-manager** - Onboarding, offboarding, org team membership, permission management.
- **contributions-hub** - Discussions, community health metrics, first-time contributor insights.
- **template-builder** - Guided wizard for issue/PR/discussion templates.
- **repo-manager** - Repository scaffolding with labels, CI, CONTRIBUTING, SECURITY, issue templates.
- **projects-manager** - GitHub Projects v2 boards, views, custom fields, and iterations.
- **actions-manager** - GitHub Actions workflow runs, logs, re-runs, and CI debugging.
- **security-dashboard** - Dependabot, code scanning, and secret scanning alert triage.
- **release-manager** - Releases, tags, assets, and release note generation.
- **notifications-manager** - Notification inbox management, filtering, and subscriptions.
- **wiki-manager** - Wiki page creation, editing, search, and organization.

## 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.
- **Mobile app (React Native / Expo / iOS / Android):** Apply cognitive-accessibility guidance. Use mobile-accessibility for touch target checks.
- **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.
- **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.

## 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.
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.
3. **Scan config templates:** If no config file exists, 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) enhances accessibility agent workflows:

- **Monorepo Support:** `chat.useCustomizationsInParentRepositories` discovers agents from parent folders
- **Agent Debugging:** `/troubleshoot`, JSONL export/import, Agent Flow Chart, and Agent Debug Logs support for Copilot CLI and Claude agent sessions
- **MCP Across Agent Types:** VS Code-registered MCP servers now bridge into Copilot CLI and Claude agents
- **Chat Customizations Editor:** `Chat: Open Chat Customizations` centralizes instructions, prompts, agents, skills, MCP servers, and plugins
- **Nested Subagents:** `chat.subagents.allowInvocationsFromSubagents` enables recursive or coordinator-worker flows when deliberately needed
- **Image Analysis:** `chat.imageSupport.enabled` for alt-text-headings to analyze actual images
- **Integrated Browser:** `editor-browser` debug type for zoom/reflow testing (WCAG 1.4.4, 1.4.10), plus local HTTPS with self-signed certificates
- **Permission Levels:** Autopilot (read-only scans), Bypass Approvals (batch scanning), Default (fix-applying)

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

For tasks that do not involve any user-facing web content (backend logic, scripts, database work), these requirements do not apply.
