Introducing a new way to review your PRs.

Read the announcement

storybookjs / storybook

Storybook is the industry standard workshop for building, documenting, and testing UI components in isolation

View on GitHub

20 documents · Updated Nov 20, 2026

docs / user-facing-addons

User-facing addons

The user-facing addons extend Storybook from a story viewer into a tool for checking, explaining, connecting, learning, and styling UI states. They split work between the manager, which provides controls and panels, and the preview, which applies the selected behavior to the rendered story. See the Addon ecosystem page for the shared addon model and Testing and agent addons for automation-focused integrations.

Addon capabilities

These addons address different parts of the component development experience. Some act only in the manager, while others send state into the preview or change how the preview is built.

AddonProduct capabilityMain integration pattern
AccessibilityChecks a story for accessibility issues and shows the result.The preview runs the check after a story renders. The manager presents the report and a vision simulation tool.
DocsTurns stories and authored MDX into component documentation.The build and preview prepare documentation. The manager shows generated source code for the selected story.
LinksLets a story move to another story or expose a story URL.Preview helpers emit navigation requests. The manager resolves those requests to a story.
OnboardingGuides a new user through controls, story creation, and the next learning step.The manager owns the tour and uses manager events and URL state to control it.
Pseudo-statesShows CSS states such as hover and focus without real user input.A manager toolbar updates globals. A preview decorator applies matching classes and style rules.
ThemesSwitches the theme used by the story preview.A manager toolbar updates a global theme. A preview decorator maps that value to a provider, class, or data attribute.

The common flow is that a manager control changes shared Storybook state, and a preview annotation turns that state into a story-level result. Docs and onboarding also use build or manager services because their product goals include authored content and guided interaction.

This diagram shows how a user action crosses the manager and preview boundary to affect the rendered story or its supporting output.

flowchart LR
  User[User] --> Manager[Manager control or panel]
  Manager -->|globals, channel event, or URL state| Preview[Preview annotation or decorator]
  Preview --> Story[Rendered story]
  Preview --> Output[Report, navigation, docs, or themed view]
  Manager --> Output

Accessibility checks

Accessibility checks help an engineer find problems against common web accessibility rules while viewing a story. The addon uses an accessibility engine in the preview, then exposes violations, incomplete checks, status, and visual simulation in the manager.

The preview runs after a story renders when the story and global settings allow automatic checks. Ghost stories and non-story views do not run the check. A story can instead mark the check as a warning, turn it off, or select manual mode. The result is reported through Storybook’s reporting path, so it can appear in the Storybook UI and in test runs. Standalone Vitest runs can fail when a configured error-mode check finds violations or cannot run. (code/…/preview.tsx• L14-107)

The manager keeps the report and fast-changing panel state in addon-local state. Its context turns story-finished and render-phase events into report status, manual runs, selected findings, element highlights, deep links, and discrepancies between browser and command-line results. (code/…/store.ts• L6-58, code/…/A11yContext.tsx• L132-186, code/…/A11yContext.tsx• L277-326, code/…/A11yContext.tsx• L463-481)

The report keeps all violating nodes while limiting detail for passing nodes. This keeps the result useful for fixing issues without making passing output unnecessarily large. (code/…/a11yRunner.integration.test.ts• L20-34)

The manager registers an Accessibility panel and a story-only vision tool. The panel title also shows the count of violations and incomplete checks, while the tool lets the user inspect how a view may appear under different vision conditions. (code/…/manager.tsx• L13-51, code/…/manager.test.tsx• L22-39)

The vision tool offers predefined simulations with labels and user-impact context. Users can select or reset a simulation through the vision global, while a story-level value locks the manager control so an authored story setting remains in force. (code/…/VisionSimulator.tsx• L38-64, code/…/visionSimulatorFilters.ts• L1-43, code/…/VisionSimulator.stories.tsx• L33-60)

The preview applies the selected simulation to the story canvas and removes the addon’s prior simulation when the value changes or resets. It preserves other body filter effects and warns when a global names an unsupported simulation. (code/…/withVisionSimulator.ts• L15-60, code/…/withVisionSimulator.test.ts• L74-100)

