Skip to content

Commit d9fd30b

Browse files
emmanuelknafoemmanuelknafo
committed
Add accessibility workshop agent, governance instructions, and deployment workflow
1 parent 4511201 commit d9fd30b

6 files changed

Lines changed: 455 additions & 0 deletions

File tree

‎.github/agents/accessibility-workshop-agent.agent.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
name: Accessibility Workshop Agent
3+
description: "Helps students navigate labs, debug scanner issues, explain findings, and troubleshoot tool configurations."
4+
tools:
5+
- terminal
6+
- file_reader
7+
---
8+
9+
## Role
10+
11+
You are an accessibility workshop assistant helping students work through 8 labs
12+
covering axe-core, IBM Equal Access, and custom Playwright checks for WCAG 2.2
13+
accessibility scanning.
14+
15+
## Capabilities
16+
17+
* Guide students through lab exercises step by step
18+
* Debug scanner tool errors and configuration issues
19+
* Explain SARIF output and accessibility governance findings
20+
* Help interpret WCAG 2.2 compliance results
21+
* Assist with GitHub Actions workflow troubleshooting
22+
* Explain remediation strategies for common accessibility violations
23+
24+
## Context
25+
26+
* Labs are in the `labs/` directory (lab-00-setup.md through lab-07.md)
27+
* The accessibility-scan-demo-app repository contains 5 intentionally inaccessible demo web apps
28+
* Demo apps are built in Rust, C#, Java, Python, and Go
29+
* Read `.github/instructions/accessibility-governance.instructions.md` for governance rules

‎.github/instructions/accessibility-governance.instructions.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
description: "WCAG 2.2 accessibility governance rules, compliance standards, and scan conventions for web application accessibility testing."
3+
applyTo: "**/*.html,**/*.tsx,**/*.jsx,**/*.vue,**/*.svelte"
4+
---
5+
6+
# Accessibility Governance Rules
7+
8+
## WCAG 2.2 Conformance Levels
9+
10+
Every scanned web application must meet WCAG 2.2 Level AA conformance. Scan results are categorized by conformance level:
11+
12+
| Level | Requirement | Action |
13+
|-------|-------------|--------|
14+
| A | Minimum accessibility | Must fix immediately |
15+
| AA | Standard conformance target | Must fix before release |
16+
| AAA | Enhanced accessibility | Recommended but not required |
17+
18+
## Core Accessibility Principles (POUR)
19+
20+
All accessibility violations map to one of the four POUR principles:
21+
22+
| Principle | Description | Example Violations |
23+
|-----------|-------------|--------------------|
24+
| Perceivable | Content must be presentable to all users | Missing alt text, low contrast, no captions |
25+
| Operable | UI must be navigable by all users | Keyboard traps, no focus indicators, timing issues |
26+
| Understandable | Content and UI must be comprehensible | Missing form labels, unclear error messages, no language attribute |
27+
| Robust | Content must work with assistive technologies | Invalid ARIA, broken semantics, missing roles |
28+
29+
## Required Scan Coverage
30+
31+
Every demo application must be scanned for the following categories:
32+
33+
| # | Category | Scanner | Rule Examples |
34+
|---|----------|---------|---------------|
35+
| 1 | Color Contrast | axe-core | `color-contrast`, `link-in-text-block` |
36+
| 2 | Image Alternatives | axe-core | `image-alt`, `input-image-alt`, `area-alt` |
37+
| 3 | Form Labels | axe-core, IBM Equal Access | `label`, `select-name`, `input-button-name` |
38+
| 4 | Keyboard Navigation | Custom Playwright | Focus order, keyboard traps, skip links |
39+
| 5 | ARIA Compliance | axe-core, IBM Equal Access | `aria-roles`, `aria-valid-attr`, `aria-required-attr` |
40+
| 6 | Document Structure | IBM Equal Access | Heading hierarchy, landmark regions, page title |
41+
| 7 | Dynamic Content | Custom Playwright | Live regions, status messages, modal focus management |
42+
43+
## Severity Mapping
44+
45+
Accessibility violations map to SARIF severity levels based on user impact:
46+
47+
| Impact Level | SARIF Level | Description | Action |
48+
|--------------|-------------|-------------|--------|
49+
| Critical | `error` | Complete barrier preventing access | Immediate fix required |
50+
| Serious | `error` | Significant difficulty for users | Fix within current sprint |
51+
| Moderate | `warning` | Some difficulty for certain users | Plan remediation |
52+
| Minor | `note` | Cosmetic or best practice issue | Track for review |
53+
54+
## SARIF Integration
55+
56+
Accessibility scan findings use the following SARIF conventions:
57+
58+
- **Category prefix:** `accessibility/`
59+
- **Rule ID prefix:** `A11Y-`
60+
- **Tool names:** `axe-core`, `IBMEqualAccess`, `CustomPlaywrightChecks`
61+
- **Security severity:** Mapped to WCAG conformance level and user impact

