# Design tokens explained: from primitives to components

> Design tokens are the named values that define your visual language - colors, spacing, type, shadows. Here's how the token hierarchy works and why it matters for keeping design and code in sync.

- Source: https://flashdsm.com/blog/design-tokens-explained
- Published: 2026-07-01
- Author: Flash DSM Team
- Category: Deep dive
- Reading time: 8 min read

---

## What is a design token?

A design token is a named value that represents a design decision. Instead of writing `color: #3B82F6` in your CSS, you write `color: var(--color-primary)`. The token `--color-primary` *is* the design decision - "our primary color is this blue" - and the value `#3B82F6` is the current implementation of that decision.

This matters because design decisions and their implementations change at different rates. The decision "our primary color" might live for years; the exact hex code might be updated every quarter as the brand evolves. Tokens let you update the implementation without changing every place that uses the decision.

## The token hierarchy

Design tokens work in layers. Flash DSM uses three layers:

### Layer 1: Primitives

Raw values - colors, sizes, weights. No semantic meaning attached.

```css
--color-blue-500: #3B82F6;
--color-blue-600: #2563EB;
--spacing-4: 16px;
--font-size-base: 16px;
```

Primitives are the source of truth for every specific value in your system. You usually have a lot of them - a full color scale might have 7–11 steps per hue.

### Layer 2: Semantic aliases

Aliases map a meaning to a primitive. They answer *what is this for*, not *what is this value*.

```css
--color-primary: var(--color-blue-500);
--color-interactive: var(--color-blue-600);
--color-background: var(--color-neutral-950);
--color-text-primary: var(--color-neutral-50);
--space-component-gap: var(--spacing-4);
```

Semantic tokens are what you use in components. When a designer says "change the primary color to purple", you update one primitive value (`--color-blue-500: #7C3AED`) and every semantic alias that references it updates automatically - across the entire codebase.

### Layer 3: Component tokens (optional)

For large design systems, it helps to have component-level tokens that reference semantic tokens:

```css
--button-background: var(--color-primary);
--button-text: var(--color-on-primary);
--button-radius: var(--radius-button);
--card-background: var(--color-surface);
--card-border: var(--color-border-subtle);
```

Component tokens create a contract between the design system and each component. The button only uses `--button-*` tokens, making it trivial to theme or replace.

## What types of tokens exist?

A complete design system has tokens for every visual decision:

| Category | Examples |
|----------|---------|
| **Color** | Primary scale, semantic (success/warning/error), surfaces, borders |
| **Typography** | Font families, size scale, weights, line heights, letter spacing |
| **Spacing** | Base unit multiples (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px) |
| **Border radius** | Button radius, card radius, input radius, pill |
| **Shadow** | Elevation levels (shadow-sm through shadow-2xl), colored glow effects |
| **Motion** | Duration (fast/base/slow), easing functions (ease-in, ease-out, spring) |
| **Border** | Width (thin/base/thick), style |

Flash DSM generates all of these categories in parallel, so you get a complete, internally consistent system - not just a color palette.

## Tokens and dark mode

One of the biggest advantages of semantic tokens is dark mode. Without tokens, dark mode requires duplicating every color rule:

```css
/* Light */
.card { background: #ffffff; color: #111827; }
/* Dark */
.dark .card { background: #1f2937; color: #f9fafb; }
```

With semantic tokens, you change the *value* of the token per theme, and every component that uses it updates automatically:

```css
:root {
  --color-surface: #ffffff;
  --color-text-primary: #111827;
}

[data-theme="dark"] {
  --color-surface: #1f2937;
  --color-text-primary: #f9fafb;
}

/* Component never changes */
.card {
  background: var(--color-surface);
  color: var(--color-text-primary);
}
```

Flash DSM generates both light and dark color scales for every design system. The exported `tokens.css` includes both the default dark-mode `:root` block and a `[data-theme="light"]` override.

## Tokens in Tailwind CSS

Tailwind's `tailwind.config.js` lets you extend the theme with your tokens. Flash DSM exports a config that maps your semantic tokens to Tailwind utility classes:

```js
// tailwind.config.js (generated by Flash DSM)
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: "var(--color-primary)",
        surface: "var(--color-surface)",
        "text-primary": "var(--color-text-primary)",
        // ...
      },
      borderRadius: {
        button: "var(--radius-button)",
        card: "var(--radius-card)",
      },
      // ...
    },
  },
};
```

Now `bg-primary`, `text-text-primary`, and `rounded-card` all reference your design tokens. Tailwind's JIT compiler generates only the classes you use, so there's no performance cost.

## Tokens in Figma

Figma Variables (released in 2023) are Figma's native implementation of design tokens. Flash DSM can:

1. **Import** from a Figma file - read existing variables and turn them into Flash DSM tokens
2. **Export** to Figma - generate a `figma-tokens.json` file in Tokens Studio format that maps back to Figma variables

This closes the design-code loop: changes made in Figma can be imported into Flash DSM, and changes made in Flash DSM can be pushed back to Figma.

## Why this matters for your team

The promise of design tokens is **one change, everywhere**. When you update your brand's primary color:

1. You change one token value in Flash DSM (or in `design-tokens.json` in your repo)
2. Flash regenerates `tokens.css` and `tailwind.config.js`
3. Every component that uses `--color-primary` or `bg-primary` reflects the change
4. Your Figma file stays in sync via the Tokens Studio plugin
5. AI tools like Cursor see the updated token via the MCP server

No global find-and-replace. No drift between design and code. No more "the Figma file has the new blue but the website still has the old one."

That's the whole point of Flash DSM.