Design Systems 101: Building Your First Component Library

A design system is not a Figma file. It is a small library of decisions — how spacing scales, how colours combine, how buttons behave — and the documentation that helps everyone use them. Start small.

The minimum viable system

• Colour tokens — primary, secondary, neutral scale, semantic (success/warning/error).
• Type scale — five sizes, two weights, line-height ratios.
• Spacing scale — four to eight values on a 4px grid.
• Radius and shadow scale — three values each, no exceptions.
• Five core components — Button, Input, Card, Modal, Toast.

The naming discipline

Use semantic names, not visual ones. --color-primary, not --color-blue-500. The day brand changes, semantic names survive a one-token edit; visual names cause a global find-and-replace.

Documentation that gets read

Every component needs three things: a working example, the props table, and the do-and-don’t section. Storybook handles the first two; the third is a paragraph you write yourself and is the most-read part of the docs.

How to roll it out

Resist the urge to migrate the entire codebase on day one. Ship the tokens, ship the five components, use them for new features, and let the rest follow opportunistically. A six-month gradual migration beats a one-month rewrite that no one finishes.

The team angle

One owner per system makes it work; a committee makes it stagnate. The owner triages requests, decides what is in scope, and writes the migration guides. Without a clear owner, design systems decay into “another folder no one updates”.