References: code/…/preview.tsx• L14-107 code/…/a11yRunner.integration.test.ts• L20-34 code/…/store.ts• L6-58 code/…/A11yContext.tsx• L132-186 code/…/manager.tsx• L13-51 code/…/VisionSimulator.tsx• L38-64 code/…/visionSimulatorFilters.ts• L1-43 code/…/withVisionSimulator.ts• L15-60 code/…/withVisionSimulator.test.ts• L74-100 code/…/package.json• L1-4

Component documentation

Docs turns component stories into pages that combine story examples, written content, component data, and source views. It supports a zero-configuration page for a story and an authored MDX path for documentation that needs a custom structure or embedded examples. (code/…/README.md• L9-15, code/…/README.md• L29-43)

The preview supplies the documentation renderer and filters stories that should not appear in generated docs. The build integration adds the MDX and story-source processing needed to make authored documentation and enriched story data available across supported builders. (code/…/preview.ts• L1-28, code/…/preset.ts• L38-61)

Docs also publishes documentation entries through the experimental manifest system. Attached MDX pages appear under their component, while unattached pages appear in a separate docs collection. In the docgen-server and components-manifest mode, these entries use shallow references to MDX service snapshots; otherwise the manifest includes the file content. Each readable page carries an authored or derived summary, while an unreadable page carries an error. (code/…/manifest.ts• L67-105, code/…/manifest.ts• L108-125, code/…/manifest.ts• L172-247)

The manifest keeps attached and unattached documentation separate and ignores docs entries without the tags that define either relationship. This lets component data and standalone page data keep distinct ownership while the MDX service supplies full content when reference mode is active. (code/…/manifest.test.ts• L98-132, code/…/manifest.test.ts• L134-205, code/…/manifest.test.ts• L207-302)

Docs presents component inputs in an ArgsTable. The table can show descriptions, types, defaults, documentation tags, and live controls. It filters disabled or conditional inputs, groups related rows into sections and subsections, and lets users collapse those groups or reset changed controls. Rows without a usable control still expose setup guidance when the user points to or focuses the row. (code/…/ArgsTable.tsx• L252-329, code/…/ArgsTable.tsx• L389-525, code/…/ArgRow.tsx• L83-157, code/…/SectionRow.tsx• L112-153)

Color-valued inputs have a dedicated control that supports text entry, a picker, preset swatches, and alternate color formats. Read-only inputs keep the value visible without allowing edits. (code/…/Color.tsx• L246-303, code/…/Color.tsx• L366-465)

Docs previews show one or more story examples with optional layout, zoom, reload, and extra actions. When source is available, users can show it or copy it; source can also be supplied directly or transformed from the current story context, including through an asynchronous transform. A source block can also use the story’s initial args when a stable starting example is required. When source generation is loading or fails, the preview shows a loading state or says that code is not available. It can also show a warning for an incomplete example and use a dark source view. (code/…/Preview.tsx• L150-166, code/…/Preview.tsx• L200-294, code/…/Source.tsx• L35-57, code/…/Source.tsx• L106-164, code/…/Source.tsx• L208-236, code/…/source.stories.ts• L12-72)

Inline docs stories keep their layout while an error is shown. When the story recovers, the docs block can reveal the same mounted area without losing its size. (code/…/Story.tsx• L38-95, code/…/Story.stories.tsx• L93-115)

The manager adds a Code panel for a selected story. The panel receives rendered snippets over the addon channel, resets when navigation changes, and ignores snippets from stories that are no longer selected. It uses an explicit source or language override when one is present, while otherwise following the rendered snippet and the story’s original source. This keeps the source view aligned with manager navigation and makes the displayed language match the selected source. (code/…/manager.tsx• L8-31, code/…/CodePanel.tsx• L30-99)

Docs source blocks also accept a language from the block, story parameters, or a rendered snippet. They can transform source with a synchronous or asynchronous function, and they discard an older asynchronous result when a newer story context or snippet replaces it. (code/…/Source.tsx• L19-29, code/…/Source.tsx• L100-123, code/…/useTransformCode.tsx• L15-57)

