accessibility
Use when making a web UI conform to WCAG 2.2 Level AA — axe-core or Lighthouse a11y violations, keyboard operability, focus management, ARIA roles/names/live regions, contrast, tap-target size. NOT palette or visual intent (that is `design`), NOT test-runner setup (that is `testing-web`), NOT LCP/page-speed (that is `performance`).
ericrisco · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add ericrisco/rsc-harness --skill accessibility技能说明
name: accessibility
description: "Use when making a web UI conform to WCAG 2.2 Level AA — axe-core or Lighthouse a11y violations, keyboard operability, focus management, ARIA roles/names/live regions, contrast, tap-target size. NOT palette or visual intent (that is design), NOT test-runner setup (that is testing-web), NOT LCP/page-speed (that is performance)."
tags: [wcag, accessibility, a11y, aria, axe-core]
recommends: [testing-web, e2e-testing, design, react, performance]
origin: risco
Accessibility — Ship WCAG 2.2 AA, not vibes
The bar is conformance to WCAG 2.2 Level AA. "Looks fine to me" is not a measurement. Fix the semantics, scan what a machine can scan, then walk the part it can't.
The loop (your 30-second model)
Run these in order. Skipping a step front-loads rework.
- Native semantics first. A real
<button>ships focus, keyboard, and role for free. Most "a11y bugs" are a<div>doing a button's job. - Automated scan. axe-core catches roughly 57% of WCAG issues — missing labels, bad roles, contrast (in a real browser), duplicate ids. Cheap, run it every commit.
- Manual checklist for the rest. The other ~43% — keyboard order, focus traps, meaningful alt text, screen-reader flow — no engine can judge. A human (or you, deliberately) must.
Decision rule: never ship on a green axe run alone. A clean automated scan means "no machine-detectable failures," not "accessible." Treat it as necessary, never sufficient.
Legal stakes are real: the EU European Accessibility Act became enforceable 2025-06-28 for many consumer products and services, on top of EN 301 549 / ADA. AA is the line.
Rule 0 — reach for HTML before ARIA
The first rule of ARIA is: don't use ARIA. If a native element gives you the semantics and behavior, use it. Every role you add is behavior you now owe by hand — focus, keyboard, state.
<!-- Bad: zero keyboard, no role, no focus, no Enter/Space -->
<div class="btn" onclick="save()">Save</div>
<!-- Good: focusable, Enter/Space fire it, announced as "Save, button" -->
<button type="button" onclick="save()">Save</button>
| You want… | Use native… | Not… |
|---|---|---|
| A click action | <button type="button"> | <div role="button" onClick> |
| Navigation | <a href="…"> | <span onClick> + JS routing |
| Show/hide section | <details><summary> | hand-rolled aria-expanded |
| Form field | <input>/<select> | contenteditable div |
| Modal | <dialog> + showModal() | a div with role="dialog" |
Reach for ARIA only when no native element fits (tabs, comboboxes, toasts) — and then copy a vetted pattern (→ references/aria-patterns.md).
Semantics & accessible names
- One
<h1>per page. Headings describe structure; never skip a level (<h2>then<h4>) to get a font size — that's a CSS job. - Landmark every region:
<header> <nav> <main> <footer>. Exactly one<main>. Screen-reader users jump by landmark; a wall of<div>has no map. - Skip link first in the DOM so keyboard users escape the nav:
<a href="#main" class="sr-only-focusable">Skip to content</a>. - Accessible name precedence (what a screen reader announces), highest wins:
aria-labelledby→aria-label→ associated<label>/ element text →title. Don't stack them hoping one sticks; pick one source.
<!-- Bad: announced as just "button" -->
<button><svg aria-hidden="true">…</svg></button>
<!-- Good: announced as "Close dialog, button" -->
<button aria-label="Close dialog"><svg aria-hidden="true">…</svg></button>
A placeholder is not a label — it vanishes on input and many SRs ignore it. Use a real <label for>.
Keyboard operability
Everything a mouse can do, a keyboard must do.
- All interactive elements reachable and operable with Tab + Enter/Space. Native controls give this free; custom ones don't.
- Tab order follows the DOM. Fix order by reordering markup, not by patching
tabindex. - Never a positive
tabindex. Only0(in natural order) or-1(focusable by script, skipped by Tab). A positive value hijacks the whole page's order and breaks the next dev's mental model. - Visible focus, always (see next section). If you can't tell where focus is with the mouse unplugged, neither can the user.
Overlays (dialogs, menus, drawers) need focus management — three obligations:
- Move focus in when it opens (to the dialog or its first control).
- Trap focus inside while open — Tab from the last element wraps to the first.
- Escape closes, and focus returns to the trigger that opened it.
Composite widgets (menus, tabs, grids) use roving tabindex: one element is tabindex="0", the rest -1, arrow keys move the 0. Full keyboard tables per pattern — modal, disclosure, tabs, combobox, menu, toast → references/aria-patterns.md.
Visible focus & the WCAG 2.2 deltas
/* Bad: kills the focus ring with nothing in its place */
:focus { outline: none; }
/* Good: ring only for keyboard users, not mouse clicks */
:focus-visible { outline: 3px solid; outline-offset: 2px; }
WCAG 2.2 (W3C Recommendation, 2023-10-05) adds 9 success criteria and removes 4.1.1 Parsing. The six that matter at Level AA — know the numbers:
- 2.4.11 Focus Not Obscured (Minimum) — a focused element must not be fully hidden behind sticky headers/footers or cookie bars.
- 2.5.7 Dragging Movements — anything done by dragging (sliders, reorder, map pan) needs a single-pointer alternative (tap, buttons).
- 2.5.8 Target Size (Minimum) — interactive targets are at least 24×24 CSS px, unless spacing keeps a 24px-radius circle from overlapping a neighbor (the spacing exception). 44×44 is the com