Claude Code rules for WCAG testing

## Accessibility (WCAG 2.2 AA — non-negotiable)

- **Native element first.** `<button>` for actions, `<a href>` for
  navigation, `<label for>` for every input, `<table>` for tabular data.
  A `<div>` with `onClick` and `role="button"` is a rewrite, not a fix:
  it has to reimplement focus, Enter, Space, and disabled state.
- **ARIA only when no native element does the job**, and never to patch a
  wrong one. `aria-label` on an icon-only button: required. On a button
  that already has visible text: noise that overrides the label a user
  reads aloud.
- **Focus is always visible.** `outline: none` is allowed only in the same
  change that ships a replacement indicator at 3:1 against both adjacent
  surfaces (1.4.11). Never remove a focus ring to fix a design review.
- **No positive `tabIndex`.** `0` to make a custom control focusable, `-1`
  for a programmatic focus target, nothing else (2.4.3).
- **Every interactive target is 24x24 CSS px or has 24px of clear spacing**
  (2.5.8). Icon buttons get padding, not a smaller icon.
- **One `<h1>` per page, no skipped levels**, headings describe the section
  rather than decorate it (1.3.1, 2.4.6).
- **Images:** meaningful ones get alt text saying what the image
  communicates in this context; decorative ones get `alt=""`. A missing
  `alt` attribute is never correct.
- **State changes are announced.** Field errors tie to the input with
  `aria-describedby`; async results land in a live region (4.1.3). A
  toast the screen reader never mentions did not happen.
- **Colour is never the only carrier of meaning** (1.4.1) — pair it with
  text, an icon, or a shape.
- **Contrast is computed, never eyeballed**, compositing alpha text over
  its real background: 4.5:1 body text, 3:1 for large text and for UI
  boundaries. This palette is already solved — see the token rules above;
  `tk-linen/80` on teal composites to 4.07:1 and fails, `/90` passes.
- **Never tween opacity on text.** Contrast is computed from whatever
  opacity the audit samples, so a crossfade fails colour-contrast
  nondeterministically. Animate `transform` only.
- **All motion respects `prefers-reduced-motion`**, including CSS
  animation in `globals.css`.
- **Never silence a check to make it pass.** No `disableRules`, no
  `eslint-disable jsx-a11y`, no dropping a route from the axe run. If you
  believe a violation is a false positive, leave it failing and say so.

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

// Every route a user can reach without an account. Add the route the day
// it ships; an unlisted route is an untested route.
const ROUTES = ["/", "/services/web-development", "/knowledge-base", "/contact"]

for (const route of ROUTES) {
  test(`axe ${route}`, async ({ page }) => {
    await page.goto(route)
    const { violations } = await new AxeBuilder({ page })
      .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"])
      .analyze()

    // Assert on the readable list, not a count: a failing test that names
    // the rule and the selector is a fix; "expected 3 to be 0" is a puzzle.
    expect(violations.flatMap((v) =>
      v.nodes.map((n) => `${v.id} [${v.impact}] ${n.target.join(" ")} — ${v.help}`)
    )).toEqual([])
  })
}

// 1.4.10 Reflow: 400% zoom on a 1280px screen is a 320px viewport.
test("no horizontal scroll at 320px", async ({ page }) => {
  await page.setViewportSize({ width: 320, height: 800 })
  await page.goto("/")
  const overflow = await page.evaluate(
    () => document.documentElement.scrollWidth - document.documentElement.clientWidth
  )
  expect(overflow, "something is wider than the viewport at 320px").toBe(0)
})

#!/usr/bin/env bash
payload="$(cat)"
file="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty')"
content="$(printf '%s' "$payload" | jq -r '.tool_input.new_string // .tool_input.content // empty')"

case "$file" in
  *.tsx|*.jsx|*.css)
    if printf '%s' "$content" | grep -qE 'outline:[[:space:]]*(none|0)' &&
       ! printf '%s' "$content" | grep -qE 'focus-visible|outline-offset|box-shadow'; then
      echo "outline: none with no replacement focus indicator (WCAG 2.4.7)." >&2
      echo "Style :focus-visible instead, at 3:1 against both surfaces." >&2
      exit 2
    fi
    if printf '%s' "$content" | grep -qE 'tabIndex=\{?"?[1-9]'; then
      echo "Positive tabIndex breaks focus order (WCAG 2.4.3)." >&2
      echo "Use 0 to make a control focusable, -1 for a focus target." >&2
      exit 2
    fi
    if printf '%s' "$content" | grep -qE 'eslint-disable.*jsx-a11y|disableRules'; then
      echo "Silencing an accessibility check is not a fix. Leave it failing." >&2
      exit 2
    fi
    ;;
esac
exit 0

---
description: Run the accessibility checks a machine can run, then print my checklist
argument-hint: [route, defaults to /]
allowed-tools: Bash(npm run test:a11y), mcp__playwright__*
---

Run `npm run test:a11y` and report every violation verbatim — rule id,
impact, and selector. Do not summarise to a count and do not fix anything
by adding ARIA or disabling a rule.

Then, with the browser MCP on $ARGUMENTS (default `/`):

1. Tab from the top through every interactive element. Report the first
   element with no visible focus indicator, any element that takes focus
   but does nothing, and any point where focus order jumps out of reading
   order.
2. Emulate `prefers-reduced-motion: reduce` and report anything still
   moving.
3. Set the viewport to 320x800 and report any horizontal overflow.

Finish by printing this checklist for me. Never tick a box yourself:

- [ ] VoiceOver over the changed area: does every control announce a name,
      a role, and its state?
- [ ] Read the alt text aloud in place of the image — does the sentence
      still carry the same information?
- [ ] Disable CSS: is the reading order still the order of the content?
- [ ] Trigger every error state: is the message specific, and does focus
      or an announcement take you to it?
- [ ] Is anything conveyed by colour alone?