References: code/…/README.md• L9-15 code/…/README.md• L29-43 code/…/docspage.md• L5-29 code/…/preview.ts• L13-28 code/…/preset.ts• L38-61 code/…/manifest.ts• L67-105 code/…/manifest.ts• L108-125 code/…/manifest.ts• L172-247 code/…/manifest.test.ts• L98-132 code/…/manifest.test.ts• L134-205 code/…/manifest.test.ts• L207-302 code/…/ArgsTable.tsx• L252-329 code/…/ArgRow.tsx• L83-157 code/…/SectionRow.tsx• L112-153 code/…/Color.tsx• L246-303 code/…/Color.tsx• L366-465 code/…/Preview.tsx• L200-294 code/…/Source.tsx• L35-57 code/…/Source.tsx• L106-164 code/…/Source.tsx• L100-123 code/…/Source.tsx• L153-205 code/…/SourceContainer.tsx• L35-101 code/…/useTransformCode.tsx• L15-57 code/…/Story.tsx• L38-95 code/…/Story.stories.tsx• L93-115 code/…/manager.tsx• L8-31 code/…/CodePanel.tsx• L30-99 code/…/CodePanel.stories.tsx• L31-137 code/…/SourceLanguage.stories.tsx• L90-321 code/…/source.stories.ts• L12-72

Story navigation

Links lets stories behave as connected demos rather than isolated examples. A story can navigate to another story, create a URL for a story, or declare a link with data attributes; React users can also render a link component that keeps normal browser behavior for modified clicks and new-tab actions. (code/…/README.md• L1-3, code/…/README.md• L78-115, code/…/README.md• L132-148)

The preview supplies the navigation helpers and a decorator that watches link data on rendered elements. A navigation request crosses the channel to the manager, which maps the requested title and name to a story ID and sends the resolved destination back. The URL helpers preserve the current story title from the preview query when a link supplies only a story name. Tests cover both asynchronous and synchronous URL creation as well as the story-selection payloads emitted by link handlers. (code/…/utils.ts• L26-43, code/…/utils.ts• L79-115, code/…/preview.ts• L1-3, code/…/manager.ts• L1-10, code/…/utils.test.ts• L20-114)

References: code/…/README.md• L1-3 code/…/README.md• L78-115 code/…/utils.ts• L26-43 code/…/utils.ts• L79-115 code/…/manager.ts• L1-10 code/…/utils.test.ts• L20-114

Onboarding experience

Onboarding gives a new Storybook user a guided path through the core workflow. It introduces the interactive controls, helps the user save a changed state as a new story, confirms the created story, and points the user to the continuing guide. (code/…/README.md• L1-13, code/…/Onboarding.tsx• L197-305)

The manager activates the experience only for an onboarding URL and a project that still has the example button stories. It selects the relevant story, opens the controls panel, and renders the tour in a separate manager container. The experience can also open an intent survey and store its accepted state in the manager checklist. (code/…/manager.tsx• L13-23, code/…/manager.tsx• L25-67)

The tour follows manager events instead of changing the preview through a general preview decorator. It watches the controls and story tree, listens for story-save completion, and uses the addon channel for survey and progress telemetry. (code/…/Onboarding.tsx• L71-129, code/…/Onboarding.tsx• L142-185, code/…/preset.ts• L8-23)

References: code/…/README.md• L1-13 code/…/manager.tsx• L25-67 code/…/Onboarding.tsx• L71-129 code/…/Onboarding.tsx• L142-185 code/…/preset.ts• L8-23

CSS pseudo-states

Pseudo-states makes interaction styles visible without requiring a real pointer or keyboard action. The addon supports dynamic CSS states such as hover, active, focus, focus-within, visited, link, and target, and it can apply them to the full story root or to selected elements. (code/…/README.md• L5-17, code/…/constants.ts• L9-20)

