Skip to content

Commit e12964c

Browse files
emmanuelknafoemmanuelknafo
committed
initial commit
0 parents  commit e12964c

26 files changed

Lines changed: 2965 additions & 0 deletions

‎.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Node
2+
node_modules/
3+
npm-debug.log*
4+
5+
# Jekyll
6+
_site/
7+
.sass-cache/
8+
.jekyll-cache/
9+
.jekyll-metadata
10+
vendor/
11+
12+
# OS
13+
.DS_Store
14+
Thumbs.db
15+
16+
# Editor
17+
.vscode/
18+
.idea/
19+
*.swp
20+
*.swo

‎CONTRIBUTING.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Contributing to Accessibility Scan Workshop
2+
3+
Thank you for contributing to this workshop. Follow these guidelines to maintain
4+
consistency across all labs.
5+
6+
## How to Contribute
7+
8+
1. Fork this repository
9+
2. Create a feature branch: `git checkout -b feature/your-change`
10+
3. Make your changes following the style guide below
11+
4. Test locally with `bundle exec jekyll serve`
12+
5. Submit a pull request
13+
14+
## Lab Authoring Style Guide
15+
16+
### Voice and Tone
17+
18+
- Use second-person voice ("you", "your")
19+
- Use present tense and active voice
20+
- Keep instructions direct and concise
21+
- Avoid jargon without explanation
22+
23+
### Lab Document Structure
24+
25+
Every lab follows this structure:
26+
27+
```markdown
28+
---
29+
permalink: /labs/lab-XX
30+
title: "Lab XX: Title"
31+
description: "Brief description"
32+
---
33+
34+
# Lab XX: Title
35+
36+
| | |
37+
|---|---|
38+
| **Duration** | XX min |
39+
| **Level** | Beginner / Intermediate / Advanced |
40+
| **Prerequisites** | Lab NN |
41+
42+
## Learning Objectives
43+
44+
- Objective 1
45+
- Objective 2
46+
47+
## Exercises
48+
49+
### Exercise X.1: Title
50+
51+
Step-by-step instructions...
52+
53+
## Verification Checkpoint
54+
55+
- [ ] Check 1
56+
- [ ] Check 2
57+
58+
## Next Steps
59+
60+
Proceed to [Lab NN: Title](lab-NN.md).
61+
```
62+
63+
### Code Blocks
64+
65+
- Always specify the language: ````powershell`, ````bash`, ````json`, etc.
66+
- Show expected output in separate blocks when relevant
67+
- Use `> [!NOTE]` for informational callouts
68+
- Use `> [!TIP]` for helpful suggestions
69+
- Use `> [!WARNING]` for caution notices
70+
71+
### Screenshots
72+
73+
- Store in `images/lab-XX/` directories
74+
- Name format: `lab-XX-descriptive-name.png`
75+
- Reference format: `![Alt text](../images/lab-XX/filename.png)`
76+
- Every screenshot directory has a `README.md` inventory
77+
- Alt text must be descriptive for accessibility
78+
79+
### Cross-References
80+
81+
- Use relative links between labs: `[Lab 01](lab-01.md)`
82+
- Use relative links for images: `../images/lab-XX/filename.png`
83+
84+
### Delivery Tier Annotations
85+
86+
Mark exercises that require Azure with:
87+
88+
```markdown
89+
> [!NOTE]
90+
> This exercise requires an Azure subscription (full-day tier only).
91+
```

‎Gemfile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
source 'https://rubygems.org'
2+
gem 'jekyll', '~> 3.10'
3+
gem 'jekyll-theme-minimal'
4+
gem 'jekyll-relative-links'

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 devopsabcs-engineering
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: Accessibility Scan Workshop
3+
description: Hands-on workshop teaching WCAG 2.2 accessibility scanning using axe-core, IBM Equal Access, and custom Playwright checks
4+
ms.date: 2026-03-29
5+
---
6+
7+
# Accessibility Scan Workshop
8+
9+
Hands-on workshop teaching WCAG 2.2 accessibility scanning using axe-core,
10+
IBM Equal Access, and custom Playwright checks. Students learn to detect,
11+
report, and remediate accessibility violations across 5 intentionally
12+
inaccessible demo web applications built in Rust, C#, Java, Python, and Go.
13+
14+
## Architecture
15+
16+
```mermaid
17+
graph LR
18+
subgraph "Demo Apps (5)"
19+
A001["001 Rust<br/>Travel Agency"]
20+
A002["002 C#<br/>E-Commerce"]
21+
A003["003 Java<br/>Learning Platform"]
22+
A004["004 Python<br/>Recipe Sharing"]
23+
A005["005 Go<br/>Fitness Tracker"]
24+
end
25+
26+
subgraph "Scan Engines"
27+
AXE["axe-core"]
28+
IBM["IBM Equal Access"]
29+
CUSTOM["Custom Playwright Checks"]
30+
end
31+
32+
subgraph "Output"
33+
SARIF["SARIF 2.1.0"]
34+
JSON["JSON Reports"]
35+
PDF["PDF Reports"]
36+
end
37+
38+
subgraph "Integration"
39+
GH["GitHub Security Tab"]
40+
ACTIONS["GitHub Actions"]
41+
COPILOT["Copilot Agents"]
42+
end
43+
44+
A001 & A002 & A003 & A004 & A005 --> AXE & IBM & CUSTOM
45+
AXE & IBM & CUSTOM --> SARIF & JSON & PDF
46+
SARIF --> GH
47+
ACTIONS --> AXE & IBM & CUSTOM
48+
COPILOT --> GH
49+
```
50+
51+
## Labs
52+
53+
| Lab | Title | Duration | Level |
54+
| --- | --- | --- | --- |
55+
| 00 | Prerequisites and Environment Setup | 30 min | Beginner |
56+
| 01 | Explore the Demo Apps and WCAG Violations | 25 min | Beginner |
57+
| 02 | axe-core — Automated Accessibility Testing | 35 min | Intermediate |
58+
| 03 | IBM Equal Access — Comprehensive Policy Scanning | 30 min | Intermediate |
59+
| 04 | Custom Playwright Checks — Manual Inspection Automation | 35 min | Intermediate |
60+
| 05 | SARIF Output and GitHub Security Tab | 30 min | Intermediate |
61+
| 06 | GitHub Actions Pipelines and Scan Gates | 40 min | Advanced |
62+
| 07 | Remediation Workflows with Copilot Agents | 45 min | Advanced |
63+
64+
## Lab Dependency Diagram
65+
66+
```mermaid
67+
graph LR
68+
L00[Lab 00: Setup] --> L01[Lab 01: Demo Apps]
69+
L01 --> L02[Lab 02: axe-core]
70+
L01 --> L03[Lab 03: IBM Equal Access]
71+
L01 --> L04[Lab 04: Custom Checks]
72+
L02 --> L05[Lab 05: SARIF]
73+
L03 --> L05
74+
L04 --> L05
75+
L05 --> L06[Lab 06: GitHub Actions]
76+
L06 --> L07[Lab 07: Remediation]
77+
```
78+
79+
Labs 02, 03, and 04 can be completed in any order after Lab 01.
80+
81+
## Delivery Tiers
82+
83+
| Tier | Labs | Duration | Azure Required |
84+
| --- | --- | --- | --- |
85+
| Half-Day | 00, 01, 02, 03, 05 | ~3 hours | No |
86+
| Full-Day | 00–07 (all) | ~6.5 hours | Yes |
87+
88+
## Tool Stack
89+
90+
| Tool | Purpose |
91+
| --- | --- |
92+
| axe-core | WCAG 2.2 automated rule checking |
93+
| IBM Equal Access | Policy-based accessibility scanning |
94+
| Custom Playwright Checks | Manual inspection automation |
95+
| SARIF | Static Analysis Results Interchange Format |
96+
97+
## Prerequisites
98+
99+
- GitHub account with Copilot access
100+
- Node.js 20+
101+
- Docker Desktop
102+
- Azure subscription (full-day tier only)
103+
- PowerShell 7+
104+
- GitHub CLI (`gh`)
105+
- Azure CLI (`az`) (full-day tier only)
106+
107+
## Quick Start
108+
109+
1. Fork and clone `devopsabcs-engineering/accessibility-scan-demo-app`
110+
2. Run `npm install && npx playwright install --with-deps chromium`
111+
3. Start the scanner: `./start-local.ps1`
112+
4. Open [Lab 00](labs/lab-00-setup.md) and begin
113+
114+
## Contributing
115+
116+
See [CONTRIBUTING.md](CONTRIBUTING.md) for lab authoring guidelines.
117+
118+
## License
119+
120+
[MIT](LICENSE)

‎_config.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
title: Accessibility Scan Workshop
2+
description: >-
3+
Learn to scan web applications for WCAG 2.2 accessibility violations
4+
using axe-core, IBM Equal Access, and custom Playwright checks.
5+
theme: jekyll-theme-minimal
6+
plugins:
7+
- jekyll-relative-links

‎_includes/head-custom.html‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<script type="module">
2+
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
3+
mermaid.initialize({ startOnLoad: true });
4+
</script>

‎images/lab-00/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<!-- markdownlint-disable-file -->
2+
# Lab 00: Prerequisites and Environment Setup — Screenshot Inventory
3+
4+
Screenshots referenced by [Lab 00](../../labs/lab-00-setup.md).
5+
6+
| Filename | Description | Method | Phase |
7+
|----------|-------------|--------|-------|
8+
| lab-00-node-version.png | Node.js version output | freeze | 1 |
9+
| lab-00-docker-version.png | Docker version output | freeze | 1 |
10+
| lab-00-gh-version.png | GitHub CLI version output | freeze | 1 |
11+
| lab-00-az-version.png | Azure CLI version output | freeze | 1 |
12+
| lab-00-pwsh-version.png | PowerShell version output | freeze | 1 |
13+
| lab-00-freeze-version.png | Charm freeze version output | freeze | 1 |
14+
| lab-00-scanner-home.png | Scanner home page at localhost:3000 | playwright | 2 |
15+
16+
## Capture Methods
17+
18+
| Method | Tool | Command |
19+
|--------|------|---------|
20+
| freeze | Charm freeze | `freeze --execute "command" --output file.png` |
21+
| freeze-file | Charm freeze | `freeze --output file.png --show-line-numbers path/to/file` |
22+
| playwright | Playwright | `npx playwright screenshot --url URL --output file.png` |
23+
24+
## Phases
25+
26+
| Phase | Environment | Prerequisites |
27+
|-------|------------|---------------|
28+
| 1 | Local only | Tools installed, scanner repo cloned |
29+
| 2 | Azure-deployed | Demo apps running (local or Azure) |
30+
| 3 | GitHub web UI | GitHub authentication, scans uploaded |

‎images/lab-01/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<!-- markdownlint-disable-file -->
2+
# Lab 01: Explore the Demo Apps and WCAG Violations — Screenshot Inventory
3+
4+
Screenshots referenced by [Lab 01](../../labs/lab-01.md).
5+
6+
| Filename | Description | Method | Phase |
7+
|----------|-------------|--------|-------|
8+
| lab-01-demo-app-001.png | Demo app 001 home page (Travel Booking) | playwright | 2 |
9+
| lab-01-demo-app-002.png | Demo app 002 home page (E-Commerce) | playwright | 2 |
10+
| lab-01-demo-app-003.png | Demo app 003 home page (Learning Platform) | playwright | 2 |
11+
| lab-01-violations-popup.png | Popup modal violation in demo app 001 | playwright | 2 |
12+
| lab-01-devtools-audit.png | Chrome DevTools accessibility audit | playwright | 2 |
13+
| lab-01-wcag-mapping.png | WCAG POUR principle mapping | freeze-file | 1 |
14+
15+
## Capture Methods
16+
17+
| Method | Tool | Command |
18+
|--------|------|---------|
19+
| freeze | Charm freeze | `freeze --execute "command" --output file.png` |
20+
| freeze-file | Charm freeze | `freeze --output file.png --show-line-numbers path/to/file` |
21+
| playwright | Playwright | `npx playwright screenshot --url URL --output file.png` |
22+
23+
## Phases
24+
25+
| Phase | Environment | Prerequisites |
26+
|-------|------------|---------------|
27+
| 1 | Local only | Tools installed, scanner repo cloned |
28+
| 2 | Azure-deployed | Demo apps running (local or Azure) |
29+
| 3 | GitHub web UI | GitHub authentication, scans uploaded |

‎images/lab-02/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<!-- markdownlint-disable-file -->
2+
# Lab 02: axe-core — Automated Accessibility Testing — Screenshot Inventory
3+
4+
Screenshots referenced by [Lab 02](../../labs/lab-02.md).
5+
6+
| Filename | Description | Method | Phase |
7+
|----------|-------------|--------|-------|
8+
| lab-02-web-ui-scan.png | Web UI scan in progress | playwright | 2 |
9+
| lab-02-scan-results.png | Scan results overview | playwright | 2 |
10+
| lab-02-violation-detail.png | Violation detail view | playwright | 2 |
11+
| lab-02-cli-output.png | CLI scan output | freeze | 1 |
12+
| lab-02-api-response.png | API response JSON | freeze | 1 |
13+
| lab-02-multi-app-comparison.png | Multi-app scan comparison | playwright | 2 |
14+
15+
## Capture Methods
16+
17+
| Method | Tool | Command |
18+
|--------|------|---------|
19+
| freeze | Charm freeze | `freeze --execute "command" --output file.png` |
20+
| freeze-file | Charm freeze | `freeze --output file.png --show-line-numbers path/to/file` |
21+
| playwright | Playwright | `npx playwright screenshot --url URL --output file.png` |
22+
23+
## Phases
24+
25+
| Phase | Environment | Prerequisites |
26+
|-------|------------|---------------|
27+
| 1 | Local only | Tools installed, scanner repo cloned |
28+
| 2 | Azure-deployed | Demo apps running (local or Azure) |
29+
| 3 | GitHub web UI | GitHub authentication, scans uploaded |

0 commit comments

Comments
 (0)