What’s included
Building Blocks owns system intent, source contracts, composition guidance, themes, product adaptation rules, and Catalog relationships. Storybook is the appropriate executable layer for real states, Controls, Autodocs/MDX, viewport execution, accessibility, interaction, visual testing, and addons when real shared component code exists.
Do not invent story links, APIs, packages, or source files to make the documentation look complete.
This relationship is architectural guidance. This page does not claim a live Storybook connection already exists.
Stories are executable state definitions.
Storybook describes a story as a rendered component state and uses args as the inputs. That is a better execution model for required component states than inventing a proprietary Building Blocks story syntax.
Controls are the manipulation surface.
When a component exists, Controls can stress variants, content, disabled/loading/error-like inputs, and edge cases. Building Blocks should say which states and variants are required; Storybook can make them live-editable.
Autodocs + MDX cover implementation-facing docs.
Storybook can infer API metadata from stories/components and generate documentation, while MDX combines written guidance with live stories. Building Blocks should not rebuild a generic prop-table engine when Storybook already owns that implementation layer.
Viewport, accessibility, interactions, visual testing
Recommended mapping
| Building Blocks owns | Storybook owns when connected |
|---|---|
| Contract + job | Rendered story |
| Required variants/states | Args + named stories |
| Usage / when not | Interactive controls |
| Responsive requirement | Viewport execution |
| Accessibility rules/manual checks | Automated accessibility checks |
| Interaction expectation | Play-function tests |
| Theme semantics | Preview of the implemented product theme |
| Catalog lineage | Implementation/source/API details |