Design Tokens: How to Build a Design System That Scales Across Products, Platforms, and AI Tools

Design tokens are the single source of truth that keeps a design system consistent as it grows from one product to many. Without tokens, a simple brand color change can mean hunting down hundreds of hardcoded hex values across Figma files and codebases. With tokens, it means editing one value.

At Inity Agency, we build every design system token-first, because tokens connect design and code and, increasingly, the AI coding tools that generate UI. Here is how design tokens work and how to set up a pipeline that scales.

What Are Design Tokens?

Design tokens are named, platform-agnostic variables that store design decisions such as colors, typography, spacing, radii, shadows, and motion. Instead of hardcoding a value like

The term comes from the Salesforce Lightning Design System team, which introduced design tokens around 2014 to keep multiple platforms visually aligned. Today, tokens live as data, usually JSON, so any tool can read them.

The W3C Design Tokens Community Group (DTCG) maintains a vendor-neutral format for that data. A shared format lets tokens move between Figma plugins, build tools, and code without custom converters. A minimal DTCG-style token file looks like this:

{
  "color": {
    "blue": {
      "600": { "$type": "color", "$value": "#4F46E5" }
    },
    "action": {
      "primary": { "$type": "color", "$value": "{color.blue.600}" }
    }
  }
}

Why Do Design Systems Need Design Tokens?

Design systems need design tokens because tokens turn visual decisions into shared data that every team and platform can consume. Tokens eliminate hardcoded values, keep Figma and code in sync, enable theming and dark mode without duplicate components, and make large changes, such as a rebrand, possible by editing a small set of values.

Without tokens, design drift is inevitable. Every product team makes small local decisions, and after two years a product can easily carry a dozen near-identical grays. Tokens make the approved options explicit and make unapproved values visible in code review.

Tokens also matter for AI. AI coding assistants and design-to-code tools generate far more consistent UI when they can read explicit tokens. A prompt like “build a settings card” produces on-brand output when the model sees –color-surface-raised and –space-4 instead of guessing hex values. Tokens are becoming the interface between design systems and AI.

What Are the Three Tiers of Design Tokens?

The three tiers of design tokens are primitive, semantic, and component tokens. Primitive tokens store raw values like blue-600. Semantic tokens assign meaning, such as color.action.primary. Component tokens bind semantic values to specific components, such as button.primary.background. Each tier references the tier below it, which keeps changes predictable.

Not every system needs all three tiers. Small products often work well with primitives and semantics only. Add component tokens when multiple brands or themes need to customize specific components independently.

One rule matters more than any other: components should never reference primitives directly. That single rule is what makes theming, dark mode, and rebrands possible without touching component code.

Design Tokens in Practice: How to Set Up a Token Pipeline

Design tokens in practice require a pipeline with three parts: a source of truth, a transformation step, and distribution. Teams define tokens in Figma Variables or JSON, store them in version control, transform them with a tool like Style Dictionary, and publish platform-specific outputs, such as CSS custom properties, as a versioned package.

1. Audit existing values. Extract every color, font size, spacing value, and shadow from your codebase and Figma files. Expect duplicates: near-identical grays and off-scale spacing values are normal.
2. Define primitives on a scale. Consolidate values into consistent scales, for example a 4px spacing scale (4, 8, 12, 16, 24, 32, 48, 64) and a 50–950 color ramp.
3. Create the semantic layer. Name tokens by purpose, not appearance: color.text.muted, not color.gray-light. Purpose-based names survive rebrands and dark mode.
4. Agree on naming conventions. Use a predictable structure such as category.property.variant.state, and document it before the token count grows.
5. Choose one source of truth. Pick Figma Variables (with a sync plugin such as Tokens Studio) or JSON files in Git. Sync in one direction only to avoid conflicts.
6. Transform with Style Dictionary. Generate CSS custom properties, a Tailwind theme, Swift, and Kotlin outputs from the same JSON.
7. Automate and version. Run the build in CI, publish tokens as an npm package with semantic versioning, and add visual regression tests to catch unexpected changes.

A typical CSS output from the pipeline looks like this:

:root {
  --color-action-primary: #4f46e5;
  --color-surface-default: #ffffff;
  --space-4: 16px;
}

[data-theme="dark"] {
  --color-action-primary: #818cf8;
  --color-surface-default: #0f172a;
}

How Do Design Tokens Support Theming and Dark Mode?

