skill: accessibility

should_trigger:
  - prompt: "Make this signup form accessible — WCAG 2.2 AA."
    why: Direct conformance ask against the exact standard this skill owns.
  - prompt: "axe-core reports color-contrast and button-name violations, fix them."
    why: Tool-output trigger; named axe rules are this skill's home turf.
  - prompt: "The modal doesn't trap focus and Escape doesn't close it."
    why: Non-obvious phrasing — focus management for overlays, no a11y keyword in sight.
  - prompt: "Tab order jumps around and the icon-only buttons have no label for screen readers."
    why: Keyboard order plus accessible-name problem; core operable/perceivable work.
  - prompt: "El lector de pantalla no lee los errores del formulario, fes-ho accessible."
    why: Spanish/Catalan trigger — live region for errors plus general conformance ask.
  - prompt: "Our tap targets are smaller than 24px — does WCAG 2.2 require bigger ones?"
    why: Non-obvious specificity on SC 2.5.8 Target Size (Minimum), a 2.2 delta.
  - prompt: "Lighthouse accessibility score is 62, get it into the green."
    why: Low a11y score is a direct entry point even though Lighthouse is multi-purpose.

should_not_trigger:
  - prompt: "The page LCP is 4 seconds, make it load faster."
    route_to: performance
    why: Page-speed / Core Web Vitals tuning, not WCAG conformance.
  - prompt: "Set up the Jest + React Testing Library harness for this repo."
    route_to: testing-web
    why: Test runner / render setup mechanics; this skill only supplies the a11y assertions that run inside it.
  - prompt: "Write Playwright E2E tests for the checkout flow."
    route_to: e2e-testing
    why: Full browser-driven flow orchestration, not a WCAG audit.
  - prompt: "Pick the brand colors and spacing scale for the design system."
    route_to: design
    why: Visual intent and design tokens; this skill checks the contrast/target-size outcome, not the aesthetic.
  - prompt: "Sanitize this user input to prevent XSS."
    route_to: secure-coding
    why: Security hardening, unrelated to accessibility conformance.

capability:
  - scenario: >
      Given a React component where an icon-only toggle is a <div onClick> inside a card,
      with no labels, a custom brand color for the glyph, and no keyboard handler — produce
      an accessible rewrite plus a way to verify it.
    must_include:
      - Replaces the div with a native <button> (Rule 0 — native HTML before ARIA).
      - Adds an accessible name (aria-label or visually-hidden text) so the icon-only control is announced.
      - Ensures keyboard operability and visible focus (:focus-visible rather than outline:none).
      - Flags that contrast must be checked in a real browser because jsdom/jest-axe can't compute it.
      - Adds an automated check (jest-axe, or @axe-core/playwright scoped to the wcag22aa tag).
      - States automation catches only ~57% of issues and names at least one manual check (keyboard pass or screen-reader spot check).

# Evals — accessibility

