Accessibility Testing

Purpose and Scope

Accessibility testing in Storybook is about auditing the rendered story DOM before accessibility problems escape into an application. The Storybook documentation defines web accessibility as making websites and apps inclusive to all people regardless of ability or technology, including support for keyboard navigation, screen readers, and sufficient color contrast. In practice, this page helps teams turn each story into a repeatable accessibility checkpoint. Because stories already capture meaningful component states, the a11y workflow can check those states while developers are still building, reviewing, and documenting UI components.

Sources: docs/writing-tests/accessibility-testing.mdx

The accessibility testing page also frames the work as a legal and quality responsibility, not only a developer convenience. It calls out accessibility legislation such as the European Accessibility Act, the Americans with Disabilities Act, and Section 508, and ties many requirements back to WCAG. Storybook does not replace expert accessibility review, user testing, or manual checks with assistive technology. Instead, automated tests provide a first line of QA: they quickly detect blatant violations against WCAG-based heuristics and industry practices every time a story renders.

Sources: docs/writing-tests/accessibility-testing.mdx

Relevant Source Files

• docs/writing-tests/accessibility-testing.mdx — The official Storybook documentation page for accessibility tests. It defines web accessibility, explains the purpose of automated accessibility checks, describes the a11y addon installation path, documents the Accessibility panel results, introduces Vitest addon integration, and starts the axe-based configuration reference.

Core Workflow

The main workflow starts by adding Storybook’s Accessibility addon, commonly referred to as the a11y addon. The documentation states that Storybook provides this addon to help ensure component accessibility, and that it is built on Deque’s axe-core library. That implementation choice matters because the addon’s findings and configuration model follow axe concepts: a rendered DOM is scanned, rules are evaluated, and results are grouped by outcome. The page notes that automated axe-based testing can catch a significant portion of WCAG issues, while still leaving room for manual confirmation.

Sources: docs/writing-tests/accessibility-testing.mdx

After installation, the running Storybook UI gains two developer-facing accessibility surfaces. First, a toolbar button can simulate different vision impairments, helping reviewers understand how a component may appear to users with visual differences. Second, the Accessibility addon panel reports audit results for the currently selected story. This keeps accessibility feedback close to the component authoring loop: developers navigate to a story, see the rendered component state, inspect the reported findings, and adjust markup, labels, contrast, focus behavior, or semantics before the component is merged.

Sources: docs/writing-tests/accessibility-testing.mdx

The page’s “Check for violations” section describes the result model developers should use when triaging findings. Results are divided into Violations, Passes, and Incomplete. Violations are known failures of WCAG rules and best practices, so they should be treated as actionable defects unless a team has an explicit exception policy. Passes are known non-violations, useful for confirming that rules were executed. Incomplete results are different: they identify areas that automation could not conclusively evaluate, so they require human review rather than automatic dismissal.

Sources: docs/writing-tests/accessibility-testing.mdx

Install and Run Accessibility Checks

Use Storybook’s addon installation flow when adding accessibility checks to an existing project. The documentation points readers to Storybook’s add command and explains that it automates addon installation and setup. Conceptually, the installation updates the project so the a11y addon is registered with Storybook, then the next development server run exposes the Accessibility panel and toolbar affordances. If a project has a custom package policy or cannot use the automated command, the same page points readers to manual addon installation documentation.

Sources: docs/writing-tests/accessibility-testing.mdx

npx storybook add @storybook/addon-a11y

Once the addon is present, no separate test file is needed for the basic interactive workflow. Navigate to a story in the Storybook UI and allow the addon to run against the rendered DOM. Because the story supplies the component props, decorators, providers, and layout context, the accessibility audit is scoped to the same state that designers, developers, and reviewers see on screen. If a component has multiple important states, model those states as separate stories so the addon can evaluate each state independently rather than relying on one generic example.

Sources: docs/writing-tests/accessibility-testing.mdx

