LazyCats-dev/ao3-podfic-posting-helper / .agent/skills/frontend-a11y
frontend-a11y
VerifiedWrite minimal, accessible web UI without over-engineering, adapting to whatever stack the project uses — React, Vue, Svelte, Angular, web components, or plain HTML. Use this skill on every project and every task that writes or reviews markup or components, builds forms, adds interactive elements like buttons, dialogs, accordions, or tabs, or audits code for accessibility — even when the user never mentions accessibility, and even inside a framework, CMS, or design system. It's non-negotiable regardless of project type, stack, or deadline. About to reach for ARIA attributes, a dialog library, a focus-trap package, or a headless UI component? Use this skill first.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 27.7 KB |
| evals/evals.json | config | 12.9 KB |
| references/angular.md | markdown | 2.5 KB |
| references/aria.md | markdown | 503.4 KB |
| references/css.md | markdown | 7.4 KB |
| references/patterns.md | markdown | 8.3 KB |
| references/react.md | markdown | 3.7 KB |
| references/standards.md | markdown | 1.2 KB |
| references/svelte.md | markdown | 2.4 KB |
| references/vue.md | markdown | 2.9 KB |
| references/wcag.json | config | 141.1 KB |
| references/web-components.md | markdown | 2.8 KB |
references/react.md
View on GitHub# React (and Next.js / Preact)
The HTML/CSS rules in `SKILL.md` all hold — React renders the same DOM. This file covers only what changes when the source is JSX. Native `<button>`, `<dialog>`, `<details>`, and `<label>` work exactly as documented; prefer them here too.
## Attribute translation
JSX renames a few HTML attributes and passes the rest through untouched:
- `class` → `className`, `for` → `htmlFor`.
- `aria-*`, `data-*`, and `role` are written **as-is** (kebab-case): `aria-expanded`, `aria-labelledby`. They render to the DOM unchanged, so every ARIA rule in `SKILL.md` applies verbatim.
- Boolean-ish ARIA takes a string, not a JS boolean, when the spec expects a token: `aria-disabled={isBusy ? "true" : "false"}` reads cleaner than relying on coercion, and `hidden` is a real boolean prop.
```jsx
<button type="button" aria-expanded={open} aria-controls="menu" aria-label="Menu">
<svg aria-hidden="true">...</svg>
</button>
```
## Generate ids with useId
`aria-labelledby`, `aria-describedby`, and `htmlFor` need stable, unique ids. Hand-rolled ids collide across component instances and mismatch between server and client render (a hydration bug). Use `useId()`.
```jsx
const hintId = useId();
return (
<>
<input aria-describedby={hintId} />
<p id={hintId}>Must be at least 8 characters.</p>
</>
);
```
## Don't put onClick on a div
The single most common React a11y regression: a clickable `<div>`/`<span>`. It's not focusable, not keyboard-operable, and absent from the accessibility tree. Use a real `<button>` (see "Use Native Elements"). If you truly can't, you owe it `role`, `tabIndex={0}`, and `onKeyDown` for Enter/Space — which is strictly more code than a button.
## Fragments keep markup valid
Wrapper `<div>`s break required parent/child relationships — a `<div>` between `<ul>` and `<li>`, or inside `<tr>`, is invalid and confuses assistive tech. Use `<>...</>` to group without emitting an element.
## Route changes must move focus and announce
Client-side navigation swaps content without a page load, so focus stays where it was (often on a now-gone link) and screen readers announce nothing. On every route change:
- Move focus to the new page's `<h1>` or `<main>` (give it `tabIndex={-1}` and `.focus()` in an effect), **or** render a visually-hidden `role="status"` live region and write the new page title into it.
- Ensure each route renders a unique `<title>` (Next.js: the Metadata API / `next/head`) and a single `<h1>`.
```jsx
useEffect(() => {
headingRef.current?.focus();
}, [pathname]);
```
## Manage focus with refs, not the DOM
Reach for elements with `useRef` + `useEffect`, never `document.getElementById` — the latter fights React's ownership of the DOM and runs before paint. This is how you call `dialogRef.current.showModal()` on a native `<dialog>`, or move focus into a newly opened panel.
## dangerouslySetInnerHTML is an XSS hole
It bypasses React's escaping. Avoid it; render data as children instead. If you genuinely must inject HTML, sanitize it first (e.g. DOMPurify) — unsanitized user or CMS content is a security bug, not just an a11y one.
## Portals for overlays
Render modals/toasts through `createPortal` to `document.body` so a `overflow:hidden` or `transform` ancestor can't clip them or trap focus. Still use native `<dialog>` + `showModal()` inside the portal — it keeps the built-in focus trap, Escape handling, and inertness.
## Live regions must be mounted before they update
A `role="alert"`/`role="status"` region is only announced when text is inserted into an **already-present** region. Conditionally mounting the region at the same moment you fill it (`{msg && <div role="alert">{msg}</div>}`) often fires nothing. Keep the region rendered and change its text content instead.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |