/a11y-validate

name: a11y-validate
description: "Accessibility validator: WCAG 2.1 AA, EN 301 549, EAA. Triggers: a11y, accessibility, WCAG, EAA, ARIA, contrast, keyboard, screen reader."
user-invocable: true
effort: medium
disable-model-invocation: true
context: fork
agent: frontend-specialist
argument-hint: "[path] [--scope full|keyboard|contrast|forms|media|aria|motion|mobile|docs] [--standard wcag-2.1-aa|wcag-2.2-aa|en-301-549|eaa] [--severity high|warn|info] [--framework auto|react|next|nuxt|astro|gatsby|sveltekit|remix|angular|vue|react-native|flutter|static] [--output markdown|json]"
allowed-tools: Read, Grep, Glob, Bash

/a11y-validate — Accessibility & EAA Compliance Scanner

$ARGUMENTS

Scan a codebase for accessibility issues using pattern-matching heuristics. Detects violations of **WCAG 2.1 Level AA**, **EN 301 549** (the EU harmonized accessibility standard), and the **European Accessibility Act** (Directive (EU) 2019/882, "EAA", in force since 28 June 2025). Read-only — never modifies files.

Complements `/seo-validate` (which only covers SEO-a11y overlap shallowly). Use this skill when the concern is legal accessibility compliance, not search engine ranking.

**Standards basis**:

• **WCAG 2.1** Level A + AA — W3C Recommendation 2018 (updated 2023).
• **WCAG 2.2** Level AA (opt-in via `--standard wcag-2.2-aa`) — adds 2.4.11 focus not obscured, 2.5.8 target size minimum, 3.2.6 consistent help, 3.3.7 redundant entry, 3.3.8 accessible authentication.
• **EN 301 549 v3.2.1** — EU harmonized standard; aligned with WCAG 2.1 AA plus additional chapters for mobile, hardware, ICT procurement, authoring tools, and functional-performance statements.
• **EAA / Directive (EU) 2019/882** — legal framework requiring EN 301 549 conformance for consumer-facing digital products and services in EU markets. Deadline: **28 June 2025**. Requires accessibility statements per member-state templates.

Usage

/a11y-validate                                # Scan full project, auto-detect framework
/a11y-validate src/                           # Scan specific path
/a11y-validate --scope keyboard               # Only keyboard + focus checks
/a11y-validate --scope media                  # Only captions/transcripts/autoplay
/a11y-validate --scope docs                   # Only EAA accessibility-statement check
/a11y-validate --scope mobile                 # Only React Native + Flutter patterns
/a11y-validate --standard eaa                 # Activate EAA documentation category
/a11y-validate --standard wcag-2.2-aa         # Add WCAG 2.2 criteria
/a11y-validate --severity high                # Filter to HIGH findings
/a11y-validate --framework react-native       # Force framework
/a11y-validate --output json                  # Structured JSON for CI integration

**Scopes:**

• `full` (default) — all 8 categories
• `keyboard` — Category 3 only
• `contrast` — Category 4 only
• `forms` — Category 5 only
• `media` — Category 6 only
• `aria` — Category 7 only
• `motion` — Category 8 motion subsection
• `mobile` — Category 8 mobile subsection (React Native / Flutter)
• `docs` — Category 8 EAA documentation subsection (fast "are we legally exposed?" scan)

**Standards:**

• `wcag-2.1-aa` (default) — 50 Level A + AA success criteria.
• `wcag-2.2-aa` — adds 2.4.11, 2.5.8, 3.2.6, 3.3.7, 3.3.8.
• `en-301-549` — wcag-2.1-aa + mobile chapter + functional-performance statements.
• `eaa` — en-301-549 + accessibility-statement documentation requirement (activates Category 8 docs).

**Severity filtering:** `--severity high` shows only HIGH, `--severity warn` shows HIGH+WARN, `--severity info` shows all. Default: all.

What This Command Does

1. **Detect framework** from `package.json`, `pubspec.yaml`, and entry HTML. 2. **Run the scanner script** for a deterministic baseline over 13 WCAG success criteria. 3. **Extend the scan by hand** using `Grep` / `Glob` / `Read` against framework-aware patterns for everything the script does not cover. 4. **Interpret findings** with specific fixes tied to the detected framework. 5. **Report** findings sorted by severity with WCAG / EN 301 549 citations.

Steps

Step 1: Detect Framework

Run detection before scanning. Same logic as `/seo-validate` plus mobile entries:

| Deps / files contain | Framework | Notes | |---|---|---| | `next` | `next` | App Router uses `metadata` export | | `nuxt` | `nuxt` | `useHead()` / `definePageMeta` | | `astro` | `astro` | islands model; `client:only` affects a11y | | `gatsby` | `gatsby` | Head API + react-helmet | | `@sveltejs/kit` | `sveltekit` | `<svelte:head>` | | `@remix-run/*` | `remix` | `MetaFunction` | | `@angular/core` | `angular` | CDK `a11y` module expected | | `vue` (no nuxt) | `vue` | a11y plugins optional | | `react` + `vite` (no next/remix) | `react-spa` | — | | `react-scripts` | `cra` | — | | `react-native` | `react-native` | mobile — AccessibilityInfo API | | `pubspec.yaml` with Flutter SDK | `flutter` | mobile — `Semantics()` widget | | no framework deps | `static` | raw HTML |

Also detect a11y libraries: `@react-aria/*`, `@reach/*`, `@angular/cdk/a11y`, `vue-a11y`, `svelte-a11y`, `react-axe`, `axe-core`. Their presence is INFO.

Step 2: Run the Scanner Script

python3 ${CLAUDE_SKILL_DIR}/scripts/a11y-scanner.py [path] [--severity high|warn|info|all] [--output json|text]

Deterministic regex checks over 13 WCAG success criteria — images, headings, language, forms, keyboard, focus, colour contrast, media, ARIA and target size. No framework awareness and no heuristics: what it reports is real, what it misses is Step 3's job. Exit code is non-zero when HIGH findings exist.

Step 3: Extend the Scan by Hand

Read [reference/scanner-categories.md](reference/scanner-categories.md) in full, then work every category in `--scope` with `Grep` + `Read`, skipping only the success criteria Step 2 already reported. Patterns adapt to the detected framework.

The coverage table under [Scanner Reference](#scanner-refer