Configure axe-Based Audits

The a11y addon is built on axe-core, and the documentation explicitly states that much of the available configuration maps to axe options. Storybook exposes those settings through parameters.a11y, which means the same parameter inheritance model used elsewhere in Storybook can be applied to accessibility. Set defaults globally when every story should share the same scan target or rule configuration. Override at the component level when a component family needs a different context. Override at the individual story level when a single state has a special rendering container or known exception.

Sources: docs/writing-tests/accessibility-testing.mdx

// .storybook/preview.ts
export default {
  parameters: {
    a11y: {
      context: 'body',
    },
  },
};

The concrete property visible in the documentation table is parameters.a11y.context, whose default is 'body'. It is passed as the axe context argument to axe.run, so it controls which part of the rendered document is audited. Keeping the default is appropriate for most stories because Storybook renders the story into the preview body. Narrowing the context can be useful when a story includes helper markup, test scaffolding, or page chrome that should not be evaluated as part of the component contract.

Sources: docs/writing-tests/accessibility-testing.mdx

// Button.stories.ts
export default {
  component: Button,
  parameters: {
    a11y: {
      context: '#button-story-root',
    },
  },
};
 
export const IconOnly = {
  parameters: {
    a11y: {
      context: '#icon-button-example',
    },
  },
};

Use narrower configuration carefully. Automated accessibility checks are most valuable when they evaluate what a user actually experiences, so excluding surrounding content can hide real problems if the component depends on page structure, headings, landmarks, focus order, or contrast against a parent background. Prefer global configuration for stable team-wide expectations, component configuration for renderer or layout-specific needs, and story configuration only for state-specific exceptions. When a result is marked incomplete, treat the configuration as a prompt to inspect manually rather than as proof that the story is accessible.

Sources: docs/writing-tests/accessibility-testing.mdx

Vitest Addon Integration

The accessibility testing page identifies the Vitest addon as the automation path for running accessibility checks alongside component tests. This matters because the Storybook UI is excellent for previewing and debugging, but teams also need CI feedback. The a11y addon’s integration with the Vitest addon lets projects reuse stories as test subjects, combining accessibility audits with the broader component testing workflow. In that model, stories remain the source of component states, while Vitest provides repeatable execution in local terminal and continuous integration environments.

Sources: docs/writing-tests/accessibility-testing.mdx

npx storybook add @storybook/addon-vitest

A practical testing strategy is to treat accessibility checks as one layer beside interaction, visual, and snapshot testing. Interaction tests exercise user behavior through story play functions, while accessibility checks audit semantic and perceptual requirements in the rendered DOM. Visual tests catch appearance regressions, and snapshots can cover targeted structural output when necessary. Keeping these checks story-centered reduces duplication: a well-authored story can serve designers in the UI, developers in local testing, and CI jobs that enforce a baseline of component quality.

Sources: docs/writing-tests/accessibility-testing.mdx

API and Configuration Reference

When documenting or reviewing a component library, make accessibility configuration part of the story contract. A story that requires a provider, theme, locale, routing context, or specific DOM wrapper should express that context through normal Storybook mechanisms before the a11y addon runs. If the addon reports a violation, fix the component or story setup rather than suppressing the signal by default. If the result is incomplete, add manual review notes to the component’s testing checklist and consider whether a more representative story state would make the automated scan more useful.

Sources: docs/writing-tests/accessibility-testing.mdx

Next Steps

Start by installing the a11y addon and reviewing the Accessibility panel for your most important stories. Then add stories for the states that are most likely to fail accessibility requirements: disabled controls, validation errors, loading states, modals, icon-only buttons, menus, and keyboard-driven interactions. Configure parameters.a11y.context only when the default body-level scan does not match what you intend to test. Finally, add the Vitest addon integration when the team is ready to run accessibility checks with the rest of its component test suite in CI.

Sources: docs/writing-tests/accessibility-testing.mdx