When I started building the design system at Nebula Labs, I made every beginner mistake in the book. I over-abstracted, over-documented, and built components nobody asked for.
Here's what I learned after two years of iteration.
Start with tokens, not components
The first thing you should build is not a Button. It's your spacing scale. Your color palette. Your type ramp. These are the atoms that every component will reference, and getting them wrong means rebuilding everything later.
I settled on an 8px grid for spacing, a 1.25 type scale, and a semantic color system with three tiers: primitive (raw hex values), semantic (background, foreground, border), and component (button-primary, input-border).
Build what you need, not what you might need
Version one of our system had 47 components. We used 12 regularly. The rest rotted — no one updated them, no one tested them, and they became a source of bugs rather than productivity.
Now I follow a rule: a component earns its place in the system only after it's been copy-pasted across three or more features. Until then, it lives in the feature code.
Variants are a spectrum
Not everything needs to be a prop. I've seen Button components with 15 props and a 200-line switch statement for styling. The better approach: a small set of meaningful variants (solid, outline, ghost) and composition for everything else.
The documentation is the product
A design system without documentation is just a folder of components. We invested heavily in Storybook — not just for visual testing, but as the canonical reference for how to use each component. Every component page includes: when to use it, when not to use it, and at least two real-world examples.
Closing thoughts
A design system is never done. It's a living product that serves your team. The best ones are small, opinionated, and well-documented. Start there.