Design Tokens: Why Products Always Look Different Without Them

In a team, three developers make three different product sections. Everyone has a “basic blue” in their head, but everyone has their own idea of what blue it is. The first is #1A1A2E. The second #1B1B30. The third takes a pipette from Figma, but misses the pixel - it turns #1A1C2E.

Three different blues. The user will not consciously notice. But subconsciously, you’ll feel “something’s wrong” – that blurred feeling that reduces trust in the product.

With the color/brand/primary token, all three have one value - stored in one place and does not diverge anywhere.

## What a token is and why a name is more important than meaning

The token is a named variable. color/brand/accent: #E94560. Not just #E94560.

The difference looks small until rebranding is needed. Then color/brand/accent changes in one file and everything that uses it is updated automatically: Figma, CSS, iOS, Android. #E94560 scattered over 80 files - manual bypass with gaps and bugs.

The second effect that is underestimated is AI agents. #E94560 is simply a number without context. The name color/brand/accent is meaning. Claude Code sees color/brand/accent and understands that it is an accent color, uses it on CTA and active states. Hex-value AI guesses.

## Three-level architecture

The flat system of tokens (one level) breaks down when scaling: it is not clear what to change when rebranding, it is not clear how to add a dark topic, AI does not understand logic. Three levels solve this.

### Level 1 – Primitive (facts without meaning)

Complete visual palette without specifying where it is used.

{
  "color": {
    "blue": {
      "900": { "value": "#1A1A2E", "type": "color" },
      "800": { "value": "#252545", "type": "color" },
      "500": { "value": "#4040A0", "type": "color" }
    },
    "red": {
      "500": { "value": "#E94560", "type": "color" },
      "400": { "value": "#F06080", "type": "color" }
    },
    "neutral": {
      "50":  { "value": "#FAFAF8", "type": "color" },
      "100": { "value": "#F5F5F0", "type": "color" },
      "900": { "value": "#1A1A2E", "type": "color" }
    }
  },
  "spacing": {
    "1": { "value": "4px" },
    "2": { "value": "8px" },
    "4": { "value": "16px" },
    "6": { "value": "24px" },
    "8": { "value": "32px" }
  }
}

Primitive tokens are never used directly in components. Only as a source for the next level.

### Level 2 – Semantic (meaning without details)

Refer to Primitive and give them an appointment. This is the main level with which the components work.

{
  "color": {
    "brand": {
      "primary": { "value": "{color.blue.900}" },
      "accent": {
        "value": "{color.red.500}",
        "comment": "CTA, активные состояния. Не использовать для фонов."
      }
    },
    "background": {
      "page":    { "value": "#FFFFFF" },
      "surface": { "value": "{color.neutral.100}" },
      "elevated": { "value": "#FFFFFF" }
    },
    "text": {
      "primary":   { "value": "{color.blue.900}" },
      "secondary": { "value": "{color.blue.800}" },
      "disabled":  { "value": "{color.neutral.400}" }
    },
    "status": {
      "error":   { "value": "{color.red.500}" },
      "success": { "value": "#2D8A4E" },
      "warning": { "value": "#D97706" }
    },
    "border": {
      "default": { "value": "#E0E0F0" },
      "focus":   { "value": "{color.brand.accent}" }
    }
  }
}

When rebranding, you only change links at the Semantic level. color/brand/accent now points to {color.green.500} – all components are updated without touching Primitive.

### Level 3 Component (only when required)

Tokens for specific components. Add only when there is a real need: multi-brand support, or when one component should look different in different contexts. At the start, do not complicate ahead of time.

## Name: DTCG standard

Design Token Community Group is an open name standard. In 2026 it is supported by Figma Variables, Tokens Studio, Style Dictionary, all AI tools. Pattern: category/role/variant.

The team must understand the purpose of the token from the name – without further explanation.

Rule of verification: can you understand why this token does not know the product? If not, the name is wrong.

## Synchronization: Figma → JSON → Code → AI

