Why I Build Design Tokens Before Components

When teams decide to build a component library, the instinct is to start with components. A button. A card. A modal. Visible progress feels good.

I do it backwards. Tokens first, components second. This article explains why.

The Problem With Components First

Here is what happens when you start with components:

1. You build a button with background-color: #1B5DEF
2. Design changes the blue to #2563EB
3. You update the button
4. You realize the link component also uses blue
5. You update the link
6. You find three more places using the old blue
7. You question your career choices

Hard-coded values in components create a maintenance nightmare. Every design change becomes a scavenger hunt.

What Design Tokens Actually Are

A design token is a named value that represents a design decision.

:root {
  --color-blue-500: #1B5DEF;
  --color-text-primary: #F4F4F4;
  --space-4: 1rem;
  --font-mono: 'JetBrains Mono', monospace;
}

That is it. Named CSS custom properties. Nothing fancy.

The power is not in the technology. It is in the constraint: every visual value in your system must have a name.

Why Tokens First Changes Everything

Design Changes Become Trivial

When design changes the blue, you update one token. Every component using that token updates automatically. The scavenger hunt disappears.

Consistency Becomes Default

When developers can only choose from named tokens, inconsistency becomes harder. You cannot accidentally use #1B5DEE (one character off) because that value does not exist in your system.

Communication Improves

“Use color-blue-500” is clearer than “use #1B5DEF”. Tokens give your team a shared vocabulary for design decisions.

Theming Becomes Possible

Want dark mode? Swap the token values. Want a client-specific theme? Swap the token values. The components do not change.

What a Token System Looks Like

At MapVX, I built a system with 50+ tokens before writing any components. Here is the structure:

Colors

/* Brand */
--color-blue-500: #1B5DEF;
--color-orange-500: #E25327;

/* Neutrals */
--color-gray-100: #F4F4F4;
--color-gray-900: #121212;

/* Semantic */
--color-text-primary: var(--color-gray-100);
--color-text-secondary: rgba(244, 244, 244, 0.7);
--color-bg-primary: var(--color-gray-900);

Spacing

--space-1: 0.25rem;
--space-2: 0.5rem;
--space-3: 0.75rem;
--space-4: 1rem;
--space-5: 1.5rem;
--space-6: 2rem;

Typography

--font-display: 'Instrument Serif', serif;
--font-mono: 'JetBrains Mono', monospace;

--text-xs: 0.75rem;
--text-sm: 0.875rem;
--text-md: 1rem;
--text-lg: 1.25rem;

Motion

--motion-fast: 150ms;
--motion-medium: 300ms;
--ease-standard: cubic-bezier(0.4, 0, 0.2, 1);

The Process

Week 1: Audit and Extract

Go through the existing designs (Figma, existing code, wherever). Extract every unique value: colors, spacing, font sizes, shadows, border radii.

You will find chaos. Seventeen slightly different grays. Spacing values that make no sense. This is normal.

Week 2: Rationalize and Name

Consolidate the chaos into a coherent system. Seventeen grays become five. Random spacing becomes a scale.

Name everything. Naming is hard. Do it anyway.

Week 3: Document and Implement

Create a reference document showing all tokens with their values and usage guidelines. Implement the tokens as CSS custom properties.

Week 4: Migrate Incrementally

New components use tokens exclusively. Old code is migrated opportunistically, not all at once.

The Tradeoff

Building tokens first slows down initial component development. You spend time on infrastructure that does not look like progress.

At MapVX, the token system took about a week to build. During that week, we shipped zero components.

But every week after that was faster. Design changes that would have taken hours took minutes. New components that would have required design decisions were straightforward: just use the tokens.

The upfront investment paid for itself within a month.

When to Skip This

Not every project needs a formal token system.

• One-off landing pages: Just write the CSS. The maintenance cost is low.
• Very small teams: If one person makes all design decisions, tokens add overhead without much benefit.
• Prototypes: Speed matters more than architecture. Hard-code everything.

The Broader Lesson

Tokens first is really about sequencing. Do the foundational work before the visible work.

It feels slow. Stakeholders want to see components. But the time you “lose” on infrastructure, you gain back (with interest) during development and maintenance.

This applies beyond design systems. Database schemas before API endpoints. Contracts before implementations. Foundations before features.