# Accessibility Addon (a11y) Gating

Use this reference when reviewing or configuring the `a11y` addon's `parameters.a11y.test` gating behavior, axe-core rule configuration, or diagnosing why accessibility violations aren't failing CI despite the addon being installed. For test-runner/Chromatic wiring, see `test-runner-and-chromatic-wiring.md`. For dark mode/RTL/reduced-motion coverage of the stories being checked, see `theme-and-variant-coverage.md`.

> Version note: `parameters.a11y.test` and the `initialGlobals`/`globals.a11y.manual` flag are current documented shapes; the addon's config surface has changed across Storybook majors (notably the move to `parameters.a11y.test` gating via the Vitest addon or test-runner). Verify the exact parameter names against the installed Storybook version via Context7 (`/storybookjs/storybook`) or the official docs before writing a config diff.

## What people get wrong

The common bad assumption is:

> The `a11y` addon is installed, so accessibility violations block merge.

That is false by default. The addon being installed only means violations are visible in the Storybook UI's a11y panel during manual browsing. Whether a violation actually fails a build depends entirely on the `parameters.a11y.test` value, which is `undefined` (no enforced test behavior) unless explicitly set.

## Officially grounded shape

The accessibility addon is built on `axe-core`; its configuration options largely map to axe-core's own API surface:

| Property | Default | Description |
|---|---|---|
| `parameters.a11y.context` | `'body'` | Context passed to `axe.run` -- which elements checks run against. |
| `parameters.a11y.config` | (empty) | Configuration passed to `axe.configure()` -- most commonly used to enable/disable individual rules. |
| `parameters.a11y.options` | `{}` | Options passed to `axe.run` -- can adjust which rulesets are checked. |
| `parameters.a11y.test` | `undefined` | Determines test behavior when run with the Vitest addon or the test-runner. |
| `globals.a11y.manual` | `undefined` | Set `true` to prevent a story from being automatically analyzed when visited. |

`parameters.a11y.test` accepts exactly three documented values:

- `'off'` -- do not run accessibility tests automatically (manual panel review is still possible).
- `'todo'` -- run accessibility tests; violations surface as a **warning** in the Storybook UI, not a failing test.
- `'error'` -- run accessibility tests; violations surface as a **failing test** in the Storybook UI and CLI/CI.

