Design Tokens & Theming

Design Token Fundamentals

Design tokens are named design decisions — colors, spacing, typography, shadows, and radii — stored as data and consumed by code. They bridge design tools (Figma) and development (Tailwind config).

Organize tokens in three tiers: primitive (raw values), semantic (purpose-based), and component (component-specific). Primitive tokens should rarely appear in component code.

• Primitive → Semantic → Component is the standard token hierarchy
• Semantic names describe purpose, not appearance
• Tools like Style Dictionary generate tokens for multiple platforms

/* Primitive tokens */
--color-blue-500: #2563eb;
--space-4: 1rem;

/* Semantic tokens */
--color-interactive: var(--color-blue-500);
--color-surface: var(--color-white);

/* Component tokens */
--button-bg: var(--color-interactive);

Tailwind Theme Architecture

Map design tokens to Tailwind theme in config (v3) or @theme (v4). Define color scales, spacing scales, typography scales, and shadow scales as the single source of truth.

Extend, do not replace, the default theme unless you have a complete custom system. Defaults provide sensible fallbacks and documentation alignment.

// v3 tailwind.config.js
theme: {
  extend: {
    colors: {
      surface: {
        DEFAULT: 'var(--color-surface)',
        elevated: 'var(--color-surface-elevated)',
      },
      interactive: 'var(--color-interactive)',
    },
  },
}

Multi-Theme Implementation

Define theme variables on :root for the default theme and override them on [data-theme="dark"] or .dark. Tailwind dark: variant maps to these overrides.

For more than two themes (light, dark, high-contrast, brand), use data-theme attribute selectors and define complete token sets per theme.

:root {
  --color-surface: #ffffff;
  --color-text: #1e293b;
  --color-interactive: #2563eb;
}

[data-theme="dark"] {
  --color-surface: #0f172a;
  --color-text: #f1f5f9;
  --color-interactive: #60a5fa;
}

CSS Variable Integration

Define all theme values as CSS custom properties. Tailwind utilities reference these variables. JavaScript can read and write them for dynamic theming — user preferences, brand customization, or accessibility modes.

This architecture separates token definition (CSS) from token consumption (Tailwind utilities). Changing a variable updates every utility that references it.

@theme {
  --color-surface: var(--theme-surface);
  --color-text: var(--theme-text);
}

/* Utilities generated automatically:
   bg-surface, text-text, etc. */

Design Tool Sync

Export tokens from Figma using plugins like Tokens Studio or Figma Variables. Transform exported JSON into Tailwind config with Style Dictionary or token-transformer.

Establish a token update workflow: designers modify Figma tokens, export JSON, CI regenerates Tailwind config, developers get updated utilities. This keeps design and code synchronized.

• Figma Variables map naturally to CSS custom properties
• Automate token sync in CI to prevent drift
• Version token changes alongside code releases

// style-dictionary.config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'src/styles/',
      files: [{ destination: 'tokens.css', format: 'css/variables' }],
    },
    tailwind: {
      transformGroup: 'js',
      buildPath: 'src/',
      files: [{ destination: 'tailwind-tokens.js', format: 'javascript/module' }],
    },
  },
};