These cases are graded by eye, not by an auto-runner. Read `cases.yaml` against the live `SKILL.md` description and decide: every `should_trigger` prompt should clearly select **accessibility** (note that several are deliberately non-obvious — a focus-trap complaint, a tap-target-size question, and a Catalan/Spanish phrasing — so the description's `Triggers:` list has to cover them), while each `should_not_trigger` prompt should route to the named sibling instead (`performance`, `testing-web`, `e2e-testing`, `design`, `secure-coding`) and not pull this skill in. For the `capability` case, prompt the agent with the scenario and read its output for each `must_include` point — it passes only if the rewrite replaces the div with a native `<button>`, gives the control an accessible name, makes it keyboard-operable with a visible focus ring, flags that contrast needs a real browser, wires in an automated check (jest-axe or @axe-core/playwright with the `wcag22aa` tag), and explicitly says automation only covers ~57% while naming a manual check. There is no scoring script; this is a judgement pass over the skill's text and the agent's response.

# Accessible patterns (copy-ready)

The minimal correct ARIA + keyboard behavior for the widgets you can't build from a single native element. Written fresh; verify intent against the W3C ARIA Authoring Practices Guide. Reach for these **only** when no native element fits (Rule 0).

Recurring obligation for everything custom: **Name, Role, Value** — a name, the right role, and *state kept in sync* with the handler that changes the visuals.

---

## Modal dialog

Prefer native `<dialog>` + `el.showModal()` — it gives you the role, the backdrop, focus trap, and Escape-to-close for free. Build by hand only if you can't.

If hand-rolling: `role="dialog"` (or `alertdialog`), `aria-modal="true"`, and `aria-labelledby` pointing at the title.

| Key            | Behavior                                          |
| -------------- | ------------------------------------------------- |
| Open           | Move focus into the dialog (first control/title). |
| `Tab`          | Cycle within; from last element wrap to first.    |
| `Shift+Tab`    | From first element wrap to last.                  |
| `Esc`          | Close; **return focus to the trigger**.           |

Trap focus while open; mark the rest of the page inert (`inert` attribute or `aria-hidden` on the background). Never leave focus loose behind the overlay.

## Disclosure / accordion

A button that shows/hides a region. Native `<details><summary>` covers most cases — use it first.

Hand-rolled: a `<button>` with `aria-expanded` and `aria-controls` pointing at the panel id.

| Key             | Behavior                          |
| --------------- | --------------------------------- |
| `Enter`/`Space` | Toggle the panel; flip `aria-expanded`. |

```html
<button aria-expanded="false" aria-controls="sect1">Details</button>
<div id="sect1" hidden>…</div>
```

Toggle `aria-expanded` **and** the `hidden` attribute in the same handler.

## Tabs

`role="tablist"` wraps `role="tab"` buttons; each tab `aria-controls` its `role="tabpanel"`. The active tab has `aria-selected="true"`; the panel has `tabindex="0"`.

Use **roving tabindex**: active tab `tabindex="0"`, others `-1`.

| Key                 | Behavior                                  |
| ------------------- | ----------------------------------------- |
| `Tab`               | Into the tablist (one stop), then panel.  |
| `←` / `→`           | Move between tabs (horizontal tablist).   |
| `Home` / `End`      | First / last tab.                         |
| `Enter`/`Space`     | Activate (if not auto-activating).        |

## Combobox (autocomplete)

`role="combobox"` on the input with `aria-expanded`, `aria-controls` → the listbox, and `aria-activedescendant` → the highlighted option id. The popup is `role="listbox"` of `role="option"`.

| Key             | Behavior                                            |
| --------------- | --------------------------------------------------- |
| `↓` / `↑`       | Open list / move highlight; update `aria-activedescendant`. |
| `Enter`         | Select the highlighted option, collapse.            |
| `Esc`           | Close the list, keep or clear the value.            |
| typing          | Filter; keep focus in the input the whole time.     |

Focus stays in the input — you move a virtual highlight via `aria-activedescendant`, not real focus.

## Menu button

A `<button aria-haspopup="menu" aria-expanded>` opens a `role="menu"` of `role="menuitem"`. Roving tabindex inside.

| Key                 | Behavior                                  |
| ------------------- | ----------------------------------------- |
| `Enter`/`Space`/`↓` | Open menu, focus first item.              |
| `↑` / `↓`           | Move between items.                       |
| `Home` / `End`      | First / last item.                        |
| `Esc`               | Close, return focus to the button.        |
| `Enter`             | Activate item, close.                     |

Note: a simple navigation dropdown of links is often better as a plain disclosure of `<a>` elements — don't reach for `role="menu"` unless it's an application action menu.

## Toast / live region

Transient status messages. Don't move focus to them — announce via a live region that already exists in the DOM.

- `role="status"` / `aria-live="polite"` — non-urgent ("Saved", "3 results"). Waits for a pause.
- `role="alert"` / `aria-live="assertive"` — urgent ("Submit failed", "Session expiring"). Interrupts. Use sparingly.

```html
<!-- present in the DOM before the message; inject text into it -->
<div role="status" aria-live="polite" class="sr-only"></div>
```

The region must exist *before* you write into it — injecting both the container and the text at once often isn't announced.

---

## The `.sr-only` utility

Visually hide while keeping it in the accessibility tree (skip links, live regions, icon-button names):

```css
.sr-only {
  position: absolute;
  width: 1px; height: 1px;
  padding: 0; margin: -1px;
  overflow: hidden;
  clip: rect(0 0 0 0);
  white-space: nowrap;
  border: 0;
}
```

Do **not** use `display:none` or `visibility:hidden` for this — both remove the text from screen readers too.

# WCAG 2.2 Level AA checklist (grouped by POUR)

The conformance bar. Each item is tagged how it's best verified:

- **[auto]** — an engine (axe-core) catches it reliably.
- **[manual]** — needs a human (keyboard, screen reader, judgement).
- **[both]** — automation flags candidates, a human confirms intent.

**NEW** marks a criterion introduced in WCAG 2.2 (W3C Recommendation 2023-10-05). WCAG 2.2 added 9 criteria and **removed 4.1.1 Parsing** — don't chase it anymore.

This is the AA conformance set (A + AA). Numbers (`x.y.z`) are the official SC ids so you can cross-reference the spec.

---

## Perceivable

- **1.1.1 Non-text Content (A)** — every image/icon/control has a text alternative; decorative images use `alt=""`. **[both]** (axe flags missing alt; a human judges whether it's *meaningful*).
- **1.3.1 Info and Relationships (A)** — structure is in the markup: headings, lists, `<label for>`, `<th scope>`, fieldset/legend. **[both]**
- **1.3.2 Meaningful Sequence (A)** — DOM order matches reading order; don't reorder with CSS in a way that breaks it. **[manual]**
- **1.3.4 Orientation (AA)** — don't lock to portrait/landscape unless essential. **[manual]**
- **1.3.5 Identify Input Purpose (AA)** — use `autocomplete` tokens on personal-data fields (`name`, `email`, `tel`). **[auto]**
- **1.4.1 Use of Color (A)** — color is never the only way to convey info; pair with text/icon/shape. **[manual]**
- **1.4.3 Contrast (Minimum) (AA)** — text **4.5:1**; large text (≥24px or ≥18.66px bold) **3:1**. **[auto in a real browser; jsdom can't]**
- **1.4.4 Resize Text (AA)** — text scales to 200% with no loss of content/function. **[manual]**
- **1.4.5 Images of Text (AA)** — use real text, not pictures of text, except logos. **[manual]**
- **1.4.10 Reflow (AA)** — content reflows to a 320px-wide viewport with no 2-D scrolling. **[manual]**
- **1.4.11 Non-text Contrast (AA)** — UI components and meaningful graphics hit **3:1** (input borders, focus indicators, icon glyphs, chart segments). **[both]**
- **1.4.12 Text Spacing (AA)** — no content clipped when users override line/letter/word spacing. **[manual]**
- **1.4.13 Content on Hover or Focus (AA)** — hover/focus popups are dismissable, hoverable, and persistent. **[manual]**

## Operable

- **2.1.1 Keyboard (A)** — all functionality available from the keyboard. **[manual]**
- **2.1.2 No Keyboard Trap (A)** — focus can always move away with the keyboard. **[manual]**
- **2.1.4 Character Key Shortcuts (A)** — single-key shortcuts can be turned off/remapped or only fire on focus. **[manual]**
- **2.4.1 Bypass Blocks (A)** — a skip link or landmarks let users bypass repeated content. **[both]**
- **2.4.2 Page Titled (A)** — every page has a unique, descriptive `<title>`. **[auto]**
- **2.4.3 Focus Order (A)** — focus order preserves meaning and operability. **[manual]**
- **2.4.4 Link Purpose (In Context) (A)** — link text says where it goes; no bare "click here". **[both]**
- **2.4.5 Multiple Ways (AA)** — more than one way to find a page (nav, search, sitemap). **[manual]**
- **2.4.6 Headings and Labels (AA)** — headings and labels describe topic/purpose. **[manual]**
- **2.4.7 Focus Visible (AA)** — keyboard focus is always visibly indicated. **[both]**
- **2.4.11 Focus Not Obscured (Minimum) (AA)** — **NEW** — a focused element isn't entirely hidden by sticky headers/footers/cookie bars. **[manual]**
- **2.5.1 Pointer Gestures (A)** — multipoint/path gestures have a single-pointer alternative. **[manual]**
- **2.5.2 Pointer Cancellation (A)** — actions fire on up-event, allow abort. **[manual]**
- **2.5.3 Label in Name (A)** — the accessible name contains the visible label text. **[both]**
- **2.5.4 Motion Actuation (A)** — device-motion features have a UI alternative and can be disabled. **[manual]**
- **2.5.7 Dragging Movements (AA)** — **NEW** — anything by dragging has a single-pointer (tap/button) alternative. **[manual]**
- **2.5.8 Target Size (Minimum) (AA)** — **NEW** — interactive targets ≥ **24×24 CSS px**, or spaced so a 24px circle doesn't overlap neighbors (spacing exception). **[both]**
- **2.3.1 Three Flashes or Below (A)** — nothing flashes more than 3×/second. **[manual]**

## Understandable

- **3.1.1 Language of Page (A)** — `<html lang="…">` set. **[auto]**
- **3.1.2 Language of Parts (AA)** — inline language changes marked with `lang`. **[manual]**
- **3.2.1 On Focus (A)** — focus alone doesn't trigger a context change. **[manual]**
- **3.2.2 On Input (A)** — changing a setting doesn't auto-change context without warning. **[manual]**
- **3.2.3 Consistent Navigation (AA)** — repeated nav stays in the same relative order. **[manual]**
- **3.2.4 Consistent Identification (AA)** — same-function components are labeled consistently. **[manual]**
- **3.2.6 Consistent Help (A)** — **NEW** — help (contact, FAQ link, chat) appears in the same relative order across pages. **[manual]**
- **3.3.1 Error Identification (A)** — errors are identified in text and described. **[both]**
- **3.3.2 Labels or Instructions (A)** — inputs have labels/instructions. **[both]**
- **3.3.3 Error Suggestion (AA)** — when known, suggest a correction. **[manual]**
- **3.3.4 Error Prevention (Legal/Financial/Data) (AA)** — reversible/checked/confirmed submissions. **[manual]**
- **3.3.7 Redundant Entry (A)** — **NEW** — don't ask for info already provided in the same process; auto-populate or let them select it. **[manual]**
- **3.3.8 Accessible Authentication (Minimum) (AA)** — **NEW** — no cognitive-function test to authenticate (no puzzles, no transcription); allow paste and password managers. **[manual]**

## Robust

- **4.1.2 Name, Role, Value (A)** — every UI component exposes a correct name, role, and current state/value to assistive tech. **[both]**
- **4.1.3 Status Messages (AA)** — status updates are announced without moving focus (live regions / roles). **[both]**

> 4.1.1 Parsing was **removed** in WCAG 2.2. Modern browsers recover from minor markup errors; the criterion no longer applies.

---

## How to work this list

1. Run axe (browser, `wcag22aa` tag) — clears most **[auto]** rows.
2. Do a keyboard-only pass — clears the operable **[manual]** rows.
3. One screen-reader spot check — names/roles/state, live-region announcements (4.1.2, 4.1.3).
4. Zoom 200% + 320px reflow — 1.4.4 / 1.4.10.
5. Manually verify the 2.2 NEW rows; they're almost all **[manual]** and the ones most teams miss.

#!/usr/bin/env bash
# verify.sh — accessibility conformance check (read-only by default).
#
# Detects the project's a11y tooling and runs the cheapest verdict it can:
#   1. an explicit a11y test script in package.json (e.g. "test:a11y")
#   2. @axe-core/playwright  -> needs a URL; runs an inline scan only if A11Y_URL is set
#   3. jest-axe              -> runs the project's jest tests
#   4. eslint-plugin-jsx-a11y -> lints src and counts jsx-a11y violations
#   5. nothing installed     -> prints install hints and EXITS 0 (skip, never a false failure)
#
# Exits non-zero ONLY when serious/critical violations are found.
# Usage: verify.sh [target-dir]   (default: current directory)
set -euo pipefail

TARGET="${1:-.}"
cd "$TARGET"

say() { printf '%s\n' "$*"; }

if [ ! -f package.json ]; then
  say "a11y: no package.json in '$TARGET' — nothing to verify. (skip)"
  exit 0
fi

# read a top-level field out of package.json without extra tooling
pkg_has() { node -e "const p=require('./package.json');const d={...p.dependencies,...p.devDependencies};process.exit(d['$1']?0:1)" 2>/dev/null; }
script_has() { node -e "const p=require('./package.json');process.exit((p.scripts||{})['$1']?0:1)" 2>/dev/null; }

PM="npm"
if [ -f pnpm-lock.yaml ]; then PM="pnpm"; elif [ -f yarn.lock ]; then PM="yarn"; fi
run_script() { case "$PM" in pnpm) pnpm run "$1";; yarn) yarn "$1";; *) npm run "$1";; esac; }

