Design Systems in Code: Harmonizing Token Architectures Between Figma & CSS

1. The Three-Tier Design Token Architecture

A fatal mistake made by early design systems was creating a flat, one-dimensional token list (e.g., exposing --color-blue-500: #2563eb directly to UI components). If the brand re-brands from blue to terracotta, engineers must search and replace hundreds of references across the codebase. Modern enterprise design systems enforce a Three-Tier Token Hierarchy:

• Tier 1: Global Tokens (Primitives): Raw, immutable values describing physical design choices without semantic context (e.g., color.palette.terracotta.500: #c2410c, space.16: 16px, font.family.display: 'Fraunces'). UI components are strictly forbidden from referencing Global Tokens directly.
• Tier 2: Semantic Tokens (Aliases): Context-aware tokens that map primitives to functional meaning (e.g., color.background.primary: {color.palette.terracotta.500}, color.text.body: {color.palette.stone.800}). Semantic tokens enable effortless theming: switching to Dark Mode or High Contrast Mode requires altering only the semantic aliases while leaving primitive palettes untouched.
• Tier 3: Component-Specific Tokens: Granular scoped tokens bound to individual component primitives (e.g., button.primary.bg.default: {color.background.primary}, modal.header.padding.bottom: {space.16}). Component tokens allow engineering squads to tweak a button's border radius without risking accidental regressions across unrelated card components.

2. Automated Synchronization: The Figma-to-Code Pipeline

To eliminate manual transcription errors, enterprise design systems implement automated Git-Driven Token Pipelines:

1. Design Authoring in Figma: Designers define brand tokens using native Figma Variables (Color, Number, String, Boolean) organized into Collections (Primitives, Semantics, Modes).
2. Webhook / GitHub Action Trigger: When the design library is published or updated, a GitHub Action dispatches a scheduled webhook or executes a script leveraging the Figma REST API (GET /v1/files/:file_key/variables/local).
3. AST Normalization: The pipeline extracts raw Figma variable values and normalizes them into standard W3C DTCG JSON format (tokens.json).
4. Transformation via Style Dictionary: Style Dictionary processes the JSON tokens, transforming values into platform-specific targets: CSS Custom Properties (tokens.css), TypeScript declarations (tokens.d.ts), Tailwind theme configurations, and iOS Swift structs.
5. Automated Pull Request: The pipeline creates an automated GitHub PR with visual snapshot diffs, allowing engineering leads to review design token changes alongside automated unit tests.

3. End-to-End TypeScript Type Safety for Design Tokens

By compiling design tokens into strongly typed TypeScript const assertions (as const), front-end teams achieve compile-time verification across React MVC views:

Instead of passing unvalidated raw strings to styling props (e.g., <Box color="terracotta-rust" />), TypeScript infers the exact union of allowed semantic token keys (type ColorToken = keyof typeof designTokens.colors). If a developer mistypes a token name or references an obsolete alias, the TypeScript compiler immediately halts the build with an actionable error.

4. Technical Matrix: Token Representation Across Platforms

5. Production Implementation: Automated Figma Token Fetcher in TypeScript

The following Node.js script demonstrates how enterprise pipelines fetch variables from the Figma REST API and transform them into normalized DTCG tokens:

// scripts/fetchFigmaTokens.ts
import fs from 'fs/promises';
import path from 'path';

const FIGMA_API_TOKEN = process.env.FIGMA_ACCESS_TOKEN || '';
const FIGMA_FILE_KEY = process.env.FIGMA_FILE_KEY || '';

interface FigmaVariable {
  id: string;
  name: string;
  resolvedType: 'COLOR' | 'FLOAT' | 'STRING';
  valuesByMode: Record<string, any>;
}

async function syncFigmaTokens() {
  const url = `https://api.figma.com/v1/files/${FIGMA_FILE_KEY}/variables/local`;
  const response = await fetch(url, {
    headers: { 'X-Figma-Token': FIGMA_API_TOKEN }
  });

  if (!response.ok) {
    throw new Error(`Figma API responded with status: ${response.status}`);
  }

  const data = await response.json();
  const variables: Record<string, FigmaVariable> = data.meta.variables;
  const tokenDictionary: Record<string, any> = {};

  for (const id in variables) {
    const variable = variables[id];
    // Convert Figma variable slash path (e.g. "color/brand/primary") to nested object
    const parts = variable.name.split('/');
    let current = tokenDictionary;

    for (let i = 0; i < parts.length - 1; i++) {
      current[parts[i]] = current[parts[i]] || {};
      current = current[parts[i]];
    }

    const leafKey = parts[parts.length - 1];
    const defaultModeId = Object.keys(variable.valuesByMode)[0];
    const rawVal = variable.valuesByMode[defaultModeId];

    current[leafKey] = {
      $value: rawVal,
      $type: variable.resolvedType.toLowerCase(),
      $description: `Synced from Figma Variable: ${variable.name}`
    };
  }

  const outputPath = path.resolve(process.cwd(), 'tokens/dtcg-tokens.json');
  await fs.writeFile(outputPath, JSON.stringify(tokenDictionary, null, 2), 'utf8');
  console.log(`Successfully synced ${Object.keys(variables).length} tokens to ${outputPath}`);
}

Frequently Asked Questions: Design Systems in Code