/validating-accessibility

name: validating-accessibility
description: >-
  Use this skill when creating, modifying, or reviewing any .tsx component in apps/web, even if
  the user doesn't mention "accessibility." Covers semantic HTML, aria labels, navigation landmarks,
  forms, dialogs, and keyboard navigation. Trigger on: adding buttons, links, toggles, icons, or
  any interactive element; building or editing forms; adding dialogs or modals; reviewing UI code.
  Includes inline verification patterns for scanning violations. Not for styling or layout changes
  that don't involve interactive elements.
metadata:
  internal: true

Accessibility Checklist

Every UI component in `apps/web` must meet these standards. No partial compliance.

Gotchas

• **`role="button"` divs may exist in the codebase** -- fix them when touching affected files. `<TableHead>` elements with `role="button"` for sortable columns are acceptable.
• **Nested interactive elements** -- when replacing a `<div role="button">` that contains a child `<button>` (e.g., a copy button inside a collapsible toggle), do not just swap the outer div to `<button>`. That creates invalid nested buttons. Instead, restructure into sibling elements: a toggle `<button>` and a separate action `<button>` side by side in a flex container.
• **Standalone inputs outside react-hook-form need manual ID pairing** -- use `useId()` with `htmlFor`/`id`. The shadcn `<FormField>` handles this automatically, but raw `<Input>` does not.
• **AlertDialog vs Dialog** -- use `AlertDialog` for destructive confirmations (requires `AlertDialogTitle` + `AlertDialogDescription`). Use `Dialog` for content/forms. Never build custom modal overlays.
• **Icon-only buttons without `aria-label`** are common in new code. Every icon-only button needs one, and it must include context: `Delete API key ${keyName}`, not just "Delete".

Semantic HTML

Use native elements. Never recreate `<button>` behavior with `<div role="button">` + keyboard handlers.

| Interaction | Element | | ---------------- | ------------------------------------------------------ | | Clickable action | `<button>` or `<Button>` from `@/components/ui/button` | | Navigation link | `<Link>` (Next.js) or `<a>` | | Navigation group | `<nav>` with descriptive `aria-label` | | Item list | `<ul>`/`<ol>` + `<li>` | | Section heading | `<h1>`-`<h6>` in order, never skip levels |

Aria Labels

Every interactive element without visible text needs `aria-label` with both action AND target:

<Button size="icon" aria-label={`Delete API key ${keyName}`}>
  <Trash2 className="h-4 w-4" />
</Button>

<Switch aria-label={`${enabled ? "Disable" : "Enable"} skill ${skillName}`} />

Prefer state-aware labels ("Copied!" vs "Copy"). Buttons with visible text skip `aria-label`.

**Reference implementations:** `copy-button.tsx` (state-aware), `context-attachment-badge.tsx` (contextual remove), `thread-table-header.tsx` (sort state) -- all in `apps/web/components/`.

Navigation Landmarks

Wrap navigation groups in `<nav>` with a unique `aria-label` per region on the page.

Forms

Use shadcn Form components from `@/components/ui/form` (`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormMessage`). They handle ID generation, label association, `aria-describedby`, and `aria-invalid` automatically.

For standalone inputs outside react-hook-form, pair `useId()` with `htmlFor`/`id`. Never use placeholder as label substitute.

Keyboard Navigation

• Only `tabIndex={0}` or `tabIndex={-1}` (never positive values)
• Never remove focus outlines
• Prefer `<button>` over manual Enter/Space handlers

Verification

Scan `apps/web/components` for common violations. For each check, grep for the pattern and fix any matches found.

Check 1: `role="button"` on non-button elements

Search for `role="button"` in `.tsx` files. Flag `<div` or `<span` elements with this attribute; they should be `<button>` or `<Button>` instead. `<TableHead>` elements with `role="button"` for sortable columns are acceptable.

**Pattern:** `role="button"`

Check 2: `<div onClick>` patterns

Search for `<div` elements with `onClick` handlers. These should use `<button>` instead for proper keyboard support.

**Pattern:** `<div[^>]*onClick`

Check 3: Positive tabIndex values

Search for `tabIndex` with values greater than 0. Only `tabIndex={0}` and `tabIndex={-1}` are allowed.

**Pattern:** `tabIndex={[1-9]`

Check 4: Icon buttons missing aria-label

Search for `size="icon"` in `.tsx` files. For each match, check surrounding lines (5-10 above and below) for `aria-label` on the same `<Button>` element or an `sr-only` span. Flag buttons that have neither.

**Pattern:** `size="icon"` without nearby `aria-label`

Manual checks

These cannot be detected by pattern matching:

• [ ] Form inputs have associated `<label>` elements
• [ ] Navigation groups use `<nav>` with unique `aria-label`
• [ ] Dialogs use Radix-based components (AlertDialog or Dialog)
• [ ] Focus outlines intact