summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChukwuebuka Ezeokeke <ebulamicheal@gmail.com>2026-10-14 22:13:04 +0000
committerChukwuebuka (Gaus Octavio) <56232734+Chukwuebuka-2003@users.noreply.github.com>2026-11-16 09:56:26 +0000
commit3b79b0ce438e944fab594b143f20f64b6093562d (patch)
treee1fcaddadb80aaaa5d90179f96a05cc5a5ef54f9
parent0094fdbd5ebb15ec9243a94e43e7224edbae52de (diff)
fix(review): address maintainer accessibility feedback
-rw-r--r--README.md2
-rw-r--r--docs/copilot-setup.md1
-rw-r--r--references/accessibility-checklist.md10
-rw-r--r--skills/accessibility-engineering/SKILL.md116
-rwxr-xr-xskills/accessibility-engineering/scripts/audit-a11y.sh82
5 files changed, 101 insertions, 110 deletions
diff --git a/README.md b/README.md
index e6b1d71..cd4b323 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ Skills encode the workflows, quality gates, and best practices that senior engin
| Set the quality bar | `/constraints` | Decide it once, enforce it everywhere |
| Review before merge | `/review` | Improve code health |
| Audit web performance | `/webperf` | Measure before you optimize |
-| Audit accessibility | `/a11y` | Automated tools catch ~30%; manual testing catches the rest |
+| Audit accessibility | `/a11y` | Automation is a smoke test; manual verification completes the audit |
| Simplify the code | `/code-simplify` | Clarity over cleverness |
| Ship to production | `/ship` | Faster is safer |
diff --git a/docs/copilot-setup.md b/docs/copilot-setup.md
index b33d111..2ef224d 100644
--- a/docs/copilot-setup.md
+++ b/docs/copilot-setup.md
@@ -98,6 +98,7 @@ Skills are user-invocable by default, so once they're discovered the whole lifec
| Build | `/incremental-implementation` | Pair with `/test-driven-development`; one slice at a time |
| Verify | `/test-driven-development` | Red-green-refactor, Prove-It for bugs |
| Review | `/code-review-and-quality` | Five-axis review |
+| Audit accessibility | `/accessibility-engineering` | WCAG 2.2 AA audit; the repository's short command wrapper is `/a11y` |
| Ship | `/shipping-and-launch` | Launch readiness |
Type `/` to browse what's actually loaded in this workspace.
diff --git a/references/accessibility-checklist.md b/references/accessibility-checklist.md
index 214ab49..48f15da 100644
--- a/references/accessibility-checklist.md
+++ b/references/accessibility-checklist.md
@@ -1,6 +1,6 @@
# Accessibility Checklist
-Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engineering` skill.
+Quick reference for WCAG 2.2 AA conformance. Use `frontend-ui-engineering` while building interfaces and `accessibility-engineering` when auditing and remediating them.
## Table of Contents
@@ -49,7 +49,7 @@ Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engin
- [ ] Language declared (`<html lang="en">`)
- [ ] Page has a descriptive `<title>`
- [ ] Links distinguish from surrounding text (not by color alone)
-- [ ] Touch targets ≥ 44x44px on mobile
+- [ ] Touch targets meet 24x24 CSS px (SC 2.5.8, AA), including its spacing and exception rules; 44x44 CSS px is the enhanced AAA target (SC 2.5.5)
- [ ] Meaningful empty states (not blank screens)
## Common HTML Patterns
@@ -123,9 +123,9 @@ Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engin
## Testing Tools
```bash
-# Automated audit
-npx --package=@axe-core/cli axe http://localhost:3000
-npx pa11y # CLI accessibility checker
+# Automated audit (versions pinned for repeatable browser-driver behavior)
+npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit
+npx --yes pa11y@9.1.1 http://localhost:3000
# In browser
# Chrome DevTools → Lighthouse → Accessibility
diff --git a/skills/accessibility-engineering/SKILL.md b/skills/accessibility-engineering/SKILL.md
index df2ebc3..021a98b 100644
--- a/skills/accessibility-engineering/SKILL.md
+++ b/skills/accessibility-engineering/SKILL.md
@@ -7,113 +7,41 @@ description: Audits existing interfaces for WCAG 2.2 AA conformance and remediat
## Overview
-Accessibility is not a polish step — it's a legal requirement in many jurisdictions, an engineering quality standard, and a prerequisite for shipping. This skill covers the full workflow: building accessible components, auditing existing interfaces, and fixing common violations. The goal is WCAG 2.2 AA compliance verified by automated tools and manual testing.
+Accessibility is not a polish step — it's a legal requirement in many jurisdictions, an engineering quality standard, and a prerequisite for shipping. This skill audits existing interfaces, triages the findings, and remediates verified violations. The goal is WCAG 2.2 AA compliance supported by automated tools and manual testing.
## When to Use
-- Building new UI components or pages
-- Before shipping any user-facing change that touches UI
+- Before shipping a user-facing change that needs an accessibility audit
- When a11y issues are reported (e.g., "screen reader can't read this", "keyboard navigation broken")
- When auditing an existing interface for compliance
-- When working with forms, modals, navigation, or interactive widgets
+- When triaging axe-core or pa11y findings
+- When remediating verified accessibility violations
-**Do NOT use** for backend-only changes, CLIs, or library code with no UI output.
+**Do NOT use** for building new UI components from scratch; use `frontend-ui-engineering` for construction guidance. Do not use for backend-only changes, CLIs, or library code with no UI output.
## Workflow
-### Phase 1: Build Accessible Components
+### Phase 1: Route New UI Work
-Follow these rules when creating UI:
-
-**Semantic HTML first. ARIA second.**
-
-```tsx
-// Good: native elements have built-in accessibility
-<button onClick={handleClick}>Save</button>
-<nav aria-label="Main">
- <a href="/tasks">Tasks</a>
-</nav>
-
-// Avoid: re-creating native behavior with ARIA
-<div role="button" tabIndex={0} onClick={handleClick}>Save</div>
-```
-
-**Label every interactive element:**
-
-```tsx
-// Visible label
-<label htmlFor="email">Email</label>
-<input id="email" type="email" />
-
-// Icon-only button
-<button aria-label="Delete task">
- <TrashIcon />
-</button>
-
-// Avoid: placeholder as the only label
-// It supplies a fallback accessible name (HTML-AAM), but it disappears on
-// input, so the field has no persistent label (SC 3.3.2).
-<input type="email" placeholder="Email address" />
-```
-
-**Manage focus for dynamic content:**
-
-```tsx
-function Dialog({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
- const dialogRef = useRef<HTMLDialogElement>(null);
- // showModal() makes the rest of the page inert and closes on Escape
- useEffect(() => {
- const dialog = dialogRef.current;
- if (isOpen && !dialog?.open) dialog?.showModal();
- if (!isOpen && dialog?.open) dialog.close();
- }, [isOpen]);
-
- return (
- <dialog ref={dialogRef} onClose={onClose} aria-labelledby="dialog-title">
- <h2 id="dialog-title">Confirm</h2>
- <button onClick={onClose}>Close</button>
- </dialog>
- );
-}
-```
-
-**Announce dynamic updates:**
-
-```tsx
-// Status updates
-<div role="status" aria-live="polite">
- {isSaved ? 'Task saved' : 'Saving...'}
-</div>
-
-// Error messages
-<div role="alert">
- Title is required
-</div>
-```
-
-**Support keyboard navigation:**
-
-- All interactive elements reachable via Tab
-- Focus order matches visual order
-- No keyboard traps (always Tab-away-able)
-- Custom widgets handle Enter, Escape, Arrow keys
-- Visible focus indicator (never `outline: none` without a replacement)
+For component construction, interaction patterns, and focus-management guidance, use `../frontend-ui-engineering/SKILL.md`. Do not restate that skill here. Return to this workflow once an interface exists and needs auditing or remediation.
### Phase 2: Run Automated Audit
Execute accessibility checks in this order:
```bash
-# axe-core rules through @axe-core/cli (the axe-core package ships no CLI)
-npx @axe-core/cli http://localhost:3000 --exit
+# axe-core rules through pinned @axe-core/cli (the axe-core package ships no CLI)
+npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit
# Keep the JSON for the accessibility-auditor
-npx @axe-core/cli http://localhost:3000 --dir ./a11y-reports --save axe.json
+npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --dir ./a11y-reports --save axe.json
-# pa11y for HTML validation (WCAG2AA rules via HTML_CodeSniffer)
-npx pa11y http://localhost:3000
+# Pinned pa11y for HTML validation (WCAG2AA rules via HTML_CodeSniffer)
+npx --yes pa11y@9.1.1 http://localhost:3000
```
+For a combined report, run `bash skills/accessibility-engineering/scripts/audit-a11y.sh url <url> --json`. It runs both pinned tools, records their status and versions, and fails rather than reporting a clean result when either tool does not produce a valid report.
+
Review the violations grouped by severity:
- **Critical** — Blocks screen reader access entirely (missing alt text on info images, empty buttons)
- **Serious** — Makes content difficult or impossible to access (low contrast, missing labels)
@@ -124,7 +52,7 @@ For each violation, verify it's a real issue (not a false positive) by inspectin
### Phase 3: Manual Testing
-Automated tools catch ~30% of a11y issues. Manual testing catches the rest.
+Automated checks are a smoke test, not proof of conformance. Complete the audit manually.
**Keyboard audit:**
1. Tab through every interactive element — can you see where you are?
@@ -161,9 +89,9 @@ Apply the accessibility checklist (`../../references/accessibility-checklist.md`
| Rationalization | Reality |
|---|---|
-| "We'll fix a11y later" | Retrofitting accessibility costs 3-5x more than building it in. In many jurisdictions, shipping inaccessible software is a legal liability. |
-| "Automated tools caught everything" | Automated tools detect ~30% of WCAG failures. Keyboard and screen reader testing are mandatory. |
-| "Screen reader users are a tiny minority" | 15% of the global population has some disability. Accessibility improvements benefit everyone (keyboard nav helps power users, captions help noisy environments). |
+| "We'll fix a11y later" | Delayed remediation compounds across components and can create legal liability. Audit before shipping. |
+| "Automated tools caught everything" | Automated checks cannot prove keyboard or screen reader behavior. Manual testing is mandatory. |
+| "Screen reader users are a tiny minority" | Accessibility is a requirement, not a usage-share calculation. Keyboard navigation, captions, and clear structure also help users across contexts. |
| "This is an internal tool, it doesn't need a11y" | Internal tools are subject to the same regulations. Disabled employees and contractors need access. |
| "I'll just use aria-label everywhere" | ARIA is a bridge, not a foundation. Semantic HTML first. Overusing ARIA creates maintenance burden and can make things worse. |
| "The design system handles accessibility" | Design systems provide accessible primitives. How you compose them determines whether the result is accessible. |
@@ -179,14 +107,14 @@ Apply the accessibility checklist (`../../references/accessibility-checklist.md`
- Empty or unlabeled buttons and links
- Modals that don't trap focus or restore focus on close
- No `alt` text on meaningful images (or `alt=""` missing on decorative ones)
-- Touch targets smaller than 24x24 CSS px (SC 2.5.8, AA; 44x44 is the AAA target, SC 2.5.5)
+- Touch targets that fail SC 2.5.8's 24x24 CSS px size-or-spacing requirement and do not qualify for an exception (AA; 44x44 is the AAA target, SC 2.5.5)
- Autoplaying video or audio without controls
- Low contrast text (especially on hover, disabled states, placeholders)
## See Also
-- `../../references/accessibility-checklist.md` — Quick reference for WCAG 2.1 AA
-- `skills/frontend-ui-engineering/SKILL.md` — Building accessible components from the start
+- `../../references/accessibility-checklist.md` — Quick reference for WCAG 2.2 AA
+- `../frontend-ui-engineering/SKILL.md` — Building accessible components from the start
- `agents/accessibility-auditor.md` — Dedicated a11y audit persona for deep reviews
## Verification
@@ -202,4 +130,4 @@ After completing the accessibility workflow:
- [ ] All images have appropriate `alt` text
- [ ] Dynamic content changes are announced (aria-live)
- [ ] Page is usable at 200% zoom with no content loss
-- [ ] Touch targets are at least 24x24 CSS px (SC 2.5.8, AA); 44x44 is the AAA target (SC 2.5.5)
+- [ ] Touch targets satisfy SC 2.5.8's 24x24 CSS px size-or-spacing requirement or a normative exception (AA); 44x44 is the enhanced AAA target (SC 2.5.5)
diff --git a/skills/accessibility-engineering/scripts/audit-a11y.sh b/skills/accessibility-engineering/scripts/audit-a11y.sh
index 17d659d..1c9eb22 100755
--- a/skills/accessibility-engineering/scripts/audit-a11y.sh
+++ b/skills/accessibility-engineering/scripts/audit-a11y.sh
@@ -9,9 +9,11 @@ set -e
# bash audit-a11y.sh url <url> [--json]
# bash audit-a11y.sh file <path> [--json]
#
-# Requires: npx (@axe-core/cli and pa11y are fetched on demand)
+# Requires: npx (@axe-core/cli and pa11y are fetched at the pinned versions below)
SCRIPT_NAME="audit-a11y"
+AXE_VERSION="4.13.0"
+PA11Y_VERSION="9.1.1"
TEMP_DIR=$(mktemp -d)
trap 'rm -rf "$TEMP_DIR"' EXIT
@@ -28,14 +30,27 @@ fi
case "$MODE" in
url)
echo "Running axe-core audit on $TARGET..." >&2
- npx @axe-core/cli "$TARGET" --dir "$TEMP_DIR" --save axe-report.json >&2 || true
+ if npx --yes "@axe-core/cli@$AXE_VERSION" "$TARGET" --dir "$TEMP_DIR" --save axe-report.json >&2; then
+ AXE_EXIT=0
+ else
+ AXE_EXIT=$?
+ fi
echo "Running pa11y audit on $TARGET..." >&2
- npx pa11y "$TARGET" --reporter json 2>/dev/null > "$TEMP_DIR/pa11y-report.json" || true
+ if npx --yes "pa11y@$PA11Y_VERSION" "$TARGET" --reporter json 2>/dev/null > "$TEMP_DIR/pa11y-report.json"; then
+ PA11Y_EXIT=0
+ else
+ PA11Y_EXIT=$?
+ fi
;;
file)
+ AXE_EXIT=-1
echo "Running pa11y on file $TARGET..." >&2
- npx pa11y "$TARGET" --reporter json > "$TEMP_DIR/pa11y-report.json" 2>/dev/null || true
+ if npx --yes "pa11y@$PA11Y_VERSION" "$TARGET" --reporter json > "$TEMP_DIR/pa11y-report.json" 2>/dev/null; then
+ PA11Y_EXIT=0
+ else
+ PA11Y_EXIT=$?
+ fi
echo "File-based axe analysis limited; prefer URL mode for full coverage." >&2
;;
*)
@@ -44,20 +59,62 @@ case "$MODE" in
;;
esac
-# Both tool invocations above are masked with `|| true` so one failure does not
-# abort the run. Without this guard a missing npx, an offline run, or a bad
-# option would fall through to an empty report and print a clean zero.
-if [ ! -s "$TEMP_DIR/axe-report.json" ] && [ ! -s "$TEMP_DIR/pa11y-report.json" ]; then
- echo "$SCRIPT_NAME: no tool produced a report; not printing a zero-violation result" >&2
+report_status() {
+ local tool="$1"
+ local report="$2"
+ local exit_code="$3"
+ if [ ! -s "$report" ]; then
+ printf 'failed'
+ return
+ fi
+
+ # axe runs without --exit, so any non-zero status is an execution failure.
+ # pa11y uses exit 2 when a valid report contains violations; other non-zero
+ # statuses mean the audit itself failed.
+ if { [ "$tool" = "axe" ] && [ "$exit_code" -ne 0 ]; } || \
+ { [ "$tool" = "pa11y" ] && [ "$exit_code" -ne 0 ] && [ "$exit_code" -ne 2 ]; }; then
+ printf 'failed'
+ elif node -e "
+ const fs = require('fs');
+ const tool = process.argv[1];
+ const report = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+ const valid = tool === 'axe'
+ ? Array.isArray(report) && report.length > 0 && report.every(run => run && Array.isArray(run.violations))
+ : Array.isArray(report);
+ if (!valid) process.exit(1);
+ " "$tool" "$report" >/dev/null 2>&1; then
+ printf 'completed'
+ else
+ printf 'invalid-report'
+ fi
+}
+
+if [ "$MODE" = "url" ]; then
+ AXE_STATUS=$(report_status axe "$TEMP_DIR/axe-report.json" "$AXE_EXIT")
+else
+ AXE_STATUS="not-run"
+fi
+PA11Y_STATUS=$(report_status pa11y "$TEMP_DIR/pa11y-report.json" "$PA11Y_EXIT")
+
+# A URL audit promises both engines. A valid report is the success signal because
+# pa11y may return non-zero when it found violations. Never turn a partial run
+# into a clean result just because the remaining engine returned an empty list.
+if [ "$PA11Y_STATUS" != "completed" ] || { [ "$MODE" = "url" ] && [ "$AXE_STATUS" != "completed" ]; }; then
+ echo "$SCRIPT_NAME: incomplete audit; refusing to report a violation total" >&2
+ echo "$SCRIPT_NAME: tool status: @axe-core/cli@$AXE_VERSION=$AXE_STATUS (exit $AXE_EXIT), pa11y@$PA11Y_VERSION=$PA11Y_STATUS (exit $PA11Y_EXIT)" >&2
exit 1
fi
# Merge results into structured JSON output
RESULT_FILE="$TEMP_DIR/result.json"
-cat > "$RESULT_FILE" << 'RESULT_EOF'
+cat > "$RESULT_FILE" << RESULT_EOF
{
"tool": "audit-a11y",
+ "tools": [
+ {"name": "@axe-core/cli", "version": "$AXE_VERSION", "status": "$AXE_STATUS", "exitCode": $AXE_EXIT},
+ {"name": "pa11y", "version": "$PA11Y_VERSION", "status": "$PA11Y_STATUS", "exitCode": $PA11Y_EXIT}
+ ],
"summary": {
"violations": 0,
"critical": 0,
@@ -155,6 +212,11 @@ else
const r = JSON.parse(require('fs').readFileSync('$RESULT_FILE', 'utf8'));
console.log('Accessibility Audit Results');
console.log('===========================');
+ console.log('Tools:');
+ for (const tool of r.tools) {
+ console.log(' ' + tool.name + '@' + tool.version + ': ' + tool.status + ' (exit ' + tool.exitCode + ')');
+ }
+ console.log('');
console.log('Total violations: ' + r.summary.violations);
console.log(' Critical: ' + r.summary.critical);
console.log(' Serious: ' + r.summary.serious);