---
name: a11y-component-check
description: Reviews UI component source (React, Vue, Svelte, Angular templates, plain HTML) for WCAG 2.2 AA failures such as missing labels, keyboard traps, focus handling, ARIA misuse, color contrast and target size, and reports findings with file and line or applies fixes. Use when the user asks for an accessibility, a11y or WCAG review of components or pages.
---

# Accessibility component check

Arguments: `$ARGUMENTS`. The first argument is a file or folder. If the word `fix` appears, apply fixes after reporting; otherwise report only.

## 1. Gather

- Read every component file in scope plus the shared primitives it uses (Button, Icon, Modal, Input).
- Find the color source: design tokens, CSS variables, Tailwind config. You need it for contrast.

## 2. Checklist

Cite the WCAG 2.2 success criterion for each finding.

**Semantics and names**
- Click handlers on `div`/`span` without role, tabindex and key handling -> use `button` or `a` (2.1.1, 4.1.2).
- Icon-only buttons and links have an accessible name via text, `aria-label` or `aria-labelledby` (4.1.2).
- Images: informative images have descriptive `alt`; decorative ones have `alt=""` (1.1.1).
- Form fields have a programmatic label; placeholder is not a label (1.3.1, 3.3.2).
- Error messages are associated with fields (`aria-describedby`) and not conveyed by color alone (3.3.1, 1.4.1).
- Headings follow a logical order; landmarks exist on page-level components (1.3.1).
- Links say where they go; no repeated "click here" (2.4.4).

**Keyboard and focus**
- Everything operable by mouse is operable by keyboard (2.1.1).
- No `tabindex` greater than 0 (2.4.3).
- Focus outline not removed without a visible replacement (2.4.7).
- Dialogs: focus moves into the dialog on open, stays inside while open, Escape closes it, and focus returns to the trigger on close (2.1.2, 2.4.3). A native `<dialog>` opened with `showModal()` handles part of this.
- Custom widgets (menus, tabs, comboboxes, listboxes) implement the expected keys from the ARIA Authoring Practices.
- Focused element is not hidden behind sticky headers or overlays (2.4.11).

**ARIA**
- Roles and `aria-*` attributes are valid for the element.
- No redundant roles (`<button role="button">`).
- `aria-hidden="true"` is not on focusable content or its ancestors.
- Toggle state exposed (`aria-expanded`, `aria-pressed`, `aria-selected`) and kept in sync with state.

**Visual**
- Contrast: compute the ratio when both colors are known. Text needs 4.5:1, large text (24px, or 18.66px bold) needs 3:1 (1.4.3). Icons, borders of inputs and focus indicators need 3:1 against adjacent colors (1.4.11). If a color is computed at runtime, mark the check "not verifiable statically".
- Target size: pointer targets at least 24x24 CSS px or with enough spacing (2.5.8).
- Text does not break at 200% zoom due to fixed heights on text containers (1.4.4).
- Animations honor `prefers-reduced-motion` (2.3.3 is AAA; flag as advisory).

**Dynamic content**
- Loading, success and error messages that appear without focus change are in a live region (`role="status"` or `aria-live`) (4.1.3).

## 3. Report

```
## Accessibility review: <scope>
| Severity | WCAG | Location | Problem | Impact | Fix |
```
Severity: High (blocks a task for keyboard or screen reader users), Medium (harder but possible), Low (advisory).

End with: "Static review only. Confirm with an automated scan (for example axe) and a manual keyboard and screen reader pass." Never state the code is compliant.

## 4. Fix (only if `fix` was given or the user asks)

- Prefer native elements over ARIA.
- Change shared primitives once instead of patching every usage, and tell the user.
- Keep visual design unchanged unless the fix requires it (contrast, focus styles); call out any visual change.