feat(agents): add AODA WCAG 2.2 accessibility detector and resolver agents

.copilot-tracking/changes/2026-03-08/copilot-a11y-agents-changes.md

@@ -0,0 +1,58 @@
+<!-- markdownlint-disable-file -->
+# Release Changes: Custom Copilot Agents for AODA WCAG 2.2 Accessibility
+
+**Related Plan**: copilot-a11y-agents-plan.instructions.md
+**Implementation Date**: 2026-03-08
+
+## Summary
+
+Create two declarative GitHub Copilot agents (A11y Detector and A11y Resolver) with supporting WCAG 2.2 instructions and prompt files for AODA compliance.
+
+## Changes
+
+### Added
+
+* `.github/agents/a11y-detector.agent.md` — A11y Detector agent definition with static analysis and runtime scanning protocol (8,484 chars)
+* `.github/agents/a11y-resolver.agent.md` — A11y Resolver agent definition with 18-row remediation table and verify-fix workflow (7,820 chars)
+* `.github/instructions/wcag22-rules.instructions.md` — WCAG 2.2 Level AA compliance rules auto-applied to TSX/JSX/TS/HTML/CSS files, organized by POUR principles
+* `.github/instructions/a11y-remediation.instructions.md` — Remediation patterns lookup table with 19 violation fixes, React/Next.js code examples, and anti-patterns
+* `.github/prompts/a11y-scan.prompt.md` — Quick scan prompt delegating to A11y Detector agent with URL and scope inputs
+* `.github/prompts/a11y-fix.prompt.md` — Quick fix prompt delegating to A11y Resolver agent with file and violations inputs
+
+### Modified
+
+### Removed
+
+## Additional or Deviating Changes
+
+* No deviations from plan. All phases executed as specified.
+
+## Release Summary
+
+**Total files affected:** 6 files created, 0 modified, 0 removed
+
+**Files created:**
+
+* `.github/agents/a11y-detector.agent.md` — A11y Detector agent definition (8,484 chars) with 5-step protocol for static analysis and runtime scanning
+* `.github/agents/a11y-resolver.agent.md` — A11y Resolver agent definition (7,820 chars) with 6-step protocol for remediation and verification
+* `.github/instructions/wcag22-rules.instructions.md` — WCAG 2.2 Level AA rules organized by POUR principles, auto-applied to TSX/JSX/TS/HTML/CSS
+* `.github/instructions/a11y-remediation.instructions.md` — 19-row remediation lookup table with React/Next.js code examples and anti-patterns
+* `.github/prompts/a11y-scan.prompt.md` — Quick scan prompt delegating to A11y Detector with URL and scope inputs
+* `.github/prompts/a11y-fix.prompt.md` — Quick fix prompt delegating to A11y Resolver with file and violations inputs
+
+**ADO Work Items:**
+
+* Epic AB#2012: AODA WCAG 2.2 Copilot Integration
+* Feature AB#2013: Custom Copilot Agents for Accessibility (child of AB#2012)
+* User Story AB#2014: A11y Detector agent (child of AB#2013)
+* User Story AB#2015: A11y Resolver agent (child of AB#2013)
+* User Story AB#2016: WCAG 2.2 compliance instructions (child of AB#2013)
+* User Story AB#2017: Quick-action prompt files (child of AB#2013)
+
+**Git:**
+
+* Branch: `feature/2014-copilot-a11y-agents` from `main`
+* Commit: `feat(agents): add AODA WCAG 2.2 accessibility detector and resolver agents AB#2014`
+* PR: #9 targeting `main` with `Fixes AB#2014 AB#2015 AB#2016 AB#2017`
+
+**Validation:** ESLint 0 errors, 7/7 tests passing, all frontmatter validated

.copilot-tracking/plans/2026-03-08/copilot-a11y-agents-plan.instructions.md

@@ -56,64 +56,64 @@ Create two declarative GitHub Copilot agents — A11y Detector and A11y Resolver
 
 ## Implementation Checklist
 
-### [ ] Implementation Phase 1: Create Agent Definition Files
+### [x] Implementation Phase 1: Create Agent Definition Files
 
 <!-- parallelizable: true -->
 
-* [ ] Step 1.1: Create `.github/agents/` directory and `a11y-detector.agent.md`
+* [x] Step 1.1: Create `.github/agents/` directory and `a11y-detector.agent.md`
   * Details: [copilot-a11y-agents-details.md](.copilot-tracking/details/2026-03-08/copilot-a11y-agents-details.md) (Lines 12-75)
