diff options
| author | Chukwuebuka Ezeokeke <ebulamicheal@gmail.com> | 2026-10-14 22:13:04 +0000 |
|---|---|---|
| committer | Chukwuebuka (Gaus Octavio) <56232734+Chukwuebuka-2003@users.noreply.github.com> | 2026-11-16 09:56:26 +0000 |
| commit | 3b79b0ce438e944fab594b143f20f64b6093562d (patch) | |
| tree | e1fcaddadb80aaaa5d90179f96a05cc5a5ef54f9 | |
| parent | 0094fdbd5ebb15ec9243a94e43e7224edbae52de (diff) | |
fix(review): address maintainer accessibility feedback
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | docs/copilot-setup.md | 1 | ||||
| -rw-r--r-- | references/accessibility-checklist.md | 10 | ||||
| -rw-r--r-- | skills/accessibility-engineering/SKILL.md | 116 | ||||
| -rwxr-xr-x | skills/accessibility-engineering/scripts/audit-a11y.sh | 82 |
5 files changed, 101 insertions, 110 deletions
@@ -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); |
