# Add Accessibility Tests to Storybook

Yes. The agent adds the a11y addon, makes axe violations fail each story's test in Vitest, fixes or records what it finds and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-accessibility-tests/storybook/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Accessibility checks in Storybook are one addon and one parameter, and the work is in making them fail a build and then dealing with what they find. The agent first reads how stories are tested. In a project like chromaui/intro-storybook-react-template, `.storybook/main.ts` lists three addons, `@chromatic-com/storybook`, `@storybook/addon-docs` and `@storybook/addon-vitest`, and no accessibility addon. `vite.config.ts` already runs every story as a Vitest test in headless Chromium through the `storybookTest` plugin, with `.storybook/vitest.setup.ts` passing the preview's annotations to `setProjectAnnotations`. `.storybook/preview.ts` sets only control matchers. So the runner exists and nothing checks accessibility.

It adds `@storybook/addon-a11y` with the project's own CLI, `yarn exec storybook add @storybook/addon-a11y` (plain `yarn storybook` is this project's dev-server script), so the addon's version matches the installed `storybook`, and reads what the command changed: the entry in `main.ts`, and whether the Vitest setup file now includes the addon's annotations beside the preview's. It sets `parameters.a11y.test` to `'error'` in `preview.ts`, the setting that turns an axe violation into a failed test. Then it proves the wiring before trusting a green run. It adds a temporary story that renders a button with no accessible name, runs `yarn vitest run --project=storybook`, and expects that story to fail with axe's rule id in the output. If it passes, the checks are not running, and the agent fixes the setup file until the temporary story fails. The story is deleted before the commit.

With the check live, it runs every story and sorts the results. In this template there are three components to read against the output. `Button.tsx` renders a `<button>` with its `label` as text and takes any `backgroundColor`, which the stories expose as a colour control, so a story can pair white primary text with a light background. `Header.tsx` has an inline logo `<svg>` with no title beside an `<h1>`. `Page.tsx` has links that open in a new tab and a small `.tip` badge that `page.css` colours `#357a14` on `#e7fdd8` at 11 pixels. Axe runs after a story's `play` function finishes, so `Page`'s `LoggedIn` story is checked in its logged-in state as well as its first render.

Each violation gets one of three outcomes, and the agent says which. A defect in the component with an obvious fix, a missing name or an `aria-hidden` on a decorative image, is fixed in the component. A violation that needs a design decision, a brand colour that misses the contrast ratio, is not changed: that one story gets `a11y: { test: 'todo' }`, which reports the violation as a warning, with a comment naming the rule. A rule that does not apply to a component rendered alone is disabled for that story through the addon's rule configuration, with the reason. Nothing is switched off globally. It adds a `test` script for the Vitest project, since `package.json` has none, and runs `yarn tsc -b` and `yarn build-storybook`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add accessibility tests to this Storybook project so that an axe violation in any story fails a test. Read package.json, .storybook/main.ts, .storybook/preview.ts, .storybook/vitest.setup.ts, vite.config.ts and every component, stylesheet and story under src first, and state how stories run as tests today. Install with yarn install --immutable and install Chromium with yarn playwright install --with-deps chromium. Add @storybook/addon-a11y with the project's own Storybook CLI (yarn exec storybook add, since yarn storybook may be a script) so its version matches, and show what the command changed. Set parameters.a11y.test to 'error' in the preview. Prove the checks run: add a temporary story with an unnamed button, run the Vitest storybook project, confirm that story fails with an axe rule id, fix the setup until it does, then delete the temporary story. Run every story and list each violation with its story, rule id, impact and the element. For each one choose: fix the component when the fix is unambiguous (a missing accessible name, a decorative image not hidden, a missing label); set a11y.test to 'todo' on that story with a comment naming the rule when the fix needs a design decision such as changing a colour; or disable a single rule for a story when it does not apply to a component in isolation, with the reason. Do not disable a rule globally and do not change colours or copy. Add a test script that runs the storybook project if none exists. Run yarn tsc -b and yarn build-storybook. Open a pull request with the violations table and what was done about each, the diff of the config files explained, and the output of the test run, type check and build.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that adds the addon to `package.json` and `yarn.lock`, registers it in `.storybook/main.ts`, sets the `a11y` parameter in `.storybook/preview.ts`, adjusts the Vitest setup file if the checks needed it, and adds a `test` script. Component files change only where a violation had an unambiguous fix.

