Building a Design System from Scratch: Lessons Learned

Why bother

On a three-person project a design system is overhead. On a marketplace with fifteen order states, six user roles and two years of roadmap, it is the difference between a product and a pile of screens.

We started ours in week three, which was two weeks too late.

Start with tokens, not components

The temptation is to design a button first. Resist it — a button is downstream of a dozen decisions you have not made yet.

• Spacing. One scale, and every gap on every screen comes from it.
• Type. A named scale with line heights attached, so nobody picks a size by eye.
• Colour. Roles, not values: surface, border, body, muted, accent.
• Radius and elevation. Two of each at most, until something genuinely needs a third.

Components come in threes

Do not build a component until three real places need it. Two usages produce an abstraction shaped like a coincidence; three tell you which parts actually vary.

The rules that kept it alive

• Document the decision, not just the value. Anyone can read a hex code; nobody can reconstruct why it is that one.
• Test with real content. Lorem ipsum has no long names, no missing images and no empty states.
• Give the system an owner. A design system without one converges on whatever shipped most recently.

A year in, the marketplace has roughly forty components and almost no one-off styling. The last new screen took a day and the first took a week. That gap is the entire return.