AI-Generated Code Accessibility: React Fix Checklist

Give every interactive element a name a screen reader can announce.

// ❌ Typical generated code
<button onClick={onClose}><XIcon /></button>
<a href={`/posts/${post.slug}`}>Read more</a>

// ✅ Fixed
<button type="button" onClick={onClose} aria-label="Close dialog">
  <XIcon aria-hidden="true" />
</button>
<a href={`/posts/${post.slug}`}>
  Read more<span className="sr-only"> about {post.title}</span>
</a>

A visible label, a programmatic link to the error, and an invalid state.

<label htmlFor="email">Email address</label>
<input
  id="email"
  name="email"
  type="email"
  autoComplete="email"
  aria-invalid={Boolean(errors.email)}
  aria-describedby={errors.email ? "email-error" : undefined}
/>
{errors.email && (
  <p id="email-error" role="alert">{errors.email}</p>
)}

A skip link only works if the target can receive focus.

// layout.tsx
<a href="#main" className="sr-only focus:not-sr-only">Skip to content</a>
<Header />
<main id="main" tabIndex={-1} className="outline-none">
  {children}
</main>

Paste into CLAUDE.md (Claude Code) or your agent's rules file.

## Accessibility (required for all UI changes)
- Every <button> and <a> has a visible text name or aria-label. Icons get aria-hidden="true".
- Every form field has a <label htmlFor>. Errors use aria-describedby + aria-invalid.
- Use native elements first: <button>, <select>, <dialog> with showModal().
- Skip-link targets must be focusable (tabIndex={-1}).
- Never set maximum-scale or user-scalable=no.
- Interactive targets are at least 24x24px. Body text contrast is at least 4.5:1.
- After UI changes, run `npm run test:a11y` and fix every violation before finishing.

tests/a11y.spec.ts: scan the checkout page before and after a failed submit.

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

const WCAG = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];

test("checkout has no WCAG A/AA violations", async ({ page }) => {
  await page.goto("/checkout");
  let results = await new AxeBuilder({ page }).withTags(WCAG).analyze();
  expect(results.violations).toEqual([]);

  // Interaction states hide half the issues: test them too.
  await page.getByRole("button", { name: "Place order" }).click();
  results = await new AxeBuilder({ page }).withTags(WCAG).analyze();
  expect(results.violations).toEqual([]);
});