What is Design tokens?

A design token stores one design decision under a name: color.accent, space.4, radius.control, shadow.overlay. The name is what designers and engineers refer to; the value can change without anyone hunting through code. Because tokens are data, one source can generate CSS custom properties, iOS and Android constants, and design tool variables, which keeps every platform in sync.

Token tiers

Most systems layer tokens so that each tier has one job.

• Primitive (or reference) tokens name raw values: violet-600, gray-900, space-16. They say what a value is, not what it is for.
• [Semantic tokens](/glossary/semantic-tokens) name roles and point at primitives: accent, fg-muted, border, danger. Components use these.
• Component tokens (optional) scope a value to one component: button-height-sm, dialog-radius. Useful in large systems, noise in small ones.

Theming happens at the semantic tier. Dark mode, a brand variant or a high-contrast mode remaps semantic tokens to different primitives, and components never notice.

Formats

The W3C Design Tokens Community Group maintains a JSON format that tools such as Style Dictionary and design tool plugins read. Each token has a $value and usually a $type, and tokens can reference other tokens with curly braces. In the current version of the format, colors and dimensions are structured objects:

{
  "color": {
    "violet-600": {
      "$type": "color",
      "$value": { "colorSpace": "oklch", "components": [0.53, 0.215, 283] }
    },
    "accent": { "$type": "color", "$value": "{color.violet-600}" }
  },
  "radius": {
    "control": { "$type": "dimension", "$value": { "value": 8, "unit": "px" } }
  }
}

On the web, tokens end up as CSS variables. In Tailwind CSS v4 you expose them as utilities with @theme, so --color-accent becomes bg-accent, text-accent and border-accent.

Common pitfalls

• Naming semantic tokens after their value (--blue) instead of their role. The name breaks the first time the brand changes.
• Letting components reach past semantic tokens to primitives. Theming then requires editing components.
• Creating a token for every one-off value. A token earns its place when it is reused or themed.
• Keeping design files and code in separate token sets. Generate both from one source, or they drift within weeks.

How MiniDev UI uses them

MiniDev UI ships semantic tokens only, written in OKLCH and mapped to Tailwind utilities: surfaces (bg, surface, raised, sunken), text (fg, fg-muted, fg-subtle), brand (accent, accent-soft, on-accent), four status colors and a shadow scale. It also maps them onto the shadcn variable names (--primary, --muted, --ring), so existing shadcn components pick them up. Generate a scale of your own with the OKLCH palette generator.