The manager exposes a story-only toolbar control that updates the selected states as globals. The preview decorator reads those globals or story parameters, finds the target root, and applies the matching state classes. It can also use a custom root for content such as portals and dialogs. (code/…/PseudoStateTool.tsx• L13-43, code/…/withPseudoState.ts• L125-180, code/…/README.md• L67-83)

Because browsers do not provide a general API for forcing native pseudo-classes, the preview rewrites matching style selectors to support the added classes. This makes fixed story states useful for visual checks, but it does not reproduce browser user-agent styles exactly. (code/…/README.md• L11-17, code/…/withPseudoState.ts• L183-227)

References: code/…/PseudoStateTool.tsx• L13-43 code/…/withPseudoState.ts• L125-180 code/…/withPseudoState.ts• L183-227 code/…/README.md• L11-17

Theme selection

Themes lets an engineer view the same story under several visual themes. The selected theme is a Storybook global, so it can be changed from the toolbar or fixed by story-level settings for a stable example. (code/…/README.md• L1-3, code/…/README.md• L37-67)

The manager registers a toolbar control for story and docs views. It learns the available theme names from the preview-side theme setup, then renders a toggle for two themes or a selector for more than two. A story override locks the control and makes the source of the selected theme clear to the user. (code/…/manager.tsx• L1-14, code/…/theme-switcher.tsx• L24-67, code/…/theme-switcher.tsx• L73-111)

The preview exposes decorator strategies for the main ways applications consume a theme. A provider strategy passes the selected theme into a component provider, while class-name and data-attribute strategies update a parent element for CSS-driven themes. All strategies use the story override before the global value and fall back to the configured default. (code/…/provider.decorator.tsx• L23-60, code/…/class-name.decorator.tsx• L19-54, code/…/data-attribute.decorator.tsx• L19-40)

References: code/…/manager.tsx• L1-14 code/…/theme-switcher.tsx• L24-67 code/…/provider.decorator.tsx• L23-60 code/…/class-name.decorator.tsx• L19-54 code/…/data-attribute.decorator.tsx• L19-40

Manager and preview integration

The manager is the user-facing control plane for these addons. It registers panels, tools, and toolbar controls, then uses globals, URL state, manager state, or channel events to express the user’s choice. The Docs manager creates a story-only Code panel and passes the active story and its preparation state to the panel. (code/…/manager.tsx• L36-51, code/…/store.ts• L28-58, code/…/manager.ts• L6-13, code/…/manager.tsx• L6-13, code/…/manager.tsx• L8-31)

The preview is the story-facing execution plane. Preview annotations add decorators, after-story checks, initial globals, and documentation behavior; those annotations convert manager state into rendered styles, reports, navigation, or docs. (code/…/preview.tsx• L12-20, code/…/preview.ts• L1-3, code/…/preview.ts• L1-8, code/…/preview.ts• L1-7)

The channel connects the two planes when a value cannot be shared as a direct global. Links use it to resolve destinations, Docs use it to deliver generated snippets and source metadata, and onboarding uses it for progress and survey events. Docs keeps snippets scoped to the current story in both the manager Code panel and the docs source context. This keeps manager UI state separate from the story render while still allowing both sides to respond to one user action. (code/…/manager.ts• L5-9, code/…/manager.tsx• L8-31, code/…/CodePanel.tsx• L52-70, code/…/SourceContainer.tsx• L46-101, code/…/preset.ts• L14-23)

References: code/…/manager.tsx• L36-51 code/…/store.ts• L28-58 code/…/preview.tsx• L12-20 code/…/manager.ts• L5-9 code/…/manager.tsx• L8-31 code/…/CodePanel.tsx• L52-99 code/…/SourceContainer.tsx• L46-101 code/…/preset.ts• L14-23

Change checklist