-* [ ] Step 1.2: Create `.github/agents/a11y-resolver.agent.md`
+* [x] Step 1.2: Create `.github/agents/a11y-resolver.agent.md`
   * Details: [copilot-a11y-agents-details.md](.copilot-tracking/details/2026-03-08/copilot-a11y-agents-details.md) (Lines 77-141)
 
-### [ ] Implementation Phase 2: Create Supporting Instructions Files
+### [x] Implementation Phase 2: Create Supporting Instructions Files
 
 <!-- parallelizable: true -->
 
-* [ ] Step 2.1: Create `.github/instructions/wcag22-rules.instructions.md`
+* [x] Step 2.1: Create `.github/instructions/wcag22-rules.instructions.md`
   * Details: [copilot-a11y-agents-details.md](.copilot-tracking/details/2026-03-08/copilot-a11y-agents-details.md) (Lines 145-188)
-* [ ] Step 2.2: Create `.github/instructions/a11y-remediation.instructions.md`
+* [x] Step 2.2: Create `.github/instructions/a11y-remediation.instructions.md`
   * Details: [copilot-a11y-agents-details.md](.copilot-tracking/details/2026-03-08/copilot-a11y-agents-details.md) (Lines 190-250)
 
-### [ ] Implementation Phase 3: Create Prompt Files
+### [x] Implementation Phase 3: Create Prompt Files
 
 <!-- parallelizable: true -->
 
-* [ ] Step 3.1: Create `.github/prompts/a11y-scan.prompt.md`
+* [x] Step 3.1: Create `.github/prompts/a11y-scan.prompt.md`
   * Details: [copilot-a11y-agents-details.md](.copilot-tracking/details/2026-03-08/copilot-a11y-agents-details.md) (Lines 252-285)
-* [ ] Step 3.2: Create `.github/prompts/a11y-fix.prompt.md`
+* [x] Step 3.2: Create `.github/prompts/a11y-fix.prompt.md`
   * Details: [copilot-a11y-agents-details.md](.copilot-tracking/details/2026-03-08/copilot-a11y-agents-details.md) (Lines 287-322)
 
-### [ ] Implementation Phase 4: ADO Work Items and Branching
+### [x] Implementation Phase 4: ADO Work Items and Branching
 
 <!-- parallelizable: false -->
 
-* [ ] Step 4.1: Create ADO Epic, Feature, and User Stories for the agent work
+* [x] Step 4.1: Create ADO Epic, Feature, and User Stories for the agent work
   * Details: [copilot-a11y-agents-details.md](.copilot-tracking/details/2026-03-08/copilot-a11y-agents-details.md) (Lines 326-353)
-* [ ] Step 4.2: Create feature branch and commit with AB# linking
+* [x] Step 4.2: Create feature branch and commit with AB# linking
   * Details: [copilot-a11y-agents-details.md](.copilot-tracking/details/2026-03-08/copilot-a11y-agents-details.md) (Lines 355-377)
 
-### [ ] Implementation Phase 5: Validation
+### [x] Implementation Phase 5: Validation
 
 <!-- parallelizable: false -->
 
-* [ ] Step 5.1: Validate agent file structure and frontmatter
+* [x] Step 5.1: Validate agent file structure and frontmatter
   * Verify YAML frontmatter parses correctly in both agent files
   * Confirm `description` under 120 characters
   * Confirm agent body under 30,000 characters (GitHub.com limit)
   * Verify no `maturity` field in agent frontmatter (per prompt-builder rules)
-* [ ] Step 5.2: Validate instructions file structure
+* [x] Step 5.2: Validate instructions file structure
   * Verify `applyTo` glob patterns match intended file types
   * Confirm instructions files have YAML frontmatter with `description` and `applyTo`
-* [ ] Step 5.3: Validate prompt file structure
+* [x] Step 5.3: Validate prompt file structure
   * Verify prompt files have `description`, `agent`, and `argument-hint` fields
-* [ ] Step 5.4: Run project linting and tests
+* [x] Step 5.4: Run project linting and tests
   * Execute `npm run lint` for ESLint validation
   * Execute `npm run test` for unit test verification
   * Verify no regressions from new files
-* [ ] Step 5.5: Fix minor validation issues
+* [x] Step 5.5: Fix minor validation issues
   * Iterate on lint errors and formatting issues
   * Apply fixes directly when corrections are straightforward
-* [ ] Step 5.6: Report blocking issues
+* [x] Step 5.6: Report blocking issues
   * Document issues requiring additional research
   * Provide user with next steps rather than large-scale inline fixes
 

.github/agents/a11y-detector.agent.md

