Tokens first, components later

The first three weeks I spent designing components. Buttons, inputs, cards. Everything in Figma, everything “pixel perfect”, everything pretty. When the devs opened the file, they used two of the fourteen components I had designed.

Not because they were ugly. Because they didn’t know when to use them.

The mistake that almost cost me the project

I thought the system was the component library. Turns out the system is the language the components speak. If the language isn’t clear, the components are noise.

I got it by reading about Design Tokens and watching how big teams (GitHub Primer, Shopify Polaris) solve it: tokens first, components later. Always.

The pivot: reversing the order

Instead of shipping finished components, I delivered the tokens first: three JSON files with colors, spacing, and radii. The devs could use them immediately, without having to decide between Button/Primary or Button/PrimaryLarge.

The difference was immediate. Engineering started using the tokens without asking me. And when I finally shipped the components, they already knew the language.

/* tokens.css */
:root {
  --color-bg-canvas: #F8FAFC;
  --color-fg-default: #0F172A;
  --color-brand-600: #6125E7;
  --space-1: 4px;
  --space-2: 8px;
  --space-4: 16px;
  --radius-md: 8px;
}

What I learned

Three things I take from that project:

1. Tokens first, components later. The system is the language, not the library.
2. Components are a consequence. If the language is clear, components pick themselves.
3. The first useful deliverable is invisible. It’s a JSON the team consumes in silence.

If I had to do it again, I’d start there. And I wouldn’t wait three weeks to realize it.