Starting a design system with tokens, not components

When a team decides it needs a design system, the first instinct is to build a component library: buttons, cards, modals, a date picker. Six months later there are forty components in Figma, a partial implementation in code, and the product still looks inconsistent because every component made its own decisions about color and spacing. We have seen this pattern often enough that we now start almost every design system engagement somewhere less glamorous: the tokens. Tokens are the named decisions underneath every component, and getting them right first makes everything that follows faster and more consistent.

What tokens are and why they come first

A design token is a named value for a design decision: a color, a font size, a spacing step, a border radius, a shadow, a duration. Instead of a button using #1F4ED8 and 12 pixels of padding, it uses color.action.primary and space.3. The value lives in one place and is referenced everywhere.

Starting with tokens pays off in three ways. First, consistency arrives immediately, even on screens that do not use any shared components, because designers and developers pick from the same constrained set. Second, rebrands and theming become changes to values, not hunts through hundreds of files. Third, components become simpler to build, because the hardest decisions have already been made.

Structure tokens in layers

The most useful structure we have found has three layers, and the discipline of keeping them separate is what makes a system flexible.

1. Primitive tokens describe the raw palette: blue.600, gray.100, size.16. They have no meaning, just values.
2. Semantic tokens describe purpose: color.text.default, color.surface.raised, color.border.danger. They reference primitives.
3. Component tokens, used sparingly, describe specific parts: button.primary.background. They reference semantic tokens.

Components should use semantic tokens almost exclusively. That way, dark mode, a high-contrast theme or a sub-brand is a matter of remapping the semantic layer to different primitives, without touching components.

{
  "color": {
    "text": {
      "default": { "value": "{gray.900}" },
      "muted":   { "value": "{gray.600}" }
    },
    "action": {
      "primary": { "value": "{blue.600}" }
    }
  }
}

Tokens are the named decisions underneath every component. Get them right first and the components almost design themselves.

Decide the scales deliberately

Token work is really decision work. The value of a system comes from constraining choices, so each scale should be as small as it can be while still covering real needs.

• Spacing: a base unit, usually 4 pixels, with a scale of eight to ten steps. More steps invite inconsistency.
• Type: a modular scale with six to eight sizes, each paired with a line height and letter spacing. Name them by role, such as body, small and heading levels, rather than by pixel value.
• Color: primitive ramps of nine or ten steps per hue, with semantic tokens that are checked for contrast. Every text and background pairing used in semantic tokens should meet WCAG AA at minimum.
• Radius, elevation and motion: three or four steps each is usually enough.

Audit the existing product before deciding. On a recent engagement for a SaaS client, the audit found 43 distinct grays and 27 spacing values in production CSS. Collapsing those to 10 grays and 9 spacing steps took a week of negotiation and removed a surprising amount of visual noise on its own.

Make tokens a shared source of truth

Tokens only work if design and code use the same ones. That means a single source, usually a JSON file in a repository, that generates outputs for every platform: CSS custom properties for the web, variables in Figma, and platform formats for iOS or Android if needed. Tools like Style Dictionary handle the transformation, and a simple CI step can publish updated tokens as a package.

Keep the pipeline boring. The goal is that a designer changing a semantic color in Figma and a developer changing it in code are editing the same source, reviewed through the same process. When that loop exists, drift between design and implementation drops sharply.

Naming deserves real care because it is hard to change later. Favor names that describe purpose and are predictable: category, then property, then variant, then state. Avoid names tied to appearance, such as color.lightblue, in the semantic layer; the value will change and the name will lie.

Plan for governance from the start as well. Someone needs to own the token set, review proposed additions and say no to one-off values. A lightweight process works: a request with the use case, a short review by a designer and an engineer, and a release note when tokens change. Without it, the palette slowly grows back to where it started.

Then build components on top

With tokens in place, component work becomes faster and more focused. Start with the components that appear most often in the product, typically buttons, form inputs, typography, cards and layout primitives, and build them in code alongside design so that the library reflects reality. Document each with usage guidance, not just variants. A design system that shows what a component looks like but not when to use it will still produce inconsistent products.

Our design systems engagements usually deliver tokens and a first set of 10 to 15 core components within eight to ten weeks, with the rest following as product teams need them. The token layer also underpins our web UI design work, which means new pages inherit the system rather than reinventing it, and it makes a later accessibility audit far easier because contrast is solved at the source.

Start your system on solid ground

If your product has outgrown its styles, or a component library has stalled, we can help you set up tokens and a practical path forward. Get a fixed-price quote within 24 hours.