Design tokens support theming and dark mode by swapping values at the semantic tier while component code stays unchanged. A component references color.surface.default, and each theme maps that semantic token to a different primitive. Switching from light to dark mode, or from one brand to another, changes the mapping, not the components.

Figma Variables mirror this model through modes. A single variable collection can hold Light and Dark modes, and designers preview both without duplicating frames.

Dark mode is not simple inversion. Elevated surfaces often get lighter instead of relying on shadows, and saturated brand colors usually need lighter variants to meet the WCAG contrast ratio of 4.5:1 for body text. Semantic tokens let you tune each of these values per theme.

Multi-brand and white-label SaaS products use the same approach at a larger scale: one component library, plus one semantic token set per brand.

What Does a Design Token Migration Look Like in a Real Product?

A design token migration replaces hardcoded values with token references in phases, starting with color and spacing because they cause the most inconsistency. For example, a B2B SaaS product preparing for a rebrand can tokenize its color system first, then switch the entire interface to the new palette by updating primitive values.

Picture a SaaS dashboard with four years of history. The audit uncovers dozens of hardcoded grays and several one-off blues. The migration then runs in three phases:

• Phase 1: color. The team maps every color to a semantic token and adds a Stylelint rule such as color-no-hex, so no new hardcoded values enter the codebase.
• Phase 2: spacing and typography. Off-scale values snap to the nearest step on the new scales, with visual regression tests flagging any layout shifts.
• Phase 3: component tokens. Only the few components that need brand-specific overrides get their own tokens.

After the migration, the rebrand becomes a single pull request: update the primitives, review contrast, and ship. This is how the Inity Agency team approaches design system engagements: tokens first, components second.

What Mistakes Should Teams Avoid with Design Tokens?

Teams should avoid naming tokens after appearance, letting components reference primitives directly, creating tokens for every one-off value, syncing in both directions between Figma and code, and skipping documentation. Each mistake erodes the main benefit of design tokens: a predictable, single source of truth that changes safely at scale.

Appearance-based names break first. A token called color.blue-button stops making sense the day the button turns green.

Too many tokens is its own problem. If every margin gets a token, nobody can find the right one. Tokens should represent decisions, not every value that exists.

Two-way sync creates conflicts. Decide whether design or code owns the tokens, then automate one direction. For component-level guidance, see our post on AI UX design principles, which relies on the same token foundations.

What Are the Most Frequently Asked Questions About Design Tokens?

The most frequent questions about design tokens cover the difference between tokens and CSS variables, the best tools for managing them, how many tokens a system needs, whether small teams benefit, and how tokens relate to Figma Variables. The five answers below address each question directly and can be read independently.

What is the difference between design tokens and CSS variables?

Design tokens are platform-agnostic design decisions stored as data, usually JSON. CSS variables are one possible output of those tokens for the web. A single token set can generate CSS custom properties, Swift constants, Android resources, and Tailwind configuration, so tokens act as the source and CSS variables act as one destination.

Which tools are best for managing design tokens?

The most widely used design token tools are Figma Variables for defining tokens in design, Tokens Studio for syncing Figma with Git, and Style Dictionary for transforming JSON tokens into platform outputs. Teams with advanced needs add Supernova or Specify for documentation and distribution. The right stack depends on team size and platforms.

How many design tokens does a design system need?

A design system needs as few design tokens as possible to express its real decisions. Many product teams work comfortably with a few hundred primitive and semantic tokens. Rapid growth beyond that usually signals one-off values disguised as tokens. Measure success by consistency and adoption across products, not by token count.

Are design tokens worth it for small teams?

Design tokens are worth it for small teams because the setup cost is lowest at the start. A startup can define a primitive and semantic token set in a few days and avoid years of hardcoded values. Tokens also make dark mode, white-labeling, and future rebrands far cheaper when the product grows.

Are Figma Variables the same as design tokens?

Figma Variables are Figma’s native way to store and apply design tokens inside design files. Variables support collections and modes, which map well to token tiers and themes. However, Figma Variables alone do not reach code, so teams still need an export or sync step to deliver tokens to developers.

What Is the Bottom Line on Design Tokens?

Design tokens turn design decisions into shared data that design, code, and AI tools can all read. A three-tier structure of primitive, semantic, and component tokens keeps changes predictable. A pipeline built on Figma Variables, Git, and Style Dictionary keeps every platform in sync. Teams that start token-first ship theming, dark mode, and rebrands faster.

Planning a new design system or untangling an old one? Talk to Inity Agency about a token-first design system built to scale across your products, platforms, and AI tools.