Give the agent a failing Storybook story, not a vague “fix a11y”

I used to type “make this component accessible” into the agent and hope for the best. It would sprinkle aria-labels, flip a couple of roles, and declare victory. CI still failed. Reviewers still found focus traps. The agent wasn’t wrong about intent — I had given it a vibe instead of a failing unit.

What actually works: hand the agent a red Storybook a11y story (or the axe / Accessibility addon output for that story) and ask for the smallest fix that turns it green. Same pattern as pasting a Playwright failure — artifacts beat slogans.

Why “fix a11y” produces fake green

Vague a11y prompts invite:

• Decorative aria-labels on elements that already have visible text
• Role swaps that silence axe but break keyboard order
• “Skip to content” links that aren’t in the story under test
• Color-contrast “fixes” that only work on the agent’s assumed theme

Agents optimize for the prompt you wrote. If the prompt is “be accessible,” they’ll invent compliance. If the prompt is “story Button/Loading fails rule button-name — fix only that,” they have a target.

The artifact I paste now

I keep stories that are supposed to fail until fixed — or I run the a11y addon / @storybook/addon-a11y / axe-playwright against a specific story id and paste the raw report.

## Storybook a11y failure (paste raw)

Story id: ui-button--loading
Story file: src/components/Button/Button.stories.tsx
Component: src/components/Button/Button.tsx

<<< paste axe / addon violations: rule id, nodes, html, failureSummary >>>

Goal: smallest change so THIS story passes a11y for the listed rules
Out of scope: rewriting the design system, adding new variants, “improving” unrelated stories
Do not: invent aria-labels that duplicate visible text; do not remove interactive roles to silence axe

That “out of scope” line matters. Left alone, agents will refactor the Button API mid-fix.

Make the failure cheap to reproduce

A few habits that keep this loop under five minutes:

1. Name stories after states that break a11y — Loading, IconOnly, DisabledWithTooltip, ErrorInline. Happy-path Default rarely teaches the agent anything.
2. Run one story in CI (or locally) with axe attached — don’t wait for a full visual suite.
3. Prefer rule ids in the prompt (button-name, label, color-contrast, focus-order) so the agent doesn’t “fix” a different problem.
4. Include the rendered HTML snippet from the report when the DOM is the bug (extra wrappers, missing for/id).

Example constraint I reuse:

You are fixing ONE Storybook a11y failure.

Rules:
- Change the component or the story controls — prefer the component if the bug is real
- Keep visible labels; do not hide text and replace it with aria-only labels
- Icon-only buttons need an accessible name that matches the UI meaning
- If contrast fails, use design tokens / existing theme vars — do not hardcode hex the design system doesn’t own
- If the failure looks like a false positive from the test harness, STOP and say so — do not paper over it

What good agent output looks like

I want:

• Which rule failed and why in one sentence
• The minimal diff (often 5–20 lines)
• How to re-check (storybook --test / addon panel / axe on that story id)
• What they deliberately did not change

I reject “added aria-label everywhere.” That’s the vibe fix again.

Pair this with review, not instead of it

A green Storybook story is necessary, not sufficient. Humans still catch:

• Focus order that axe doesn’t flag as broken but feels wrong in a modal
• Live regions that announce too often
• Mobile zoom / dynamic type issues outside the story viewport

So the workflow is: agent clears the measurable violation → you tab through the story once → then merge. Don’t skip the tab-through because axe went quiet.

A tiny checklist before you prompt

• [ ] Story id + file path
• [ ] Raw violation list (rule + node)
• [ ] Theme / mode if contrast is involved (light/dark)
• [ ] Explicit “do not invent labels / do not delete assertions”
• [ ] Re-run command for that story only

What I stopped doing

• Pasting Figma screenshots and saying “make it WCAG”
• Asking for a full a11y audit of a folder in one shot
• Accepting blanket aria-hidden on icons without checking the button name
• Treating addon green as “we’re done” without a keyboard pass

Give the agent a failing story. Get a patch you can re-run. Save the sermons for design critique — the model is much better at turning red axe output green than at inventing your accessibility policy from a slogan.