design-accessibility

Family: design Status: Stable

Purpose

A dedicated accessibility skill. Runs structural WCAG 2.2 checks on any HTML with no tools required (the free path) and a full axe-core scan when Playwright is installed (the deep path), producing a severity-ranked report that downstream skills (qa-gate, design-build) can act on.

Triggers

• "accessibility check" / "a11y check" / "wcag audit"
• "axe scan" / "is this accessible"
• "screen reader check" / "keyboard nav check"

Inputs

• Target URL or local build path
• WCAG level: AA (default) | AAA
• Viewports to test (defaults: 375 / 768 / 1280)
• Optional: a design-system token file (from design-system-gen); the token-based contrast check in Step 2 runs only when it is present

Steps

1. Detect Playwright. If available → deep path (step 3). If not → static path (step 2). Always say which path ran.
2. Static WCAG checks (free path, on the page source): run scripts/design/a11y_static.py --file <page.html> — a stdlib html.parser structural checker that emits severity-ranked JSON findings for image alt coverage, heading order (no skipped levels / one <h1>), form-control labels, <html lang>, a skip-to-content link, <main>/landmark presence, and a responsive (non-zoom-blocking) viewport meta. When a design-system-gen token file is present, pass --tokens <tokens.json> to add the token-contrast cross-check (the engine's own WCAG luminance math over the text/bg/ surface/primary/on_primary/accent slots). See references/design-accessibility/structural-checks.md for the full check catalog + severity model.
3. Deep axe scan (Playwright path): for each viewport, run axe-core; test keyboard nav (tab order, visible focus, focus traps in modals, escape routes); test prefers-reduced-motion; test 200% text scaling for truncation/overflow; verify computed-style color contrast.
4. Classify findings critical / serious / moderate / minor with the WCAG success criterion and remediation guidance (file:line when source is available).
5. Render the report; note clearly that the static path is a subset and a full axe scan needs Playwright.

Capability routing

Accessibility auditing runs on a two-tier cascade. The free Tier-2 structural checker (a11y_static.py) is the product — it delivers a real severity-ranked WCAG artifact with no browser and no network; a connected Playwright + axe-core (Tier 1) deepens it with rendered-pixel contrast and live keyboard/motion/zoom testing. See references/CAPABILITY-TIERS.md for the cascade grammar.

capability:   structural-a11y
tier1:        Playwright + @axe-core/playwright (rendered scan)
tier1_signal: none
tier2:        a11y_static.py (stdlib html.parser structural WCAG checker + token-contrast cross-check, no browser)
tier2_yields: severity-ranked WCAG findings (alt, heading order, labels, lang, viewport, landmarks, skip link, token contrast) with per-issue WCAG SC + fix, zero spend
tier3:        none
tier3_signal: none
tier4:        manual WCAG 2.2 walkthrough; connect Playwright for a full axe-core scan
needs_tier1:  computed rendered-pixel contrast, live keyboard/focus order, reduced-motion behavior, 200%-zoom reflow

Outputs

Filed to: the user's project workspace. The structural path is a genuine subset — computed-contrast, live keyboard, reduced-motion, and 200%-zoom facts are marked needs_tier1 (Playwright + axe-core), never synthesized.

Error Handling

Dependencies

• None required for the static path (analyzes provided HTML)
• Playwright extension + @axe-core/playwright (optional — adds computed-contrast verification + live keyboard/focus testing + reduced-motion + 200%-zoom checks; free path: the static structural checks in Step 2)

Notes

Mandatory inside the qa-gate workflow (phase 3); also standalone. The static path catches a real subset of WCAG issues, but only a browser-based axe scan covers computed contrast and live keyboard behavior — the report says so rather than implying full coverage.