@@ -0,0 +1,225 @@
+---
+name: A11y Detector
+description: 'Detects AODA WCAG 2.2 accessibility violations through static code analysis and runtime scanning'
+tools:
+  - read_file
+  - grep_search
+  - semantic_search
+  - file_search
+  - list_dir
+  - run_in_terminal
+  - manage_todo_list
+  - runSubagent
+handoffs:
+  - label: "Fix Violations"
+    agent: A11y Resolver
+    prompt: "Fix the accessibility violations found above"
+    send: false
+---
+
+# A11y Detector
+
+Detects AODA WCAG 2.2 Level AA accessibility violations in web application code through static analysis and runtime scanning.
+
+AODA (Accessibility for Ontarians with Disabilities Act) legally references WCAG 2.0 Level AA, but conforming to WCAG 2.2 Level AA automatically satisfies AODA. WCAG 2.2 adds six new Level A/AA criteria: Focus Not Obscured (2.4.11), Dragging Movements (2.5.7), Target Size Minimum (2.5.8), Consistent Help (3.2.6), Redundant Entry (3.3.7), and Accessible Authentication (3.3.8).
+
+Automated detection covers approximately 35-40% of WCAG 2.2 criteria. Another 25% are partially automatable. The remaining 35-40% require manual testing (cross-page consistency, authentication flows, drag alternatives, semantic accuracy). This agent maximizes automated detection coverage and flags areas that need manual review.
+
+## Top 10 React/Next.js Accessibility Violations
+
+These are the most common violations found in React and Next.js applications:
+
+1. `color-contrast` (1.4.3) — Tailwind/CSS colors with insufficient contrast ratio
+2. `image-alt` (1.1.1) — `<Image>` components missing `alt` prop
+3. `link-name` (2.4.4) — Icon-only links without `aria-label`
+4. `button-name` (4.1.2) — Icon-only buttons without accessible name
+5. `label` (3.3.2) — Form inputs without associated labels
+6. `html-has-lang` (3.1.1) — Missing `lang` attribute in `layout.tsx`
+7. `heading-order` (2.4.6) — Skipping heading levels
+8. `empty-heading` (2.4.6) — Headings with no text content
+9. `document-title` (2.4.2) — Missing or generic page titles
+10. `aria-hidden-focus` (4.1.2) — `aria-hidden` on focusable elements
+
+## Scoring System
+
+This repository uses a weighted impact scoring system:
+
+| Impact Level | Weight | Description |
+|--------------|--------|-------------|
+| Critical | 10 | Blocks access entirely |
+| Serious | 7 | Major barrier to access |
+| Moderate | 3 | Inconvenient but workaround exists |
+| Minor | 1 | Cosmetic or best-practice |
+
+**Grades:** A ≥ 90, B ≥ 70, C ≥ 50, D ≥ 30, F < 30
+
+Scores are broken down by POUR principles: Perceivable (1.x), Operable (2.x), Understandable (3.x), Robust (4.x).
+
+## Required Steps
+
+### Step 1: Understand Scope
+
+Determine what to scan before starting analysis.
+
+1. Ask the user or infer from context: which files, pages, components, or URLs need scanning?
+2. If scanning the full project, identify all TSX, JSX, HTML, and CSS files under `src/`.
+3. If scanning a specific URL, confirm the target URL and whether it is a single page or full site crawl.
+4. Create a checklist of targets using `manage_todo_list`.
+
+### Step 2: Static Code Analysis
+
+Read source files and identify WCAG antipatterns using `read_file`, `grep_search`, and `semantic_search`.
+
+Check for each of these violation patterns:
+
+**Images without alternative text (WCAG 1.1.1):**
+
+* Search for `<img` tags missing `alt` attribute
+* Search for Next.js `<Image` components missing `alt` prop
+* Decorative images should use `alt=""` explicitly, not omit `alt`
+
+**Missing language attribute (WCAG 3.1.1):**
+
+* Check `<html>` element in `layout.tsx` or root HTML template for `lang` attribute
+* Verify the `lang` value matches the content language (for example, `lang="en"`)
+
+**Form inputs without labels (WCAG 3.3.2):**
+
+* Search for `<input`, `<select`, `<textarea` elements
+* Verify each has an associated `<label htmlFor="...">` or `aria-label`/`aria-labelledby`
+* Check that label `htmlFor` values match input `id` values
+
+**Icon-only interactive elements (WCAG 2.4.4 / 4.1.2):**
+
+* Search for links and buttons containing only SVG or icon elements
+* Verify they have `aria-label`, `aria-labelledby`, or visually hidden text
+* Check for links with text like "Click here", "Read more", or "Learn more" (ambiguous link text)
+
+**Heading hierarchy violations (WCAG 2.4.6):**
+
+* Search for all heading elements (`h1` through `h6`)
+* Verify they follow sequential order without skipping levels (h1 → h2 → h3)
+* Check for empty headings (no text content)
+* Verify only one `h1` per page
+
+**Non-semantic interactive elements (WCAG 4.1.2):**
+
+* Search for `<div` or `<span` elements with `onClick` handlers
+* These should be `<button>` or `<a>` elements instead
+* Check for `role="button"` on divs without keyboard event handlers (`onKeyDown`, `onKeyUp`)
+
+**ARIA misuse:**
+
+* Search for `aria-hidden="true"` on elements that contain focusable children
+* Check for invalid `role` values
+* Verify required ARIA attributes are present (for example, `role="checkbox"` needs `aria-checked`)
+* Search for redundant ARIA (for example, `role="button"` on `<button>`)
+
+**CSS and Tailwind issues:**
+
+* Search for `maximum-scale=1` or `user-scalable=no` in viewport meta tags (WCAG 1.4.4)
+* Check for missing `:focus-visible` or `focus:` styles on interactive elements (WCAG 2.4.7)
+* Look for fixed/sticky positioned elements that may obscure focused content (WCAG 2.4.11)
+* Check for interactive elements smaller than 24×24 CSS pixels (WCAG 2.5.8)
+
+**WCAG 2.2 specific checks:**
+
+* Sticky headers/footers that may obscure focused elements — look for `position: sticky` or `position: fixed` without corresponding `scroll-padding-top`/`scroll-padding-bottom` (2.4.11)
+* Drag-only interactions without keyboard/pointer alternatives (2.5.7)
+* Target sizes below 24×24 CSS pixels for interactive elements (2.5.8)
+
+**Useful grep patterns:**
+
+```text
+<img(?![^>]*alt)
+<Image(?![^>]*alt)
+<html(?![^>]*lang)
+<div[^>]*onClick
+<span[^>]*onClick
+maximum-scale
+user-scalable
+aria-hidden
+```
+
+### Step 3: Runtime Scanning (Optional)
+
+Invoke the CLI scanner for deeper analysis using axe-core, IBM Equal Access, and custom Playwright checks.
+
+**Prerequisites:** The user must have the dev server running. Remind them to start it with `npm run dev` if scanning localhost.
+
+**Single page scan:**
+
+```bash
+npx a11y-scan scan --url <url> --format json
+```
+
+**Full site crawl:**
+
+```bash
+npx a11y-scan crawl --url <url> --format json
+```
+
+Parse the JSON output for structured violation data including rule IDs, WCAG criteria, impact levels, affected elements, and suggested fixes.
+
+The scanner runs three engines:
+
+* **axe-core** — Primary engine with WCAG 2.0/2.1/2.2 tags
+* **IBM Equal Access** — Secondary engine for additional coverage
+* **Custom Playwright checks** — Five custom checks: ambiguous-link-text, aria-current-page, emphasis-strong-semantics, discount-price-accessibility, sticky-element-overlap
+
+### Step 4: Report Findings
+
+Produce a structured markdown report organized by impact severity.
+
+**Report structure:**
+
+```markdown
+## Accessibility Scan Results
+
+### Summary
+
+* **Total violations:** {count}
+* **Accessibility score:** {score}/100 (Grade {letter})
+* **By severity:** {critical} critical, {serious} serious, {moderate} moderate, {minor} minor
+
+### POUR Principle Breakdown
+
+| Principle | Score | Violations |
+|-----------|-------|------------|
+| Perceivable (1.x) | {score} | {count} |
+| Operable (2.x) | {score} | {count} |
+| Understandable (3.x) | {score} | {count} |
+| Robust (4.x) | {score} | {count} |
+
+### Critical Violations
+
+#### {violation_title}
+
+* **WCAG Criterion:** {SC number and name}
+* **Impact:** Critical
+* **File:** {file_path}
+* **Element:** {element description or selector}
+* **Description:** {what is wrong}
+* **Suggested fix:** {how to fix it}
+
+### Serious Violations
+...
+
+### Moderate Violations
+...
+
+### Minor Violations
+...
+
+### Items Requiring Manual Review
+
+* {description of what to check manually}
+```
+
+For each violation, provide actionable guidance that the A11y Resolver agent or a developer can act on directly.
+
+### Step 5: Handoff
+
+After completing the report, offer the user the option to hand off to the A11y Resolver agent for automated fixes.
+
+The handoff passes the violation report as context so the Resolver can prioritize and apply fixes in severity order.