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.

How to Capture an Interaction Timeline in Storybook

The per-reader tabs analyze the story at a point in time. The Timeline tab goes further: it runs an interaction sequence against the rendered story and records the accessibility events that result, in order. That includes focus transitions, ARIA state changes, live region announcements, and dialog open and close events. This is how you verify dynamic behavior, such as a modal moving focus on open and restoring it on close, directly in Storybook.

Timeline capture is opt-in per story. Add a parameters.speakable block with either a full sequence or a named built-in pattern. The sequence runs automatically once after the story renders, so the Timeline reflects that scripted run rather than manual clicking in the preview.

Option 1: Use a built-in interaction pattern

Built-in patterns cover common ARIA widgets. Override the selectors to match your markup:

export const Dialog = {
  render: () => renderDialog(),
  parameters: {
    speakable: {
      // 'modal-dialog' | 'combobox' | 'tabs' | 'accordion'
      pattern: 'modal-dialog',
      selectors: { trigger: 'button.open', container: '[role="dialog"]' },
    },
  },
};

Option 2: Write a custom sequence

When a built-in pattern does not match your component, declare the actions yourself. Supported actions include tab, shiftTab, click (with a selector), enter, space, escape, the arrow keys, key (with a combo), and wait (with ms).

export const Disclosure = {
  render: () => renderDisclosure(),
  parameters: {
    speakable: {
      sequence: {
        description: 'Tab to the toggle and open it',
        actions: [{ type: 'tab' }, { type: 'enter' }],
      },
    },
  },
};

// Opt a story out of timeline capture (static tabs still work)
export const StaticOnly = {
  render: () => renderThing(),
  parameters: { speakable: { timeline: false } },
};

parameters.speakable reference

Set a baseline and catch regressions with the Diff tab

On the Timeline tab, click Set baseline to store the current timeline for that story. Baselines persist in the browser, keyed per component and story. On later renders, the Diff tab compares the current timeline against the baseline and classifies each change by severity (critical, high, medium, low). A broken focus trap or a dropped announcement then surfaces as a regression instead of a silent behavior change.

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.
• The per-reader tabs show the DOM state at a point in time. To capture focus management (focus trapping, focus restore) and live region announcements over time, add a parameters.speakable sequence and read the Timeline tab.
• Timelines run the scripted sequence you declare, executed once after render. They do not record free-form manual interaction in the preview.
• Live region timing and interruption behavior differs across readers. The Timeline records that an announcement occurred, not each reader's exact interruption model.
• CSS-based hiding (display: none, visibility: hidden) is detected, but complex CSS state transitions may not be captured on initial render.