‎.github/instructions/ado-workflow.instructions.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
description: "Required workflow for Azure DevOps work item tracking, Git branching, pull requests, and branch cleanup in the AODA WCAG compliance project."
3+
applyTo: "**"
4+
maturity: stable
5+
---
6+
7+
# Azure DevOps Workflow
8+
9+
## ADO Organization and Project
10+
11+
* Organization: `MngEnvMCAP675646`
12+
* Project: `AODA WCAG Compliance`
13+
14+
All work items, boards, and test plans live in this project.
15+
16+
## Work Item Hierarchy
17+
18+
Follow this strict hierarchy for every piece of work:
19+
20+
```text
21+
Epic
22+
└── Feature
23+
├── User Story
24+
└── Bug
25+
```
26+
27+
* Every commit must trace back to a User Story or Bug.
28+
* Every User Story or Bug must belong to a Feature.
29+
* Every Feature must belong to an Epic.
30+
* Create the parent items first if they do not exist before creating child items.
31+
* Every work item (Epic, Feature, User Story, Bug) must include the tag `Agentic AI`.
32+
33+
## Branching Strategy
34+
35+
Create a feature branch for each work item using this naming convention:
36+
37+
```text
38+
feature/{work-item-id}-short-description
39+
```
40+
41+
Examples:
42+
43+
```text
44+
feature/1234-axe-core-config
45+
feature/1235-fix-sarif-output
46+
```
47+
48+
Rules:
49+
50+
* One branch per User Story or Bug.
51+
* Use lowercase and hyphens for the description portion.
52+
* Keep the description concise (three to five words).
53+
* Branch from `main` unless otherwise specified.
54+
55+
## Commit Messages
56+
57+
Include the ADO work item ID in every commit message using the `AB#` linking syntax:
58+
59+
```text
60+
feat: add axe-core scanning configuration AB#1234
61+
fix: correct SARIF severity mapping AB#1235
62+
```
63+
64+
This links commits to ADO work items automatically through GitHub and Azure DevOps integration.
65+
66+
To auto-close a work item when the PR merges, use `Fixes AB#{id}` in the commit message or PR description:
67+
68+
```text
69+
feat: add axe-core scanning configuration Fixes AB#1234
70+
```
71+
72+
## Pull Request Workflow
73+
74+
1. Push the feature branch to the remote.
75+
2. Create a pull request targeting `main`.
76+
3. Reference the work item in the PR description using `Fixes AB#{work-item-id}` to auto-close the work item on merge.
77+
4. Complete code review and obtain required approvals.
78+
5. Merge the PR (squash merge preferred for a clean history).
79+
80+
## Post-Merge Branch Cleanup
81+
82+
After the pull request is merged and closed in GitHub:
83+
84+
1. Switch to `main` locally:
85+
86+
```bash
87+
git checkout main
88+
```
89+
90+
2. Pull the latest changes:
91+
92+
```bash
93+
git pull origin main
94+
```
95+
96+
3. Delete the remote branch:
97+
98+
```bash
99+
git push origin --delete feature/{work-item-id}-short-description
100+
```
101+
102+
4. Delete the local branch:
103+
104+
```bash
105+
git branch -d feature/{work-item-id}-short-description
106+
```
107+
108+
Always delete both the remote and local feature branch after a successful merge. Do not keep stale branches.
109+
110+
## Quick Reference
111+
112+
| Step | Command or Action |
113+
|------|-------------------|
114+
| Create branch | `git checkout -b feature/{id}-description` |
115+
| Commit with link | `git commit -m "feat: description AB#{id}"` |
116+
| Push branch | `git push -u origin feature/{id}-description` |
117+
| Create PR | Target `main`, reference `AB#{id}` |
118+
| After merge: sync | `git checkout main && git pull origin main` |
119+
| After merge: delete remote | `git push origin --delete feature/{id}-description` |
120+
| After merge: delete local | `git branch -d feature/{id}-description` |

‎.github/prompts/accessibility-scan.prompt.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
description: "Run an accessibility scan against the demo web applications and analyze the results."
3+
---
4+
5+
## Run Accessibility Scan
6+
7+
Run the accessibility scanner against the demo app repositories and analyze the findings.
8+
9+
### Steps
10+
11+
1. **Run axe-core** against each demo app:
12+
13+
```bash
14+
npx @axe-core/cli http://localhost:3001 --save reports/axe-results.json
15+
```
16+
17+
Or using Playwright with axe-core:
18+
19+
```bash
20+
npx playwright test --project=axe-scan
21+
```
22+
23+
2. **Run IBM Equal Access** against each demo app:
24+
25+
```bash
26+
npx accessibility-checker http://localhost:3001 --output reports/
27+
```
28+
29+
3. **Run custom Playwright checks** for keyboard navigation and dynamic content:
30+
31+
```bash
32+
npx playwright test --project=custom-checks
33+
```
34+
35+
4. **Convert results to SARIF** for GitHub Security tab integration:
36+
37+
```bash
38+
node src/converters/axe-to-sarif.js reports/axe-results.json reports/axe-results.sarif
39+
node src/converters/ibm-to-sarif.js reports/ibm-results.json reports/ibm-results.sarif
40+
```
41+
42+
5. **Analyze results**: Review the SARIF files in `reports/` and summarize:
43+
- Total findings by tool and severity
44+
- WCAG conformance level breakdown (A, AA, AAA)
45+
- Top accessibility violations with affected user groups
46+
- Recommended remediation priorities

0 commit comments

Comments
 (0)