Frontend A11Y

frontend-a11y

frontend-perfection owns measurable layout/perf/SEO/tokens polish and only touches ~12 basic a11y rules (img-alt, button/link-name, form-label, aria-valid, landmark-unique, plus lang/dir/headings). This skill owns the deep accessibility domain — the full Front-End-Checklist Accessibility category (95 rules), split into three checkable tiers so the right tool runs at the right time.

• static — offline Python (scripts/a11y_audit.py), no browser, no network. Markup structure, ARIA validity, headings, landmarks, tables, forms, media tracks, lists, and a few CSS signals.
• runtime — Playwright + axe-core (scripts/a11y_axe.mjs, optional npm deps). Computed contrast, ARIA parent/child relationships, live regions, focus order, modal traps, reflow at 400% zoom, touch targets.
• manual — screen-reader testing and human-judgement rules (NVDA/JAWS/ VoiceOver/TalkBack, plain language, seizure flashing). Checklist-only; the report records them as severity: manual so they are not silently skipped.

When to use

• User asks to "audit accessibility", "check WCAG", "run axe", "test keyboard navigation", "find focus traps", "verify contrast", "проверь доступность".
• The /frontend orchestrator routes the a11y domain here; mobile-frontend calls it for touch-target / orientation / reflow checks.
• After frontend-perfection passes its 12 basic rules and you need the other 83.

Composition

• vs frontend-perfection — it owns layout/perf/SEO/tokens + 12 a11y rules (incl. computed contrast). This skill owns the remaining 83 a11y rules. Do NOT re-implement raw-hex token checks or computed-contrast here — those live in frontend-perfection/a11y_axe.mjs. Run frontend-perfection first for the shared baseline, then frontend-a11y for depth.
• vs mobile-frontend — it calls frontend-a11y for the mobile-a11y rules (touch target size, orientation, reflow at 400%, reduced motion).
• vs /frontend — the orchestrator runs frontend-perfection + this skill
  • (optionally) a11y_axe.mjs for the full a11y picture.

Workflow

Capture evidence at every step — run the scripts and paste the real command, its exit status, and the relevant JSON rows into the report. Assertions without the script output are not acceptable, because the audit ids are the only contract that proves a fix actually closed a violation.

1. Locate the target — static index.html (+ CSS) or a served URL.
2. Run the static audit (always, offline) and record its exit status:

   python3 scripts/a11y_audit.py --html index.html --css main.css css/demo.css --out a11y-static.json
   echo "exit=$?"
   

   Exit 0 = no violations, 1 = violations, 2 = runner error. Paste the exit= line and the violation summary into the report as evidence.
3. Run the runtime audit (optional, needs deps) on a served URL, again recording the exit status:

   npm i playwright axe-core && npx playwright install chromium
   node scripts/a11y_axe.mjs --url http://localhost:8377/ --out a11y-axe.json
   echo "exit=$?"
   

   Paste the exit= line and the FAIL/manual rows so the runtime findings are verifiable, not assumed.
4. Fix by audit id — every fix references the id it closes (a11y:img-alt, a11y:landmark-main, a11y:axe:color-contrast, …).
5. Re-audit until green on static; resolve runtime FAIL rows; record manual rows as verified-or-pending in the report. Re-run the same command and show the new exit= so the improvement is demonstrable.
6. Write the before/after report (see convention below): input paths, exact commands, real output, interpretation, and what was deliberately NOT done.

audit-id scheme (95 rules)

Each checklist rule maps to a stable id tagged static / runtime / manual. Severity (critical/high/medium/low) mirrors the checklist priority and is emitted per check in the JSON report.

static — offline Python (a11y_audit.py)

runtime — Playwright + axe-core (a11y_axe.mjs)

manual — screen reader / human judgement

Scripts

a11y_audit.py (static, offline, stdlib)

Reads one or more --html files and optional --css. Emits a JSON report (--out / --json) where every check has id, title, severity, ok, detail, file. Exit codes: 0 no violations, 1 violations, 2 runner error. No PyYAML, no requests, no network.

python3 scripts/a11y_audit.py --html index.html --css main.css --out a11y.json
python3 scripts/a11y_audit.py --html a.html b.html --json   # stdout JSON

a11y_axe.mjs (runtime, optional deps)

Real Chromium via Playwright; injects axe-core and runs the WCAG tag set. Documents required deps in its header; it does NOT run at build time. Exit codes mirror the static script (0/1/2). incomplete axe results are emitted as severity: manual so they surface for human confirmation instead of being counted as hard failures.

npm i playwright axe-core && npx playwright install chromium
node scripts/a11y_axe.mjs --url http://localhost:8377/ --out a11y-axe.json

Before/after report convention

Bind every claim to an audit id. Format:

## Accessibility audit — <project>
Inputs: index.html, main.css
Commands:
  python3 scripts/a11y_audit.py --html index.html --css main.css --out a11y.json
  (exit 1, 14 violations)

Before: 14 violations (a11y:img-alt ×3, headings:order, a11y:landmark-main, …)
Fixes:
  - a11y:img-alt: added alt to hero/banner/icons
  - headings:order: h1→h3 gap closed (inserted h2)
  - a11y:landmark-main: removed duplicate <main>
After: 0 violations (exit 0)

Runtime (axe): 2 FAIL (color-contrast on footer), 3 manual pending
Manual: screen-reader pass pending (NVDA) — NOT done this run
Not done: computed-contrast (owned by frontend-perfection), design tokens.

Constraints / non-goals

• a11y_audit.py is offline and stdlib-only — no PyYAML, no requests, no network, no browser. Keep it runnable with only python3 so the audit works in any CI or offline environment without extra installs.
• Computed color contrast and design-token hex checks are out of scope here (owned by frontend-perfection and a11y_axe.mjs). Don't add them to the static script, or the two skills will duplicate and drift apart.
• a11y_axe.mjs requires npm i playwright axe-core + npx playwright install chromium; it is documented, not executed, at build time.
• Don't depend on the external Front-End-Checklist MCP server; the 95-rule mapping is embedded above so the skill runs without network or that dependency.
• Fix at the root (real semantics). Avoid hiding audits with aria-hidden spray or tabindex=-1 hacks — those mask the violation instead of resolving it, so the next audit still fails and users are still blocked.
• Record manual rules; never silently drop them, so they appear as severity: manual in the report and get a human confirmation.