Most design systems don’t fail technically. They fail socially. The components are fine, but adoption stalls, teams fork, and the system slowly becomes a museum.

I’ve worked on systems shared across several products, from tokens and component libraries to documentation and adoption. The pattern is almost always the same: the system succeeds when it saves people time today, and fails when it only promises consistency someday.

1. Treat the system as a product

It has users (engineers, designers and product managers), a roadmap and a value proposition. If using the system is slower than not using it, people will route around it, and they’ll be right to.

So measure adoption like you’d measure any product metric:

  • The share of new screens built from system components.
  • The number of local overrides and detached components.
  • The time from “we need a component” to a shipped, documented one.

The last one matters most. If a team waits three sprints for a new component, they’ll build their own in one afternoon, and you’ve just started a fork.

2. Tokens before components

Design tokens are the contract between design and code. Get naming, theming and structure right at the token layer and everything above it becomes consistent by default, including dark mode and accessibility.

Name tokens in layers. A primitive says what a value is (blue-600). A semantic token says what it’s for (color-action). Components only ever use the semantic layer. That’s what lets you rebrand, add a theme or fix a contrast problem in one place instead of in four hundred.

It doesn’t need to be big. This website runs on eleven colour tokens, from ink and concrete to cobalt-on-dark, and every page is built from them.

3. Ship it in code, not just in Figma

A system that only lives in a design file is a suggestion. The real source of truth is the component engineers import, because that’s what ships.

Keep design and code in step: the same names, the same variants, the same states. When a designer says “secondary button, small”, an engineer should be able to type exactly that. As a designer who also builds the front end, I find the most useful thing I can do is design the component and write it, so nothing is lost in translation.

4. Document the decisions, not just the props

The most valuable part of a mature system isn’t the component API. It’s the accumulated judgment about when and why to use each pattern. Capture that.

  • Show do and don’t examples taken from your real product, not abstract mock-ups.
  • Write down the reason behind a rule, so people can apply it to cases you didn’t foresee.
  • Keep a changelog people actually read: what changed, why, and what they need to do.

5. Make contributing easier than forking

Teams will always find needs the system doesn’t cover yet. The question is whether that work flows back in or stays stranded in one product.

Give people a clear path: propose, build it in their product first, then promote it to the system once a second team needs it. Review quickly. And when you retire something, deprecate it loudly and give people a way out, not a silent breaking change.

A design system scales when it makes the right thing the easy thing.