Storybook

Checking whether a single component was built correctly used to mean opening a real screen that used it. Seeing a button's disabled state meant logging in, navigating to the form, and manually creating the conditions that disable it. If the state only appeared when particular data existed on the server, putting that data there was part of the job too. Looking at one state cost several minutes.

So people checked the states that come up often and skipped the rest. The error state, the state with very long text, the state waiting for a result after a press — nobody opened those. They surfaced in production instead. A button that stayed pressable while waiting for its result, so documents got saved twice, would be reported after the release rather than before it. Nobody had skipped a step; the step had no affordable place to happen.

Mockups and code drifting apart came from the same place. A mockup shows a button in two states, resting and hovered, while the code needs six. The other four end up being decided by whoever builds it, and there was nowhere to review what got decided. Storybook is the tool that created that place.

It removes the setup work of manufacturing a screen and a dataset just to look at one component. Write down the component plus the values to hand it, and it renders from a list at a click. One of those written-down pairs is called a story, and five things move across.

1. States get written down in advance. For a button that means one line each for resting, hovered, pressed, disabled, waiting for a result, and holding very long text. With six lined up in a list, a missing state is immediately visible.
2. It renders with no screen and no data. No login, no server. Seeing the error state doesn't require causing an error — the values that produce it are simply written into the story. The same holds for states that depend on a subscription tier or a permission level.
3. It becomes the place where mockups and code get compared. A single source of reusable rules and parts is a design system, and whether those rules made it into the actual code was previously unknowable without reading the code. Storybook turns that code into something a person can look at.
4. The list of components becomes documentation. Being able to browse the component library — the collection of parts screens are made from — means fewer newcomers rebuilding something that already exists because they couldn't find it.
5. It gives automated checks somewhere to attach. Capture each state as an image, compare against the next release, and unintended visual changes get caught. Accessibility checks, the practice of making a product usable regardless of disability or circumstance, can run per component too.

The cost is one more file that humans maintain. Change a component without changing its stories and the list keeps showing the old appearance, which after a few months becomes a page nobody trusts.

There are three, and they differ in where the checking happens.

The first is building a development-only page inside the app. Put the components at an address like /dev/components and lay them out there. Nothing new gets installed and it takes an afternoon. In exchange, excluding that page from production builds is on you, and nobody builds the controls for changing values state by state, so it ends up a page with a few representative states on it.

The second is skipping the visual surface and writing tests instead. Assert in code how the component renders for given values. Broken output gets caught with nobody watching, and a designer can't open it. A four-pixel spacing error passes the test and gets caught by a human eye. Most teams end up wanting both rather than picking one.

The third is doing the checking in the design tool. Draw every state in the mockup file and treat that as the reference. The limit is plain: a mockup isn't code, so it can differ from what actually got built, and confirming they match still means a person putting two windows side by side.

On a team with fewer than twenty components and two people building them, the first option is often enough. There genuinely is a range where maintaining stories costs more than it returns, and the tool earns its keep once the component count and the number of people touching them both grow.

"There's no story for this state. Please add one."

The place to check it is missing, so fill in the list.

"It works in Storybook and breaks on the real screen."

They've hit the limit of looking at a component in isolation.

"The mockup has two states and this has six. The mockup needs filling in."

Design hasn't kept up with the number of states the code requires.

Pagedeck checks Storybook first whenever a button or an input changes. Theo edits the component, Noa opens the list and works through the six states, noting anything that differs from the mockup on the spot. Under the old approach of building a screen and arranging the conditions, that review took a day. Now it happens in the same sitting as the change.

It has run in the other direction as well. Noa asked for a story covering very long text, and once rendered, the text wrapped to two lines inside the button and the height collapsed. The mockup had no such case, so without the added story this would have been found after release.

The most common mistake is treating it as a replacement for testing. All six states were seen, so verification feels complete. But what gets checked here is the appearance of one component, and real problems tend to appear where components are joined together. How things behave with twenty buttons inside a list, or two components reading the same data differently, does not show up on this page. Start recording visual review as a pass and screen-level problems pile up after each release instead of before it.

The other frequent view is that it's a developers-only tool. It lives beside the code and launches from a command, so it looks that way. In practice half its value disappears when designers don't open it. Catching a mismatch between mockup and code is fastest for the person who drew the mockup, and when only the developer reviews it, the states the mockup never covered get decided with no reference at all. Host it at an address the whole team can open and bring it up during design review.