Storybook Screen Reader Addon

What the Addon Shows You

The addon adds a "Screen Readers" panel to Storybook. When you render any story, it instantly shows predicted speech output for four screen readers, plus an accessibility audit.

How Screen Reader Output Differs Per Reader

The addon uses the same Speakable engine that powers the CLI and MCP server. Each reader produces genuinely differentiated output. Here are some common differences you will see across tabs:

How to Install the Storybook Addon

The addon ships as part of the @reticular/speakable package. No extra package to install. If you already use Speakable for CLI or MCP, you have the addon ready.

Step 1: Install Speakable

If you have not installed Speakable yet:

npm install --save-dev @reticular/speakable

Step 2: Add to Storybook Config

Add the addon to your .storybook/main.ts (or .storybook/main.js):

import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@reticular/speakable/storybook', // Add this line
  ],
  framework: '@storybook/react-vite', // or your framework
};

export default config;

Step 3: Start Storybook

Start Storybook as usual. The "Screen Readers" panel appears at the bottom alongside your other addon panels (Actions, Controls, etc.):

npm run storybook

No configuration required beyond adding it to your addons array. The addon automatically analyzes every rendered story.

How the Addon Works Under the Hood

Supported Frameworks

The addon works with any Storybook framework that renders to the DOM. The analysis runs on the final rendered HTML, so it is framework-agnostic:

Requires Storybook 8.x. The addon uses the Storybook Manager API and panel registration system introduced in Storybook 7, but is tested and optimized for version 8.

Using the Addon with Storybook Controls

Combine the addon with Storybook Controls to explore how prop changes affect screen reader output. For example, toggling a disabled prop will show the reader output update from "button" to "button, unavailable" (NVDA) or "button, dimmed" (VoiceOver) in real time.

Understanding the Audit Tab

The Audit tab runs a lightweight accessibility check on the rendered story. It reports issues that would affect screen reader users:

The audit runs the same checks as the CLI audit command and the MCP audit_html tool.

Speakable Addon vs @storybook/addon-a11y

Both addons help with accessibility, but they solve different problems and work well together:

Limitations and Accuracy

The addon provides heuristic predictions, not a screen reader emulator. Keep these limitations in mind:

• Predictions approximate common screen reader behavior. Real output varies by reader version, user settings, and verbosity level.
• Dynamic focus management (focus trapping, focus restore) is not fully modeled. The addon shows the DOM state, not the focus sequence.
• Live region announcements are shown as static output. The timing and interruption behavior of live regions differs across readers.
• CSS-based hiding (display: none, visibility: hidden) is detected, but complex CSS state transitions may not be captured on initial render.