The description has a table with one row per violation: the story, axe's rule id and impact, the element, and the outcome, which is `fixed`, `todo` or `rule disabled for this story`. Rows marked `todo` are the team's backlog, each still visible as a warning in the story's Accessibility panel. Under the table are the output of the Vitest run, with the temporary failing story shown going red before it was removed, and the outputs of `yarn tsc -b` and `yarn build-storybook`.

A reviewer reads the `todo` rows first, because each one is a known violation the build will not catch until someone changes it back to `'error'`. They check that every disabled rule has a reason that holds for that component. They should also know what the check covers: axe finds what can be detected automatically in a rendered story. Focus order, keyboard traps and whether a screen reader announcement makes sense still need a person.

## Run it on every pull request that changes a component

Once the parameter is `'error'`, your own CI enforces the rule on every pull request by running the `test` script, and no agent is needed for that. The agent is for the pull request that fails. An automation in the Project that holds the repository, with a `github` trigger on `pull_request.labeled` and a label such as `a11y-fix` in `labels`, starts a run when a maintainer applies the label. Its prompt asks the agent to run the stories on that pull request's branch, fix the violations that have an unambiguous fix and open a pull request against the branch. The trigger puts the labelled pull request after the prompt and fills in nothing.

To work through the `todo` backlog, a second automation in the same Project, with a `schedule` trigger whose `cron` picks one morning a week, runs a prompt that takes the stories still marked `todo`, proposes the smallest change for each and opens one pull request for a designer to review.

## Why run it on Rush?

Turning the check on is quick. Reading the first run is not: every story in every component, each violation traced to an element and a rule, each fix rerun in a browser. That first pass is the reason the check so often stays in warning mode. An agent in its own sandbox does the whole pass in one sitting, with Chromium installed there and the outputs kept.

The result is also provable. The transcript at `GET /o/{org}/sessions/{id}/messages` holds the run in which the planted violation failed, so a reviewer knows the green run means the stories were checked and not that the checks were silently off. That failure mode is common with this addon, because a story run passes whether or not axe is wired in.

## Frequently asked questions

### Will it change our brand colours to pass contrast checks?

No. The prompt forbids changing colours or copy. A contrast violation is recorded on its story as `todo` with the rule id, and the pull request lists the foreground and background values axe measured so a designer can decide.

### What is the difference between 'error' and 'todo'?

They are values of the addon's `a11y.test` parameter. With `'error'` a violation fails the story's test in Vitest and in CI. With `'todo'` the violation is reported as a warning in the test output and the Accessibility panel and the test passes. The agent sets `'error'` for the project and `'todo'` only on stories with a known violation that waits on a decision.

### Does this replace an accessibility audit?

No. Axe checks rules that can be evaluated on rendered markup: names, roles, contrast, labels, landmark structure. It does not judge reading order, focus management across a flow, or whether an announcement is useful. The pull request says this in its description so nobody reads a green run as a full audit.

### We use the Storybook test runner, not the Vitest addon. Does it still work?

The agent reads which runner the project has and wires the check into that one. The steps differ, but the proof is the same: a story planted with a violation has to fail before the setup is accepted.

## More Storybook jobs

- [Run Storybook Stories as Tests in CI](https://getrush.ai/run/add-storybook-test-runner/storybook/)
- [Add Visual Regression Tests to Storybook Stories](https://getrush.ai/run/add-visual-regression-tests/storybook/)
- [Upgrade Storybook to the Latest Version](https://getrush.ai/run/upgrade-storybook/storybook/)

## The same job on other stacks

- [Add Accessibility Tests to a Vitest Component Suite](https://getrush.ai/run/add-accessibility-tests/vitest/)
- [Add Accessibility Tests to a Cypress Suite](https://getrush.ai/run/add-accessibility-tests/cypress/)
- [Add Accessibility Tests to a Lit Component](https://getrush.ai/run/add-accessibility-tests/lit/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
