Building Design Systems at Scale

After two years of building and maintaining a design system with over 120 components, I've collected a set of hard-won lessons about what works — and what quietly falls apart.

Start with the spec, not the code

The single biggest unlock was writing engineering specs in Figma before touching any code. Each component gets a page that defines every prop, state, slot, and edge case. When the spec is tight enough, implementation becomes almost mechanical.

This flips the usual workflow. Instead of designers handing off a static mockup and engineers interpreting it, the spec becomes a shared contract. Ambiguity drops. Review cycles shrink.

Tokens are the foundation

Every visual decision — color, spacing, radius, shadow, motion — flows from tokens. Not from Tailwind classes, not from hardcoded values. Tokens.

In practice this means a single source of truth in Figma variables that maps 1:1 to CSS custom properties. When the brand evolves, you change the token. Everything downstream updates.

Test what matters

Full coverage sounds good on paper. In practice, 85% line coverage with focused tests on interaction, accessibility, and edge cases catches more real bugs than 100% coverage that tests implementation details.

We use Vitest with Vue Testing Library. The rule is simple: test what the user sees and does, not how the component is wired internally.

Ship incrementally

A design system is never done. The best approach is to ship small, stable increments. Each component goes through: spec → implementation → review → docs → release. No batching. No big-bang launches.

This keeps the system honest. If a component is hard to document, it's probably too complex. If it's hard to test, the API needs work.