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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Write the missing tests.
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.