Storybook
Storybook renders a component in a named, reproducible state. That single property is what turns a documentation tool into a testing one, and it is the reason this tool is load-bearing here rather than nice to have.
One story per contracted state
Section titled “One story per contracted state”The rule that connects it to the component library:
Every state in the contract has a story. A state without a story is a gap anyone can see.
That inverts the usual relationship. Stories are not illustrations of a finished component; they are the specification it is built against, written before or alongside the implementation.
The nine states worth enumerating by default — rest, hover, focus-visible, active, disabled, loading, error, empty, read-only — are the ones from the design system. Not all apply to every component; deciding that one does not apply is a decision, and it should be a visible one.
Four things run against those stories
Section titled “Four things run against those stories”| Consumer | Gets |
|---|---|
| Interaction tests | A component in a known state, without a page around it |
| Accessibility scans | A violation attributed to a component rather than to a screen |
| Visual regression | A small, owned snapshot with a small diff |
| Designers | The real rendered component in every state, not a screenshot of the happy path |
The last row is the one that changes team behaviour. A designer reviewing the running component finds things a mockup review structurally cannot — the text that wraps, the state that was skipped, the focus ring that vanished.
Contract-driven development
Section titled “Contract-driven development”Building a component in Storybook means building it against its declared states before it is wired into a page or connected to data.
This is the interface analogue of building against a mocked API instead of waiting for the provider. Both remove a dependency on something that is not ready, and both do it by working against the contract rather than around it.
The practical benefit is felt most on the states nobody can reach on demand: an error from a service that rarely fails, an empty list in a system full of data, a slow response on a fast network. In a story, each is a prop.
The pattern catalogue
Section titled “The pattern catalogue”A Storybook is also a catalogue of the interface’s pattern vocabulary, and its value there is mostly in what it prevents.
Without a catalogue, the fifth developer needing a button writes a fifth button — not out of carelessness, but because finding the existing one costs more than rewriting it. With one, reuse is the path of least resistance, which is the only way reuse ever actually happens.
That makes findability a real design concern for the Storybook itself. A catalogue nobody can search is a catalogue nobody uses, and the fifth button gets written anyway.
The failure modes
Section titled “The failure modes”The stale Storybook. Published, out of date, quietly diverged from production. It is worse than none, because people trust it. The cure is that it is built and deployed from the same commit as the application, every time.
The happy-path-only Storybook. One story per component, showing it working. All of the maintenance cost, none of the fixture value, and no way to see which states were never designed.
The Storybook nobody runs tests against. At that point it is a gallery. Real, useful, and not a contract — see contract-first on the difference.
Where it connects
Section titled “Where it connects”- Component library is the contract the stories express.
- Interaction tests and accessibility tests are what run against them.
- Component scaffolding generates the story set from the contract, so the enumeration is not a manual chore.