# 1) explicit a11y script wins
for s in test:a11y a11y test:accessibility accessibility; do
  if script_has "$s"; then
    say "a11y: running '$s' via $PM"
    run_script "$s"
    exit $?
  fi
done

# 2) @axe-core/playwright — needs a live URL
if pkg_has "@axe-core/playwright"; then
  if [ -z "${A11Y_URL:-}" ]; then
    say "a11y: @axe-core/playwright present but A11Y_URL not set."
    say "      Set A11Y_URL=http://localhost:3000 (with the app running) to scan. (skip)"
    exit 0
  fi
  say "a11y: scanning $A11Y_URL with @axe-core/playwright (wcag2a,wcag2aa,wcag22aa)"
  node - "$A11Y_URL" <<'NODE'
const { chromium } = require('playwright');
const AxeBuilder = require('@axe-core/playwright').default;
(async () => {
  const url = process.argv[2];
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'load' });
  const r = await new AxeBuilder({ page }).withTags(['wcag2a','wcag2aa','wcag22aa']).analyze();
  await browser.close();
  const by = {};
  for (const v of r.violations) by[v.impact || 'unknown'] = (by[v.impact || 'unknown'] || 0) + 1;
  console.log('a11y: violations by impact ' + (JSON.stringify(by) || '{}'));
  const blocking = (by.serious || 0) + (by.critical || 0);
  if (blocking > 0) { console.error(`a11y: ${blocking} serious/critical violation(s) — FAIL`); process.exit(1); }
  console.log('a11y: no serious/critical violations');
})().catch(e => { console.error('a11y: scan error — ' + e.message + ' (skip)'); process.exit(0); });
NODE
  exit $?