This parameter can be set at the project level (`.storybook/preview.ts`), the component level (a story file's meta/default export), or an individual story level -- so a project can have global `'error'` gating with a deliberate `'todo'` or `'off'` override on a specific known-noisy story, or the reverse (global `'todo'` with `'error'` only on a few critical components). Either shape is valid; the review's job is to confirm which shape actually exists and whether it matches intent.

For test-runner-based enforcement (as opposed to the Vitest addon), the documented pattern injects and configures axe via the `axe-playwright` package inside the `preVisit`/`postVisit` hooks:

```typescript
import type { TestRunnerConfig } from '@storybook/test-runner';
import { getStoryContext } from '@storybook/test-runner';
import { injectAxe, checkA11y, configureAxe } from 'axe-playwright';

const config: TestRunnerConfig = {
  async preVisit(page) {
    await injectAxe(page);
  },
  async postVisit(page, context) {
    const storyContext = await getStoryContext(page, context);
    await configureAxe(page, {
      rules: storyContext.parameters?.a11y?.config?.rules,
    });
    const element = storyContext.parameters?.a11y?.element ?? 'body';
    await checkA11y(page, element, {
      detailedReport: true,
      detailedReportOptions: { html: true },
    });
  },
};
export default config;
```

Note this is a distinct enforcement path from `parameters.a11y.test` (which governs the addon's own Vitest-addon/test-runner-integrated behavior) -- a project wiring axe manually through `axe-playwright` in `preVisit`/`postVisit` is not automatically respecting `parameters.a11y.test`, and the two should not be assumed to be reading the same configuration unless the `postVisit` hook explicitly reads `storyContext.parameters?.a11y?.config`.

## Non-negotiable design rules

1. **Never credit "a11y addon is installed" as accessibility gating without confirming `parameters.a11y.test` is `'error'`** (or that a manual `axe-playwright` wiring in `postVisit` calls `checkA11y` in a way that actually fails the test runner process, not just logs a report). `'todo'` and the addon's default unset state are advisory only.
2. **Confirm which enforcement path is in use** -- `parameters.a11y.test` via the Vitest addon/test-runner integration, or a manually wired `axe-playwright` `preVisit`/`postVisit` pair -- before writing a config diff; they are configured differently and a fix aimed at the wrong path silently does nothing.
3. **Do not recommend disabling a rule globally via `parameters.a11y.config.rules` to silence a violation** without first confirming the violation is a false positive for the actual DOM/ARIA semantics in question, not a real defect the team wants to suppress.
4. **Respect `globals.a11y.manual: true` as an intentional opt-out signal**, not dead config -- confirm with the team whether a story marked `manual` is deliberately excluded (e.g., because it renders non-deterministic third-party content) before treating its absence from automated coverage as a gap to fix by removing the flag.
5. **Scope `parameters.a11y.context` deliberately** when a story wraps content the team doesn't own (e.g., a third-party embed) -- running the full-page `axe.run` against unowned markup produces violations the team cannot fix and trains reviewers to ignore the panel.

## Safe verification targets

- `.storybook/preview.ts` -- confirm the project-level `parameters.a11y.test` value and any `initialGlobals.a11y.manual` default.
- Individual story files -- confirm component/story-level `parameters.a11y` overrides match documented intent (not accidental inheritance).
- `.storybook/test-runner.ts` -- if `axe-playwright` is used, confirm `preVisit` calls `injectAxe` and `postVisit` calls `checkA11y` with a real failure path (not a report-only call whose result is discarded).
- CI logs from a Storybook build with a known-injected violation -- the most reliable evidence that gating is real is a CI run that actually failed on a deliberate violation, not just config inspection.

## When to push back

Push back if the user asks for:

- treating `'todo'` as sufficient gating because "it shows up in the UI,"
- disabling a specific axe rule project-wide to unblock a single component's merge, as a permanent fix rather than a scoped, justified exception,
- adding the `a11y` addon without setting `parameters.a11y.test` anywhere, and calling that "accessibility testing is now covered."

Visibility in a panel is not the same as a merge-blocking test.

# Test-Runner and Chromatic Wiring

Use this reference when reviewing or configuring the Storybook `test-runner`'s `preVisit`/`postVisit` hooks, its CI invocation, Chromatic project setup, or when a user is unclear on the difference between the two. For axe-core/a11y gating specifics, see `accessibility-addon-gating.md`. For theme/variant coverage, see `theme-and-variant-coverage.md`.

> Version note: hook signatures and helper exports (`getStoryContext`, `waitForPageReady`) live in `@storybook/test-runner` and have evolved across Storybook majors. Verify exact exports and signatures against the installed version via Context7 (`/storybookjs/storybook`) or the official docs before citing one as available.

## What people get wrong

The common bad assumption is:

> "We have Storybook tests" means visual regressions are covered.

That is not necessarily true. A project can have:

- a `test-runner` that only asserts `expect(canvas).toBeInTheDocument()`-style smoke checks, with no image snapshot step at all,
- Chromatic connected but running in "notify only" mode with no branch protection requiring the check,
- both tools installed, but neither one covering the components the team actually considers visually critical.

"Storybook tests exist" and "visual regressions are gated" are different claims. Confirm which one is actually true before crediting a project with coverage.

## Officially grounded shape

Per Storybook's own documentation, the `test-runner` and Chromatic are described as complementary, not redundant:

- **The `test-runner`** is a generic testing tool, built on Playwright, that can run locally or in CI and be configured or extended to run "all kinds of tests." It exposes a `preVisit`/`postVisit` hook API in `.storybook/test-runner.ts`:
  - `setup()` runs once before the test runner starts.
  - `preVisit(page, context)` runs before a story is rendered; `page` is Playwright's page object, `context` carries the story's id/title/name.
  - `postVisit(page, context)` runs after a story is fully rendered; this is where image-snapshot assertions and `getStoryContext(page, context)` (to read the story's full parameters/args/argTypes) typically go.
  - `waitForPageReady(page)` is a documented helper for image-snapshot testing that waits for the page -- including async items like images and fonts -- to finish loading before a screenshot is taken; skipping it is a common source of flaky screenshot diffs on slow-loading assets.
- **Chromatic** is a cloud-based service that runs visual and interaction tests without the team having to set up the test-runner itself. It syncs with the git provider and manages access control for private projects. Storybook's own docs describe using the test-runner locally and Chromatic in CI as a valid pairing: use Chromatic for visual and component tests, and the test-runner for other custom tests.
- Chromatic project configuration lives in `chromatic.config.json` (fields such as `projectId`, `buildScriptName`, `zip`, `debug`) rather than being hardcoded into CI invocation flags.

## Non-negotiable design rules

1. **Do not credit "Storybook tests pass" as visual coverage without confirming a diffing step exists.** A `test-runner` config with no image-snapshot assertion in `postVisit`, and no Chromatic connection, has zero visual-regression coverage regardless of how many stories exist.
2. **Confirm the check is required, not advisory.** A connected Chromatic project that is not set as a required status check on the default branch's protection rules can be bypassed by any merge; "connected" and "gating" are different claims and must be verified separately (repo evidence: branch protection config, not just Chromatic dashboard presence).
3. **Use `waitForPageReady` (or an equivalent explicit wait) before any screenshot assertion in `postVisit`.** Taking a screenshot before fonts/images finish loading produces non-deterministic diffs that erode trust in the whole suite and lead teams to loosen thresholds instead of fixing the real timing bug.
4. **Do not run the test-runner without `preVisit`/`postVisit` review when adding a11y or visual checks.** These hooks are the only place axe injection and screenshot assertions can run per-story with access to `getStoryContext`; bolting checks on outside this API produces inconsistent coverage across stories.
5. **When both the test-runner and Chromatic exist, confirm they aren't duplicating the same check with different tolerances.** Two visual-diff mechanisms with different pixel-diff thresholds on the same components is a maintenance and false-confidence problem, not defense in depth.

## Safe verification targets

- `.storybook/test-runner.ts` (or `.js`) -- confirm `preVisit`/`postVisit` hooks exist and what they assert.
- `chromatic.config.json` and the CI workflow step invoking `chromatic` -- confirm `projectId` is present and the step is wired into a required CI job, not an optional/manual trigger.
- Branch protection rules (repo settings, not just CI YAML) -- confirm the Chromatic and/or test-runner CI check is marked required before merge.
- `package.json` `test-storybook` script and its CI invocation flags (e.g. `--ci`, coverage flags) -- confirm it's actually called in CI, not just defined locally.

## When to push back

Push back if the user asks for:

- widening a `test-runner` image-snapshot diff threshold as the first response to flaky screenshots, before confirming `waitForPageReady` or explicit content masking is in place,
- connecting Chromatic without also making it a required CI check, calling that "visual regression coverage,"
- removing the test-runner because "Chromatic covers it," without confirming Chromatic's scope actually includes the custom assertions the test-runner was running.

Those are shortcuts that produce the appearance of coverage without the substance.

# Theme and Variant Coverage

Use this reference when auditing whether dark mode, RTL, and `prefers-reduced-motion` story variants have visual and accessibility coverage, or when non-deterministic content needs masking/mocking before a pixel diff is trustworthy. For the mechanics of the test-runner and Chromatic themselves, see `test-runner-and-chromatic-wiring.md`. For axe-core gating specifics, see `accessibility-addon-gating.md`.

## What people get wrong

The common bad assumption is:

> If the default-theme story passes visual and a11y checks, the component is covered.

That is incomplete. A component's rendered DOM, computed contrast ratios, and layout can all differ meaningfully across:

- **color scheme** (light vs. dark, or any custom theme the design system supports) -- contrast ratios computed by axe-core in a light-theme snapshot say nothing about the dark-theme token pairing, which is a distinct set of color values,
- **text direction** (LTR vs. RTL) -- logical layout bugs (icon placement, padding asymmetry, text truncation direction) frequently only appear in RTL and are invisible in an LTR-only snapshot,
- **motion preference** (`prefers-reduced-motion: reduce`) -- a component that only has an animated entrance story has no coverage confirming the reduced-motion fallback renders correctly, not just "does not animate."

A visual-regression suite that only ever renders the default light/LTR/motion-enabled variant of each component has verified one of potentially four-plus meaningfully different rendered states, and will not catch a regression introduced in any of the others.

## Officially grounded shape

Storybook does not automatically render every theme/direction/motion-preference permutation of a story -- coverage of these dimensions is a function of how many story variants exist and whether decorators or globals feed them into each render. Confirm, as repo evidence rather than assumption, whether:

- a dark-mode (or multi-theme) decorator/global exists and is exercised by dedicated stories, not just toggle-able in the manual Storybook UI,
- RTL stories exist using the project's actual RTL mechanism (e.g. a `dir="rtl"` wrapper decorator), not just documented as "supported" in a design doc,
- a `prefers-reduced-motion` variant exists, typically via a decorator that sets the media feature for the story's iframe, or via a dedicated reduced-motion story.

`parameters.a11y.context` (see `accessibility-addon-gating.md`) determines what markup axe-core inspects per story -- confirm it is not silently scoped in a way that excludes the very wrapper (e.g. an RTL `dir` wrapper) whose correctness is under test.

## Non-negotiable design rules

1. **Do not count a single default-theme story as coverage for "the component supports dark mode."** Supporting a capability in code and having a regression-tested story for it are different claims; only the latter catches a regression.
2. **Mask or mock non-deterministic content before adding any new theme/variant story to a visual diff, rather than after a flaky failure appears.** Timestamps, live avatars, randomized placeholder data, and animated content are common sources of false-positive diffs; the fix is explicit masking (e.g. a `mask` option, disabled animations, or seeded fixture data) applied at story-authoring time, not a loosened global threshold applied later.
3. **Treat RTL coverage as a layout-logic concern, not a translation concern.** An RTL story does not need translated text to be useful -- it needs the same content rendered with `dir="rtl"` to catch physical-vs-logical CSS property bugs (e.g. `margin-left` instead of `margin-inline-start`).
4. **Treat `prefers-reduced-motion` coverage as a distinct assertion from "does it animate," not a subset of it.** A story confirming the *entrance* animation looks right says nothing about whether the reduced-motion fallback (often a hard cut or fade) is also correct; test both if the component is animated.
5. **Prioritize theme/variant coverage by actual usage risk, not exhaustive permutation.** A component used only in an admin-only, LTR-only internal tool does not need RTL coverage; a design-system primitive used across public, internationalized surfaces does. Recommend coverage proportional to blast radius, not maximal coverage for its own sake.

## Safe verification targets

- Story files for visually-critical components -- confirm the presence (or absence) of theme/direction/motion story variants, not just the default export.
- `.storybook/preview.ts` decorators and globals -- confirm a theme-switching or `dir`-setting decorator exists and is actually wired into the stories claimed to cover it.
- The test-runner's `postVisit` hook or Chromatic's captured snapshot list -- confirm the theme/variant stories are actually included in the set of stories being diffed, not excluded by a `tags` filter or story-level skip.

## When to push back

Push back if the user asks for:

- claiming "dark mode is covered" based on a single manually-toggled preview in local dev, with no corresponding story or CI snapshot,
- adding an RTL story with translated placeholder text but no `dir="rtl"` wrapper, which tests translation rendering but not the actual logical-CSS layout bug class RTL coverage exists to catch,
- deferring reduced-motion coverage indefinitely on an animation-heavy component while treating it as low priority, without characterizing the actual user population affected (motion-sensitivity accommodations are an accessibility requirement, not a nice-to-have).

Partial coverage presented as complete coverage is worse than an honestly documented gap.