When these files or sections are changed, remember to consider these:

  • When an addon changes its global or parameter name, update both the manager control and the preview annotation that reads it.
  • When a11y report or UI state changes, keep the context consumers, panel count, highlight state, deep-link state, and manual-run events aligned.
  • When vision filter options or global handling changes, keep the toolbar labels, filter definitions, preview cleanup, and unsupported-value warning aligned.
  • When a channel event payload changes, update both its sender and receiver, including navigation resolution, generated source display, source language, and source warnings.
  • When Docs changes story filtering or MDX processing, check both generated documentation pages and authored MDX pages.
  • When Docs changes manifest grouping or MDX reference mode, check attached component docs, standalone docs, summaries, file-read errors, and service references together.
  • When Docs changes ArgsTable grouping or conditional rows, check the manager’s visible rows against the preview’s story args and globals.
  • When Docs changes preview source handling, check the show-code, copy-code, reload, source-language, loading, warning, and source-error states together.
  • When Docs changes source precedence or asynchronous transforms, check explicit code, parameter code, emitted snippets, original source, service snippets, and superseded transforms together.
  • When Docs changes source transformation examples or package dependencies, check that template stories run without relying on transitive packages.
  • When Docs changes color input behavior, check text entry, picker updates, presets, color-format changes, and read-only state together.
  • When Docs changes inline story error handling, keep the mounted layout, hidden error view, recovery display, and recovery story contract aligned.
  • When pseudo-state support changes, check the toolbar state, story parameters, docs roots, portals, and shadow-root behavior together.
  • When theme registration or selection changes, check the toolbar display and every supported preview strategy: provider, class name, and data attribute.
  • When onboarding steps or URL gates change, check the example-story requirement, checklist state, story-save transition, and survey path as one flow.
  • When link URL or selection handling changes, check both title omission fallback and the synchronous and asynchronous URL helper contracts.

Important failure modes

TriggerConsequenceGuard
A11y checks run with the wrong manual, disabled, or test mode value.A report is missing or a warning is treated as a failure.Keep story parameters and a11y globals aligned with the preview gate and report status.
A11y manager state is updated outside the shared addon store or context contract.The panel, title badge, or highlight view shows stale results.Keep report events and UI state changes on the store and context path used by the manager.
A11y result handling drops violation nodes or returns an incomplete result.The report hides the evidence needed to fix an accessibility issue.Preserve violation details while limiting only the intended passing-node output.
A vision global names an unsupported simulation.The preview cannot apply the requested view and the user may think the filter is active.Use a supported filter value and keep invalid-value warnings visible.
A Docs snippet arrives for a story that is no longer selected.The Code panel or a docs source block shows source for the previous story.Match channel events to the current story ID and keep source entries keyed by story and args.
A source block receives a stale loading, error, or warning state.The docs page hides usable code or presents an incomplete example as complete.Keep source content, loading state, error state, and warning state from the same story context.
A conditional ArgsTable rule is invalid or differs between manager and preview state.A row is hidden in docs or the preview cannot prepare the story.Keep conditional arg inputs consistent and let the preview remain the source of truth for invalid rules.
Docs source generation fails.The preview cannot show or copy code.Preserve the source error and warning state so the user sees that code is unavailable.
A Docs template story relies on a package that is only available transitively.The source example fails in an isolated sandbox.Keep template examples self-contained or declare every required runtime package directly.
A Docs manifest entry has no attached or unattached MDX tag.The entry is not added to either docs collection.Keep docs index tags aligned with the intended component or standalone ownership.
A Docs manifest source file cannot be read outside reference mode.The docs entry remains listed but has no content and reports a read error.Preserve the error payload and fix the source path or file access issue.
A Docs reference entry is used without its matching MDX service snapshot.A manifest row points to docs content that cannot be resolved.Keep docgen-server reference mode and MDX service snapshots enabled together.
A color value is invalid or a read-only input receives an update.The control shows a fallback value or changes a value that should remain fixed.Keep parsed values and read-only controls aligned with the documented arg state.
An inline docs story removes its mounted area or collapses its layout during an error.Recovery can render at the wrong size or fail to show the original story area.Keep the story area mounted and laid out while the error is visible, then wait for recovery before revealing it.
A link names a story that the manager cannot resolve.Navigation points to no story or the wrong story.Keep link title and story-name inputs aligned with the indexed story identity.
A link URL omits its title but the current preview URL has no usable story path.The generated URL can point to an incomplete or wrong story ID.Supply a title when needed and preserve the current-path fallback contract covered by the URL helper tests.
Onboarding is opened without the example button stories.The tour does not load and the addon warns that it is no longer needed.Preserve the example-story gate or use the supported onboarding setup.
Pseudo-state CSS cannot be rewritten or the target root is wrong.The toolbar reports a state that the story does not show.Use a valid root selector and account for portals, shadow DOM, and the addon’s browser-style limits.
A story fixes the theme while the toolbar tries to change it.The toolbar is locked and the preview stays on the story theme.Treat story-level theme overrides as intentional precedence over globals.

