Design systems that scale: what we learned building for 10M users

The first design system we shipped was, in retrospect, a component library with ambitions. We had a Button, a Modal, an Input, a Card. They were consistent, well-documented, and useful. When the product scaled from 100k to 10M users and from one team to twelve, the cracks appeared.

Components solve the wrong problem at scale. What scales is a shared language — a set of decisions that propagate through every layer of the product without anyone having to think about them. That's a design system. Here's how the distinction played out for us.

Tokens are the foundation, not an afterthought

Design tokens — the named values for colour, spacing, typography, shadow, and border radius — are the part of a design system that actually propagates. When your primary button uses `color.action.primary` rather than `#FF6B35`, that token can be updated once and propagate to every surface, every platform, every theme.

We rebuilt the system token-first. Every design decision that a component uses was expressed as a token before a component was written. The result was that our dark mode implementation — which came two years after the initial system — took three days, not three months.

Components should encode decisions, not expose options

A common anti-pattern is the 'flexible' component that accepts 40 props. The reasoning is good — you want to be able to use it everywhere. The outcome is that the component becomes a rendering engine with no opinion, and the design system provides no consistency benefit.

• Each component should represent one decision, not a collection of options
• If you need two behaviours, make two components with clear names
• Props should control state and content, not appearance
• Escape hatches (className overrides) should be explicit and documented as exceptions

The goal of a design system is to make the right thing easy and the wrong thing hard. If it makes everything equally easy, it has no opinion — and no value.

Documentation is the product

At 12 teams, the bottleneck was never the components. It was engineers not knowing what existed, designers not knowing what was buildable, and both groups spending time in Slack asking each other questions that a good documentation site would have answered.

We treat the documentation site as a first-class product. It has an owner, a roadmap, and usage analytics. Every new component ships with a live playground, a prop table, accessibility notes, and at least two usage examples — one showing correct use, one showing a common misuse to avoid.

Versioning and migration

The hardest operational problem is backwards compatibility. When a component needs to change in a breaking way, you have two bad options: big-bang migration across twelve teams, or maintaining two versions indefinitely. We now write automated codemods for every breaking change. Teams run the codemod, review the diff, and migrate. The investment in codemods is always repaid within the first two uses.