A client review goes sideways two weeks before launch. The designer signed off. The engineer signed off. Then the client opens the app and says it doesn't look like what they were shown. The cause, according to one studio's postmortem, was mundane: their standalone Storybook site shipped its own slimmed-down CSS entry point and never picked up form resets the production app added later (ScriptWalker). Two separate builds, two separate truths, and nobody noticed until a client did.
That's the real failure mode behind "Storybook drifts from shipped components." It's not that teams forget to update stories. It's that Storybook, by default, is a second build of your UI — its own bundler config, its own CSS pipeline, its own mocked data — sitting next to the one that actually ships. Treat two builds as one source of truth long enough and they stop agreeing.
The Split Nobody Designed On Purpose
You can watch this happen in real time in an open GitHub issue from a small team maintaining a mail client. Their design system and their product playground shared one Storybook instance, but the playground screens were never actually built — so engineers hand-rolled copies of sidebars and app shells to fake them, and those copies drifted from the real thing almost immediately (remit-mail/reader #1278). The fix wasn't a documentation policy. It was architectural: separate the design system's Storybook from the playground's, and stop letting speculative screens masquerade as shipped ones. Drift here wasn't a discipline problem. It was a structural one — the moment you let Storybook host things that aren't real product surfaces alongside things that are, you've built a system where nobody can tell which stories to trust.
Generated Docs Beat Hand-Maintained Docs, Every Time
A second pattern shows up in Equinor's design system repo, where component doc pages across web and native were written by hand in slightly different shapes — different link orders, different install commands, prop tables typed out manually that broke the instant a prop changed (equinor/design-system #5604). Their fix is the more durable version of the same lesson: generate what you can from the actual types and story files, and reserve hand-writing for the parts that genuinely require human judgment — usage notes, accessibility guidance, a one-paragraph summary. Anything generated from code can't drift from code. Anything typed by a human, eventually will.
The Nuclear Option: Stop Building a Second Copy
ScriptWalker's team took this reasoning to its logical end and turned Storybook off entirely. Their replacement is a /_ui route inside the actual production app — same compiled Tailwind output, same Blade components, same layout — that renders every component state on one page, gated by Playwright screenshot diffs in CI (ScriptWalker). Their own framing is honest about the tradeoff: Storybook earns its keep when you have a dedicated frontend team and components genuinely shared across products. For a small studio shipping self-contained apps with little cross-project reuse, a second site was just one more thing that needed syncing, and they'd rather have zero copies than two that disagree.
I don't think every team should delete Storybook — most of this publication's readers share components across more surfaces than a three-person studio does, which is exactly the case where isolation-first development still pays for itself. But the principle generalizes past the tool: the closer your documentation renders from the artifact that actually ships, the less there is to drift. A separate Medium essay on design handoff makes a parallel point about Figma: the moment a file sits behind a login wall or styles itself as the contract rather than the conversation, readers who need an answer get a 403 instead of the truth (Sebastian Balderas Espinosa). Storybook has the same failure mode when it's treated as a contract instead of a mirror.
Storybook's newer MCP integration is worth watching for a related reason — it lets coding agents pull live component metadata, stories, and tests directly rather than guessing at patterns from memory, with early benchmarks showing meaningfully better component reuse (Storybook). If agents start generating UI straight from the same source the docs are generated from, that's one more copy removed from the chain. The next thing to check isn't whether teams adopt the MCP server — it's whether they still maintain a parallel hand-written doc page once an agent can read the types directly.