Key files

FileWhy to read it
code/…/preview.tsxShows how an accessibility result is produced and reported from the preview.
code/…/manager.tsxShows the accessibility panel, count badge, and vision tool surfaces.
code/…/VisionSimulator.tsxShows the manager control for selecting, resetting, and locking a vision simulation.
code/…/visionSimulatorFilters.tsShows the supported vision simulations and their user-facing descriptions.
code/…/withVisionSimulator.tsShows how a selected vision simulation reaches the story canvas and is cleaned up.
code/…/withVisionSimulator.test.tsShows the supported, reset, and unsupported vision-value contracts.
code/…/store.tsShows the local manager state used for frequent accessibility report and UI updates.
code/…/preview.tsShows the preview contract for generated documentation.
code/…/manifest.tsShows how attached and standalone docs become inline entries or MDX service references.
code/…/manifest.test.tsShows the manifest contracts for tags, summaries, read errors, and reference mode.
code/…/ArgsTable.tsxShows how component inputs are filtered, grouped, sorted, controlled, and reset in docs.
code/…/ArgRow.tsxShows the information and control affordances for one documented component input.
code/…/SectionRow.tsxShows how grouped argument sections expand and collapse.
code/…/Color.tsxShows the user-facing color input and its value-selection modes.
code/…/Preview.tsxShows how docs previews combine story rendering with source and preview actions.
code/…/Source.tsxShows the user-visible loading, error, warning, copy, language, and theme states for source code.
code/…/Source.tsxShows how docs source follows the selected story context and can use live or initial args.
code/…/SourceContainer.tsxShows how rendered source events become story- and args-specific docs source data.
code/…/useTransformCode.tsxShows how source transforms support sync and async output without applying stale results.
code/…/Story.tsxShows how docs renders inline and iframe stories and preserves the inline story area during recovery.
code/…/Story.stories.tsxShows the docs story rendering and error-recovery contracts.
code/…/manager.tsxShows how the manager presents story source through channel events.
code/…/CodePanel.tsxShows how the manager Code panel selects source, language, warnings, and the current story.
code/…/CodePanel.stories.tsxShows the Code panel contracts for language events, overrides, and story navigation.
code/…/SourceLanguage.stories.tsxShows source-language precedence and async transform transitions.
code/…/preset.tsShows where Docs joins the build and documentation pipeline.
code/…/source.stories.tsShows the supported source modes, including custom and synchronous or asynchronous transformed source.
code/…/utils.tsShows story navigation, URL creation, and declarative link behavior.
code/…/utils.test.tsShows the navigation payload and URL fallback contracts for Links helpers.
code/…/manager.tsShows manager-side story destination resolution.
code/…/manager.tsxShows onboarding activation gates and manager mounting.
code/…/Onboarding.tsxShows the guided learning flow and its manager event links.
code/…/withPseudoState.tsShows how selected pseudo-states reach story elements and styles.
code/…/PseudoStateTool.tsxShows the toolbar contract for selecting pseudo-states.
code/…/theme-switcher.tsxShows theme discovery, selection, and story override behavior.
code/…/provider.decorator.tsxShows the provider-based preview integration.
code/…/class-name.decorator.tsxShows the CSS class-based preview integration.
code/…/data-attribute.decorator.tsxShows the data-attribute-based preview integration.