A Story’s Complete Journey

Storybook’s story model becomes most useful when its parts are viewed together. This checkpoint connects the CSF definition, the indexed entry, the manager, the preview, and the render lifecycle so the subject can be understood as one operating system rather than a set of features. The practical result is a way to explain what changes when args, globals, source files, or play functions change—and to identify which boundary owns the resulting problem.

One story has several valid representations

A story begins in a file, but the file is not the only form the story takes. The same UI state is represented first as authoring information, then as index metadata, and finally as a live rendering context. These representations overlap, but they are not interchangeable. Confusing them is one reason Storybook behavior can seem mysterious.

At the authoring boundary, CSF gives a story a component-level meta and a named variation. Args, parameters, decorators, loaders, tags, and play functions describe the conditions under which that variation should be rendered and exercised. This is the durable definition a developer edits. It says what state matters and what context or behavior belongs with it, but it does not contain the current DOM or the current value of a toolbar-controlled global.

At the indexing boundary, Storybook reads enough of the story file to make it selectable. The server extracts a title, name, identity, import path, component information when available, and tags. It can add documentation entries and connect an MDX page to the story files it references. This representation is compact by design. It allows the manager to build a navigable sidebar, resolve a URL, sort and filter entries, and identify what to load without executing every component.

At the execution boundary, the preview imports the module for the selected identity and prepares the story with its inherited annotations. It creates a live context containing current args, globals, hooks, reporting, and the canvas element. The renderer then turns that context into a DOM result and runs the declared lifecycle and play behavior. The live context is the place where a story’s current run exists; the source file remains the reusable definition.

The identity ties the representations together. It lets the manager select a story, tells the preview which module and export to resolve, and gives later status or error reports something to point to. But identity does not guarantee that every representation is healthy. A story can have a valid index entry and still fail while being imported. It can import successfully and fail when a required provider is absent. It can render and then fail in a play assertion. The identity tells the system which state is under discussion; it does not collapse all failure stages into one.

This distinction is especially important for documentation. An automatically generated docs entry may be visible in the index before the component story has been rendered on a page. When the docs page embeds stories, the documentation renderer can prepare several examples inside one page. The docs entry and the story entries refer to related material, but they have different render paths and different roots.