Tokens Studio (Figma plugin)
Push with each change
design-tokens. json in git
Style Dictionary in CI
Tokens.css → var(-color-brand-accent: #E94560)
Tokens.js → export const colorBrandAccent = '#E94560' -
Tokens.swift → UIColor for iOS
Tokens.xml → Android resources
↓
AI agents know the names and purpose

In practice: designer changes color in Figma Variables → Tokens Studio fluffs JSON in git → CI launches Style Dictionary → developer sees an update in the next PR. No manual synchronization, no “changed to Figma – transfer to code.”.

## Typical errors in implementation

Miss Primitive level. Create Semantic with hardcut values. When rebranding, you need to change the value in each Semantic token. Primitive is just a link.

One token for multiple assignments. color/interactive/active is used for buttons, menus and checkboxes simultaneously. When you only need to change the buttons, you can’t change the rest.

Tokens in code but not in DESIGN.md. AI doesn't know their names. He keeps writing hex. Tokens work for AI only if they are explicitly listed in the contextual files it reads before starting work.

Create 200 tokens on the first day. No one uses them. Start with the 20-30 most necessary, add as needed.

## How to migrate an existing project without pain

Not the “big move”, but the gradual migration:

1. Find the top 5 colors that are most common (grep by hex or search in Figma)
2. Create Primitive and Semantic tokens for them
3. Transfer one component to them: Button
4. Check what works in Figma and in code, sync is configured
5. Next component

After a month of work in this mode, most of the system is on tokens – without stress and without a separate “migration project”.

## Prompt for auditing and creating tokens

Analyze the project and help create a token system.

Step 1: Find all unique hex color values in CSS, Tailwind, inline styles.
For each: the value, how many times it occurs, in which files.
Score by frequency - top 15.

Step 2: For the top 15, suggest:
Primitive token: color/[hue]/[shade] (e.g. color/blue/900)
Semantic token: color/[category]/[role] (e.g. color/brand/primary)
Comment: When to use what is forbidden

Step 3: Generate JSON in DTCG format for all tokens.
Create CSS Custom Properties for the Semantic level.

Purpose: ready-made design-tokens. json can be connected directly through Tokens Studio.

## Why “just negotiate” doesn’t work without tokens

The most common way to manage colors without tokens is Figma Styles. You create the Primary Blue style, you apply it to the components. It seems to be a single source.

Problem one: Styles don’t sync to code automatically. The developer sees "Primary Blue" in Figma and writes #1A1A2E in code manually. The next time you change color in Figma, the old value remains in the code.

Problem two: AI can't see Styles. When an agent generates a component, they don’t know you have a Primary Blue style. It sees the hex values in the codebase and tries to guess which is the “basic blue.”.

Tokens solve both problems: they exist in Figma Variables, and in CSS Custom Properties, and in the JSON file that reads AI. One source of truth that is available to all three audiences simultaneously.

## Practical issues in implementation

"Tokens Studio is free?" Yes, the basic version is free and covers most scripts. Paid features are needed when working with several brands or complex workflow - you do not need to pay for one product.

“Do you need to migrate all the components first?” Start with one. Create Tokens for Button – Translate Button to Figma to Variables, Translate Button to CSS Custom Properties. Check what works. Then Input. Then Card. Migration is gradual, not all at once.

** What if the developers are against it?* Show me the price. Calculate how many hours developers spend answering “what color?” per month. Multiply by bet. Tokens Studio is free and takes an hour to install. The savings start right away.

"How to name tokens if we don't have a design system?" Start with simple semantic names: color/brand/primary, color/text/default, color/background/surface. Don’t think of a complex hierarchy, just name what is. It is easier to improve the structure later than to migrate from a hardcut.

● Three levels: Primitive → Semantic → Component
Primitive is not used directly in components
● Semantic: category/role/variant, the appointment is read by name
Comments in tokens: when to use what is prohibited
Tokens Studio syncs Figma Variables   JSON
Style Dictionary: CSS/JS/Swift/XML from a single JSON
ESLint rule: banning hex in JSX and CSS
Tokens in DESIGN.md with purpose for AI