跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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.

  1. Native semantics first. A real <button> ships focus, keyboard, and role for free. Most "a11y bugs" are a <div> doing a button's job.
  2. 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.
  3. 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. Only 0 (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:

  1. Move focus in when it opens (to the dialog or its first control).
  2. Trap focus inside while open — Tab from the last element wraps to the first.
  3. 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
阅读完整来源 ↗