Treat your design system like a product, not a library
A design system succeeds when teams adopt it, not when its Storybook looks complete. What building and modernizing one taught me about adoption metrics, API design, and reading team workarounds as bug reports.
TL;DRTrack adoption as your north-star metric, read team workarounds as bug reports, keep component APIs small with clean escape hatches, and modernize without a rewrite. The system succeeds when teams choose it daily, against the alternative of just writing CSS.
The design system I inherited had a complete Storybook and an adoption problem. Beautiful components, documented APIs, and product teams styling around half of them anyway.
The fix wasn't more components. It was treating the system as a product with users, churn, and a roadmap.
Users, not consumers
Product teams don't "consume" a design system. Every day they choose it, or they choose plain CSS. That framing changes everything:
- Adoption is the north-star metric. Not component count, not Storybook pages. What fraction of new UI ships on-system? We tracked it. When it dipped, the system had failed, not the teams.
- Churn has causes. Every wrapper component a team writes around yours is a bug report in disguise. We read wrappers as reviews: what's missing, what's too rigid, what's too complicated.
FROM PRODThe wrapper audit is humbling. Teams don't wrap your component because they enjoy abstraction. They wrap it because your API made the common case annoying. The wrapper is the user manual you didn't write.
API design is the whole game
A component with a clean API gets used. One with 40 props gets forked. Rules that held up:
- Few props, strong defaults. The common case must be zero-config. If the default state isn't the common state, the defaults are wrong.
- Escape hatches are features. Teams need the 5% case. Design a clean escape (a slot, a token, a render prop) or they'll invent an ugly one.
- Breaking changes have a migration path or they don't ship. Codemod where possible, changelog always, deprecation windows real.
Modernizing without a rewrite
When we modernized the library, a ground-up rewrite was on the table. We didn't take it. Instead:
- New primitives landed alongside old ones, behind the same package
- Teams migrated screen by screen, with the old API still working
- Deprecations were enforced by lint, not by hope
The rewrite would have produced a perfect library nobody had time to adopt. Adoption is the metric, remember.
The uncomfortable part
Owning a design system means breaking your own components. The variant you designed in good faith gets misused in production, and the evidence says your API was wrong.
Ship the fix, own the changelog, move on.
A design system is a product whose users are engineers with deadlines and alternatives. Serve them like customers and adoption follows. Serve them like an audience and they'll route around you.