We have now watched four design systems die. Different companies, different tools, the same autopsy: a beautiful library, a documentation site nobody opened, and a product team quietly building one-off components next to it.
The usual explanation is "we ran out of time to document it." We no longer believe that. Every one of those systems had documentation. What they did not have was a reason for anyone to keep using it on a bad Tuesday.
A system built in isolation is a proposal, not a system
The failed ones were all built the same way: a designer disappeared for two or three months, then presented a finished library. It was complete, consistent, and completely disconnected from the screens the team was actually shipping that quarter.
The first time a real feature needed something the library did not have, someone made an exception. The second exception took ten minutes to justify. By the fifth, the library was a museum.
A component nobody had to fight for is a component nobody defends.
What we do instead
- Build it out of real screens. No component enters the library until it has appeared in two different places in the actual product. The second appearance is what proves it is a pattern and not a one-off.
- Name an owner per section. Not a committee. One person who gets pinged when a button needs a new state.
- Budget the maintenance out loud. We quote design system work as an ongoing line, not a one-off deliverable. A system with no maintenance budget has a scheduled death date, and everyone should know it.
- Make the shortcut the correct path. If reaching for the library is slower than copy-pasting a div, the library loses. Every time.
Documentation is the last 10%
We still write it. But we write it after the system has survived contact with three or four features, and we keep it in the same place developers already live — the repo, not a separate site that requires a second login.
The one system of the four that is still alive two years later has the worst documentation of the lot. It also has two named owners, a monthly hour blocked for cleanup, and a rule that new components arrive with the feature that needed them. That turned out to matter more than any page of guidelines.