Skip to main content

a11y-review

A structured accessibility audit of a user-specified scope (one or more files, a folder, or the focused component) against WCAG 2.1 AA (the production baseline) and RTL/Hebrew correctness. Ported from the cursor-rules bewith-a11y-standards; called by frontend-developer and design-system, and on demand.

When to useโ€‹

  • "a11y review", "check accessibility", "audit this component for a11y", or a pass before a UI PR.
  • After finishing a component/page, before review.

Inputsโ€‹

  1. Scope โ€” which file(s)/component. If missing, infer from the open/changed files or ask once.
  2. Display name โ€” the component name for the report title (derive from the file/export if not given).

Processโ€‹

  1. Read the code in scope โ€” every file; include the .styles.ts for contrast, focus, RTL/logical CSS, and outline.
  2. Walk the checklist (below). For pages vs leaf components, skip page-only items (e.g. <h1>, skip-link) when auditing an isolated component. Mark each line pass / issue / N/A with a one-line reason.
  3. Classify findings:
    • P1 โ€” Blocker โ€” prevents keyboard/AT use: missing accessible name on an interactive control, focus trap disabled on a modal, aria-hidden on a focusable element, a hard fail against a "must".
    • P2 โ€” Serious โ€” major barrier: misleading labels, missing aria-invalid/error association on forms, color-only meaning, wrong lang/dir for Hebrew, a chart with no text/table fallback, tabIndex > 0.
    • P3 โ€” Minor โ€” redundant ARIA, vague aria-live, doc-only gaps that don't block users today.
  4. For each issue: Where (file + element/line), Why (cite the checklist item), Fix (a minimal Before/After TSX snippet).
  5. If nothing is wrong, say so + list optional P3 quick-wins only if any.

The checklist (WCAG 2.1 AA + RTL)โ€‹

  • Contrast โ€” normal text โ‰ฅ 4.5:1, large text โ‰ฅ 3:1, UI/graphical objects โ‰ฅ 3:1. Never hard-code hex that bypasses the MUI theme palette; verify overrides with a tool.
  • Keyboard โ€” every interactive element is reachable + operable by keyboard; visible focus state; logical focus order; no positive tabIndex.
  • Names/roles โ€” every control has an accessible name (label / aria-label / aria-labelledby); correct semantic role; icons-only buttons have a name.
  • Forms โ€” labels associated; errors announced (aria-invalid + aria-describedby); required state conveyed non-visually.
  • Images/media โ€” alt (translated); decorative images alt=""; charts have a text/table fallback.
  • Color โ€” never color-only meaning; pair with text/icon/pattern.
  • Live regions โ€” aria-live used deliberately, not noisily.
  • Modals/overlays โ€” focus trap on open, restore on close; aria-hidden not on focusable content.
  • RTL/Hebrew โ€” logical CSS (inline-start/-end, not left/right); correct dir/lang; layout mirrors; verified in both directions.
  • Motion/touch โ€” respect prefers-reduced-motion; touch targets โ‰ฅ the WCAG 2.2 minimum.

Output formatโ€‹

## a11y review: <ComponentName>

**Scope:** <files>
**Verdict:** <N blockers ยท M serious ยท K minor | clean>

### P1 โ€” Blockers
- **<title>** โ€” Where: `<file>:<el>` ยท Why: <checklist item> ยท Fix:
  ```tsx
  // before โ†’ after

P2 โ€” Seriousโ€‹

  • โ€ฆ

P3 โ€” Minor (optional)โ€‹

  • โ€ฆ

Lead with P1; if clean, say so and list only P3 quick-wins.

## Cross-references

- [`frontend-developer`](https://github.com/bewith-dev/bewith-docs/blob/master/.claude/agents/frontend-developer.md) / [`design-system`](https://github.com/bewith-dev/bewith-docs/blob/master/.claude/agents/design-system.md) โ€” call this skill; design-system bakes AA into components, frontend wires it into pages.
- [`i18n-localization`](../../agents/i18n-localization.md) โ€” RTL/`dir` + translated `aria-*`/`alt` overlap.
- Source: cursor-rules `bewith-a11y-review` skill + `bewith-a11y-standards.mdc` (WCAG 2.1 AA, MUI palette, RTL ยง13).