fi

# 3) jest-axe — run jest if a test script exists
if pkg_has "jest-axe"; then
  if script_has "test"; then
    say "a11y: jest-axe present — running '$PM test' (note: contrast disabled in jsdom)"
    run_script test
    exit $?
  fi
  say "a11y: jest-axe present but no 'test' script. (skip)"
  exit 0
fi

# 4) eslint-plugin-jsx-a11y — lint and count
if pkg_has "eslint-plugin-jsx-a11y"; then
  SRC="src"; [ -d "$SRC" ] || SRC="."
  say "a11y: linting $SRC with eslint (jsx-a11y rules)"
  OUT="$(npx --no-install eslint "$SRC" --ext .js,.jsx,.ts,.tsx -f json 2>/dev/null || true)"
  if [ -z "$OUT" ]; then
    say "a11y: eslint produced no output (config or install issue). (skip)"
    exit 0
  fi
  COUNT="$(printf '%s' "$OUT" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{const r=JSON.parse(s);let n=0;for(const f of r)for(const m of f.messages)if((m.ruleId||'').startsWith('jsx-a11y/'))n++;console.log(n)}catch{console.log(0)}})")"
  say "a11y: jsx-a11y violations: $COUNT"
  [ "$COUNT" -gt 0 ] && exit 1
  exit 0
fi

# 5) nothing detected — guide, don't fail
say "a11y: no a11y tooling detected. (skip)"
say "      Install one of:"
say "        npm i -D eslint-plugin-jsx-a11y   # static lint of JSX"
say "        npm i -D jest-axe                 # unit-level axe (contrast off in jsdom)"
say "        npm i -D @axe-core/playwright     # real-browser scan incl. contrast"
exit 0