Building Scalable Design Systems with Tokens

Design tokens are the atoms of your design system—the smallest, most fundamental decisions that cascade through your entire product.

What Are Design Tokens?

Design tokens are named entities that store visual design attributes. Instead of hardcoding #ff6b35 everywhere, you reference --color-accent-primary.

:root {
  /* Color tokens */
  --color-background: #000000;
  --color-foreground: #ffffff;
  --color-accent-primary: #ff6b35;
  --color-accent-secondary: #f7931e;

  /* Spacing tokens */
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 2rem;
  --space-xl: 4rem;

  /* Typography tokens */
  --font-main: "Manrope", sans-serif;
  --font-accent: "Inter", sans-serif;
  --font-size-base: 1rem;
  --font-size-lg: 1.25rem;
  --font-size-xl: 1.5rem;
}

The Token Hierarchy

I structure tokens in three tiers:

1. Primitive Tokens (Raw Values)

--gray-900: #111111;
--gray-800: #1a1a1a;
--orange-500: #ff6b35;

2. Semantic Tokens (Purpose)

--color-background: var(--gray-900);
--color-text-primary: var(--gray-100);
--color-interactive: var(--orange-500);

3. Component Tokens (Specific Use)

--button-bg: var(--color-interactive);
--button-text: var(--color-background);
--card-border: var(--color-border);

Integrating with Tailwind CSS

Tailwind makes token integration seamless:

// tailwind.config.ts
import type { Config } from "tailwindcss";

const config: Config = {
  theme: {
    extend: {
      colors: {
        background: "var(--color-background)",
        foreground: "var(--color-foreground)",
        accent: {
          DEFAULT: "var(--color-accent-primary)",
          secondary: "var(--color-accent-secondary)",
        },
      },
      fontFamily: {
        main: ["var(--font-main)"],
        accent: ["var(--font-accent)"],
      },
    },
  },
};

export default config;

Dark Mode with Tokens

Tokens make theming trivial:

:root {
  --color-background: #ffffff;
  --color-foreground: #000000;
}

[data-theme="dark"] {
  --color-background: #000000;
  --color-foreground: #ffffff;
}

Syncing with Figma

Use tools like Tokens Studio to sync Figma variables with your codebase:

1. Define tokens in Figma using Variables
2. Export as JSON
3. Transform to CSS/Tailwind with Style Dictionary
4. Commit to your repo

// tokens.json (exported from Figma)
{
  "color": {
    "background": {
      "value": "#000000",
      "type": "color"
    },
    "accent": {
      "primary": {
        "value": "#ff6b35",
        "type": "color"
      }
    }
  }
}

The Payoff

A well-structured token system means:

• Consistency: One source of truth
• Scalability: Add themes without refactoring
• Collaboration: Designers and devs speak the same language
• Maintenance: Change once, update everywhere

Start small—colors and spacing—then expand as your system matures.