Design Tokens in Production: From Figma to CSS Custom Properties

Design tokens bridge the gap between design decisions and production code. They transform colour hex values, spacing increments, typography scales, and shadow definitions from static artefacts in a design file into a single source of truth that both designers and developers reference. When implemented correctly, tokens eliminate the "hex value drift" that plagues every growing design system.

Token Taxonomy: Global, Alias, and Component Tokens

A healthy token system uses three layers of abstraction. Global tokens (sometimes called "primitives") are the raw values: color-blue-500: #1a73e8. Alias tokens (or "semantic tokens") map global tokens to purpose: color-primary: color-blue-500. Component tokens reference alias tokens for specific component properties: button-primary-background: color-primary.

This three-layer structure gives you flexibility. When your brand colour shifts from blue to indigo, you update one global token and everything cascades. When a specific button variant needs its own colour, you create a component-level token without disturbing the broader system.

{
  "global": {
    "color-blue-500": { "value": "#1a73e8" },
    "color-indigo-500": { "value": "#6366f1" },
    "spacing-4": { "value": "4px" },
    "spacing-8": { "value": "8px" }
  },
  "alias": {
    "color-primary": { "value": "{color-blue-500}" },
    "spacing-inset-sm": { "value": "{spacing-4}" },
    "font-weight-heading": { "value": "600" }
  },
  "component": {
    "button-primary-bg": { "value": "{color-primary}" },
    "button-primary-padding": { "value": "{spacing-inset-sm}" }
  }
}

The Tooling Pipeline: Figma → JSON → CSS

A manual copy-paste token workflow breaks immediately at scale. The industry-standard pipeline uses Style Dictionary (Amazon's open-source token transformer) or Tokens Studio for Figma with an export plugin.

The pipeline looks like this:

1. Designers define tokens in Figma using Tokens Studio for Figma (formerly Design Tokens). This plugin lives inside the Figma file and keeps token values synchronised across design teams.
2. Export to JSON via the Tokens Studio GitHub sync or CI script. The exported file contains the full token tree in W3C Design Tokens format.
3. Transform with Style Dictionary to generate platform-specific outputs: CSS custom properties for web, Swift constants for iOS, Kotlin variables for Android.

# Example Style Dictionary configuration
{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "src/tokens/",
      "files": [{
        "destination": "variables.css",
        "format": "css/variables"
      }]
    }
  }
}

Run npx style-dictionary build in CI on every merge to your token repository. The generated CSS file becomes the single source of truth consumed by your application.

CSS Custom Properties in Practice

Once your tokens are exported to CSS, consume them in your components:

:root {
  --color-primary: #1a73e8;
  --color-primary-hover: #1557b0;
  --spacing-inset-sm: 4px;
  --font-size-body: 1rem;
  --border-radius-md: 6px;
}

.button--primary {
  background-color: var(--color-primary);
  padding: var(--spacing-inset-sm);
  border-radius: var(--border-radius-md);
  font-size: var(--font-size-body);
}

.button--primary:hover {
  background-color: var(--color-primary-hover);
}

The benefits over static SCSS variables or hard-coded values are immediate:

• Runtime theming: Swap the :root block for a dark-theme block and all components update instantly.
• Browser developer tools inspectability: Custom properties appear in the Computed panel, making debugging straightforward.
• Component isolation: Shadow DOM components inherit custom properties by default, ensuring consistent theming across micro-frontends.

Theming Without Spaghetti

Dark mode, high-contrast mode, and brand-switching are solved elegantly with custom properties. Define your theme tokens as custom properties on a [data-theme] selector:

[data-theme="dark"] {
  --color-background: #121212;
  --color-text: #e0e0e0;
  --color-surface: #1e1e1e;
}

[data-theme="high-contrast"] {
  --color-background: #ffffff;
  --color-text: #000000;
  --color-primary: #0000ff;
  --border-width-default: 2px;
}

Toggle themes by setting document.documentElement.dataset.theme = 'dark'. No JavaScript-driven style manipulation, no class-swapping libraries. The browser's style engine handles the cascade.

Managing Breaking Changes in Token Systems

Token systems evolve. Colours shift, spacing scales expand, naming conventions improve. Breaking changes need to be surfaced to both designers and developers without causing production failures.

Adopt a semantic versioning approach for your token package:

• Patch: Value changes only (e.g., color-blue-500 changes from #1a73e8 to #1565c0). No consumer-side changes needed.
• Minor: New tokens added, no existing tokens removed or renamed.
• Major: Existing token names change, deprecated tokens removed, or values become semantically incompatible.

Ship a deprecation policy alongside every major version. Use CSS @supports and fallback values to ease migration:

.card {
  background: var(--color-surface, #ffffff);
  padding: var(--spacing-md, 16px);
}

Run a linter that warns when deprecated tokens appear in a PR. This catches drift before it reaches production.

Maintaining Alignment Between Design and Code

The pipeline is only half the battle. The harder challenge is keeping designers and developers aligned on token usage. Schedule a weekly "token sync" during active design system work—fifteen minutes to review new tokens, flag naming collisions, and resolve ambiguity.

Document token usage guidelines inside your design system documentation with real code examples and Figma component references. Every token should include its definition, intended use case, accessibility context, and a visual example.

Design tokens turn your design system from a shared vocabulary into an executable contract. When both Figma and your production app reference the same token JSON, the "design-to-dev gap" narrows to zero.

Ready to set up a token pipeline for your team? Contact SoniNow for a design system consultation or implementation workshop.