diff --git a/.copilot-tracking/changes/2026-03-08/copilot-a11y-agents-changes.md b/.copilot-tracking/changes/2026-03-08/copilot-a11y-agents-changes.md new file mode 100644 index 0000000..58cc24b --- /dev/null +++ b/.copilot-tracking/changes/2026-03-08/copilot-a11y-agents-changes.md @@ -0,0 +1,58 @@ + +# 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 diff --git a/.copilot-tracking/plans/2026-03-08/copilot-a11y-agents-plan.instructions.md b/.copilot-tracking/plans/2026-03-08/copilot-a11y-agents-plan.instructions.md index 8c9d799..c2a7d5f 100644 --- a/.copilot-tracking/plans/2026-03-08/copilot-a11y-agents-plan.instructions.md +++ b/.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 -* [ ] 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 -* [ ] 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 -* [ ] 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 -* [ ] 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 -* [ ] 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 diff --git a/.github/agents/a11y-detector.agent.md b/.github/agents/a11y-detector.agent.md new file mode 100644 index 0000000..0ccd0a9 --- /dev/null +++ b/.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) — `` 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 `` 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 `` 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 `` or `` 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 `