Why Storybook Starts with a State, Not a Page
Storybook is an open-source frontend workshop for building, testing, documenting, and sharing UI components and pages in isolation. The question here is why the project makes a named component state—not a whole application page—the basic unit of work. The answer gives this series its central model: Storybook turns a UI variation into a story, an executable artifact that can be revisited in a preview, checked by tools, explained in documentation, and shown to other people.
The frontend problem is not a lack of components
Modern frontend frameworks gave teams a useful way to break large interfaces into components. A button, form field, dialog, or navigation item can be developed as a smaller unit instead of as one indivisible page. But componentization does not make the possible states disappear. It often makes the number of states more visible.
A single component may need to behave differently on a narrow screen, with a long label, while data is loading, after a failed request, when a user has no permission, or when keyboard focus moves through it. Browser differences, accessibility requirements, performance constraints, and asynchronous work add further variations. A mature application can therefore have many components and far more distinct situations to inspect.
The difficulty is not only the number. The usual route to a state is indirect. A developer starts the application, navigates to a page, supplies data, opens a menu, submits a form, waits for a request, and tries to reproduce the condition that matters. That route passes through business logic and application context that may be necessary for the product but irrelevant to the UI question. It also makes rare states expensive to reach repeatedly. A failure in a component may be hidden behind a routing problem, a service dependency, or a sequence of actions that is difficult to remember.
This changes the practical meaning of a UI bug. The problem is not just “the component renders incorrectly.” It may be that the team cannot reliably put the component into the state where the error appears. If reaching a state costs more than examining it, developers will tend to check the common path and postpone the edge cases. The result is a workflow that treats UI variation as incidental, even though variation is where much of the user experience is decided.
Storybook’s starting point is a response to that access problem. It does not claim that frameworks are inadequate or that the application context is unnecessary. It creates a parallel place in which the component can be examined with the relevant inputs and controlled context, without requiring the entire product to be running in the same way.
Isolation changes the path to a UI state
Storybook is packaged as a small, development-only workshop that lives alongside the application. Its preview uses an isolated iframe to render a selected component or page. In practical terms, the iframe is a boundary: application business logic does not automatically surround every component being examined, so the developer can focus on the rendered variation itself.
Consider a login form. In the application, its empty, invalid, loading, and server-error states may depend on routing, authentication services, network responses, and a particular navigation path. In Storybook, each of those situations can be represented directly as a separate state. The developer can select the error case without first causing a real server failure, or inspect the loading case without racing a request. The point is not to pretend the mock is the production system. The point is to make the visual and behavioral question addressable.
Isolation therefore removes interference, not responsibility. A component that expects a theme provider, a router, a data client, or a browser feature still needs those dependencies. Storybook’s story model lets a project supply them deliberately through mocks, providers, and other context. That explicit setup can be more work at first, but it makes the conditions of the example visible. It also exposes an important boundary: an isolated story can show what the component does under supplied conditions, but it cannot by itself prove that the application wires every condition correctly.
The isolated iframe also creates a stable place for feedback. A developer can change a component and see the selected state again without reconstructing the application path. The project’s controls can expose inputs for live editing, while other features can inspect the same rendered state. These capabilities matter because the state is no longer only an accident of navigation. It has a name, inputs, and a repeatable place in the UI.
That repeatability changes the quality of a conversation. Instead of saying that a dialog “sometimes” looks wrong, a teammate can point to a named variation, inspect the same inputs, and discuss the result against a shared reference. If the state is changed deliberately, the team can compare the old and new renderings under the same story conditions. Reproduction becomes part of the artifact rather than a separate favor that one developer must perform for another. This is especially useful for edge cases: the team can keep a state visible after the original incident has disappeared from the running application.
The boundary remains important. A story that supplies a mocked error response is evidence about the component’s error presentation under that response; it is not evidence that the production service will return the response, or that the application will pass it through correctly. The value comes from isolating one question so that it can be answered clearly. Broader integration questions still belong to the application and its other tests.
That is why a story is more useful than a screenshot. A screenshot records one visual result, but it does not preserve the inputs that produced it, the context needed to render it, or the behavior expected after a user interacts with it. A story can describe a variation and, when needed, include the setup or behavior associated with that variation. It remains close to the component’s source and can be executed again after the component changes.
The diagram captures Storybook’s central reframe. A story does not eliminate the variation problem; it gives a particular variation an address. That address is valuable because several activities can refer to the same state instead of rebuilding their own approximation of it. The dotted boundary is just as important as the solid path: the story still depends on deliberate context and on people deciding which states are meaningful and whether the result is acceptable.
From isolated examples to a shared UI system
Storybook’s recommended component-driven workflow develops interfaces from the bottom up. A team can begin with basic components and their variations, combine those components into more complex units, assemble pages, and only then connect the pages to application data and business logic. This ordering is not a rule that every team must follow. It is a way to move some UI reasoning earlier, when the component is small enough to inspect directly.
The story is the connective tissue in that workflow. A component’s stories form an interactive directory of its states. Instead of searching through the application for a familiar pattern, a teammate can open the component’s examples and see how it behaves in the states the team chose to capture. That makes the story collection useful as both a workbench and a memory of the UI’s intended use cases.
The same artifact can support more than development. Storybook’s documentation describes stories as inputs to testing and documentation, and CSF—the Component Story Format—makes them portable through JavaScript modules. In a test workflow, a story can become a render check or the starting state for an interaction test. In documentation, the story can appear beside explanations and controls. In review, a published Storybook can give developers, designers, product managers, and other stakeholders a URL they can open without installing the application.
Those extensions should not be confused with automatic completeness. A project may have excellent stories for a button and no story for a difficult page state. Generated documentation may faithfully display the stories that exist while saying nothing about states nobody captured. A visual comparison can reveal a changed pixel, but a person still has to decide whether the change is intentional. A story makes feedback repeatable; it does not decide what deserves feedback.
The repository’s architecture reflects this wider purpose. Storybook is not only a canvas for a component. Its core includes a manager UI, a preview runtime, a server and CLI, and libraries used by frameworks, builders, and addons. The surrounding ecosystem adapts that core to different component runtimes and bundlers. Later, this series will follow what happens when a story moves through those layers. For now, the important point is the direction of travel: an isolated state becomes a shared reference that different tools can consume.
This also explains why Storybook is incrementally adoptable. A team does not need to solve every testing, documentation, and publishing problem before it can benefit from isolating a few high-value states. It can start where state access is most expensive: a form with difficult validation, a component with many visual variants, or a boundary between a design system and its users. The first stories can then reveal which providers, mocks, and conventions the project needs. More automation is worthwhile when the resulting feedback answers a real question often enough to justify its maintenance.
The strongest claim Storybook can make from this design is not that it replaces the application, the test suite, or human review. It changes what those activities can share. A named story gives a UI state an identity, an executable definition, and a place where other people and tools can meet it. The next step is to examine what that definition contains—its component metadata, inputs, rendering rules, and annotations—because the usefulness of the shared state depends on how precisely the story describes it.