Demo article. This text is generated and exists to test the content workflow. Review, adapt or remove it before launch.
Most design systems do not fail because the components are bad. They fail because nobody uses them. The library is beautiful, the documentation is thorough, and six months later every product team still has its own button. The problem is rarely technical.
I learned this the hard way while building a design system for twelve product teams. Here are five lessons that made the difference.
1. Tokens before components
The first instinct is to build components. Buttons, inputs, cards, modals. It feels productive. The problem is that components encode decisions, and those decisions are usually wrong until you have agreed on the primitives.
We started with tokens: colour, spacing, typography, radii, shadows. We gave them semantic names (surface, text-muted, border-strong) instead of colour names. That one decision made the system usable before a single component existed. Teams could adopt the visual language without waiting for us to build their specific use case.
Tokens are also easier to govern. Changing a token is a global decision with a small surface area. Changing a component API affects every consumer. Start where the leverage is highest.
2. Adoption is the product
A design system is a product for internal teams. Its success metric is not the number of components. It is the number of teams that use them.
We treated migration as a product problem, not a compliance problem. There was a codemod for the most common patterns, a weekly office hour, and a clear incentive: smaller bundles, fewer UI bugs, faster reviews. Teams could migrate when it suited their roadmap. No one was forced into a big-bang rewrite.
The result was not instant, but it was durable. After five months, all twelve teams had migrated. More importantly, they kept using the system after the initial push, because it made their work easier.
3. Documentation is part of the API
If a component is not documented, it does not exist. A prop table is not documentation. Good documentation answers three questions:
- When should I use this component?
- When should I not use it?
- What happens in the edge cases — focus, error, loading, disabled, keyboard?
We wrote a short page for every primitive and every component, with a live example and a “do not use” section. The “do not use” sections were the most valuable. They prevented the slow accumulation of variants that turn a system into a museum.
4. Performance budgets make decisions easier
Design system discussions can become philosophical. Performance budgets make them concrete.
We set a budget for the initial JavaScript of the largest product page. Every new component had to fit within the budget, or the team had to explain why it was worth the cost. That single constraint settled more debates than any style guide.
It also changed the component design. We stopped building “flexible” components with twelve props and started building primitives that teams could compose. Less code, fewer edge cases, better performance. The budget was not a restriction; it was a design tool.
5. Governance beats perfection
The perfect system is the one that never ships. We deliberately shipped a small system early and iterated in public.
Governance looked like this:
- A weekly office hour for questions and proposals.
- A lightweight RFC for new components: problem, use cases, API sketch, accessibility notes.
- A clear rule: if a pattern appears in three teams, it becomes a candidate for the system. Before that, teams own their solution.
- A deprecation policy with a migration path.
This kept the system small and the teams autonomous. It also made the system’s boundaries legible. People knew what belonged in the system and what did not.
The real deliverable
The real deliverable was not a component library. It was a set of decisions that made twelve teams faster and more consistent. The components were the visible part; the tokens, documentation, migration path and governance were the actual work.
If you are starting a design system, resist the urge to build a catalogue. Start with tokens, pick a small number of high-leverage components, and treat adoption as the product. The rest follows.