Design System Handoff: Tokens to Components

TLDR

Design system handoff is not just passing mockups to developers—it's implementing a structured system of tokens, components, and patterns that maintains consistency across platforms. A complete design system handoff includes primitive design tokens (colors, spacing, typography), component libraries (buttons, inputs, cards), and composed patterns (forms, navigation, layouts) with comprehensive documentation.

Key takeaways:

• Design systems have three layers: tokens (primitive values), components (UI elements), patterns (composed interfaces)
• Token-based systems enable cross-platform consistency and single-source-of-truth maintenance
• Component libraries should maintain 1:1 mapping between design components and code implementations
• Documentation with tools like Storybook ensures design and development teams stay aligned
• Automated sync tools and version control strategies prevent design-code drift over time

What is Design System Handoff?

Traditional design handoff involves passing static mockups from designers to developers with the expectation that developers will extract colors, measure spacing, and implement components from scratch. Design system handoff is fundamentally different—it's about implementing a living system that scales across products, platforms, and teams. For a complete overview of the design handoff process, see our comprehensive guide on design handoff.

A proper design system handoff delivers three distinct layers:

1. Token layer – Primitive design decisions (colors, spacing, typography, shadows, radii) stored as platform-agnostic data
2. Component layer – Reusable UI elements (buttons, inputs, cards, badges) built using tokens
3. Pattern layer – Composed interfaces (login forms, dashboards, navigation) assembled from components

Each layer builds on the previous one, creating a hierarchy that flows from raw values to complete interfaces. This structure enables teams to make global changes (like rebranding) by updating tokens once rather than hunting through hundreds of components.

The Three Layers

Understanding the hierarchy between tokens, components, and patterns is critical for successful design system implementation. Here's how they relate:

┌─────────────────────────────────────┐
│  PATTERNS (Composed Interfaces)    │
│  └─ LoginForm, Dashboard, Nav      │
│                                     │
│  ┌───────────────────────────────┐ │
│  │ COMPONENTS (UI Elements)      │ │
│  │ └─ Button, Input, Card        │ │
│  │                               │ │
│  │  ┌─────────────────────────┐ │ │
│  │  │ TOKENS (Primitive Values)│ │ │
│  │  │ └─ Colors, Spacing, Type │ │ │
│  │  └─────────────────────────┘ │ │
│  └───────────────────────────────┘ │
└─────────────────────────────────────┘

Token layer provides the raw materials: --color-blue-500: #3B82F6, --spacing-4: 16px, --font-size-lg: 18px. These are platform-agnostic values that can be transformed into CSS variables, iOS Swift constants, or Android XML resources.

Component layer consumes tokens to build reusable UI elements. A Button component might use --color-primary, --spacing-3, and --font-size-base rather than hard-coded values. This creates consistency and enables global theming.

Pattern layer composes components into complete interfaces. A LoginForm pattern combines Input components, a Button component, and a Card component following established spacing and layout conventions.

Token Layer Implementation

The foundation of any design system is its token layer. Tokens represent design decisions as data, enabling cross-platform consistency and maintainable code. For a complete deep dive into design tokens, see our guide on design tokens.

Here's a minimal token structure organized by category:

{
  "color": {
    "brand": {
      "primary": "#3B82F6",
      "secondary": "#8B5CF6"
    },
    "neutral": {
      "50": "#F8FAFC",
      "900": "#0F172A"
    },
    "semantic": {
      "success": "#10B981",
      "error": "#EF4444",
      "warning": "#F59E0B"
    }
  },
  "spacing": {
    "1": "4px",
    "2": "8px",
    "3": "12px",
    "4": "16px",
    "6": "24px",
    "8": "32px"
  },
  "typography": {
    "fontFamily": {
      "sans": "Inter, system-ui, sans-serif",
      "mono": "JetBrains Mono, monospace"
    },
    "fontSize": {
      "sm": "14px",
      "base": "16px",
      "lg": "18px",
      "xl": "20px"
    },
    "lineHeight": {
      "tight": "1.25",
      "normal": "1.5",
      "relaxed": "1.75"
    }
  }
}

This JSON structure can be transformed into CSS variables, JavaScript constants, or native platform values using tools like Style Dictionary. The key is maintaining a single source of truth that drives all platform implementations.

Component Layer Implementation

Once tokens are established, the next layer is building components that consume those tokens. The goal is 1:1 mapping between design components and code components—if Figma has a "Primary Button" component, the code should have an identical PrimaryButton or <Button variant="primary"> component.

Here's a Card component built with token-based styling in React and TypeScript:

// Card.tsx
import React from 'react';
 
interface CardProps {
  title: string;
  description: string;
  children?: React.ReactNode;
}
 
export function Card({ title, description, children }: CardProps) {
  return (
    <div className="card">
      <h3 className="card-title">{title}</h3>
      <p className="card-description">{description}</p>
      {children && <div className="card-content">{children}</div>}
    </div>
  );
}

/* Card.css - Token-based styling */
.card {
  background: var(--color-neutral-50);
  border: 1px solid var(--color-neutral-200);
  border-radius: var(--radius-lg);
  padding: var(--spacing-6);
  box-shadow: var(--shadow-md);
}
 
.card-title {
  font-family: var(--font-family-sans);
  font-size: var(--font-size-xl);
  font-weight: var(--font-weight-semibold);
  color: var(--color-neutral-900);
  margin-bottom: var(--spacing-2);
}
 
.card-description {
  font-size: var(--font-size-base);
  color: var(--color-neutral-600);
  line-height: var(--line-height-relaxed);
  margin-bottom: var(--spacing-4);
}
 
.card-content {
  margin-top: var(--spacing-4);
}

Notice that every visual property references a token. This means changing brand colors or spacing scale requires updating tokens only—no component code changes needed. This is the power of the token-component relationship.

For more advanced component patterns including variants, sizes, and state management, see our guide on component library handoff.

Pattern Layer: Composing Components

The final layer is patterns—composed interfaces built from multiple components. Patterns establish conventions for how components work together, creating consistency across different screens and workflows.

Here's a LoginForm pattern that composes Input, Button, and Card components:

// LoginForm.tsx
import React, { useState } from 'react';
import { Card } from './Card';
import { Input } from './Input';
import { Button } from './Button';
 
export function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
 
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // Handle authentication
  };
 
  return (
    <Card
      title="Welcome back"
      description="Sign in to your account"
    >
      <form onSubmit={handleSubmit} className="login-form">
        <Input
          type="email"
          label="Email address"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="you@example.com"
          required
        />
 
        <Input
          type="password"
          label="Password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          placeholder="••••••••"
          required
        />
 
        <Button type="submit" variant="primary" fullWidth>
          Sign in
        </Button>
      </form>
    </Card>
  );
}

/* LoginForm.css */
.login-form {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-4);
}

This pattern establishes several conventions:

• Forms use consistent vertical spacing (--spacing-4)
• Input fields appear in a logical order (email before password)
• Submit buttons are full-width in card-based forms
• Card components provide visual structure for authentication flows

These patterns get documented alongside components so developers know which compositions are approved and which break design system conventions.

Documentation with Storybook

Documentation is the bridge between design and development teams. Without it, even the best-architected design system falls apart because no one knows what components exist or how to use them.

Storybook is the industry standard for documenting React component libraries. It provides an interactive playground where developers can view components in isolation, toggle props, and see all possible states.

Here's a basic Storybook story for the Card component:

// Card.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Card } from './Card';
 
const meta: Meta<typeof Card> = {
  title: 'Components/Card',
  component: Card,
  tags: ['autodocs'],
  argTypes: {
    title: { control: 'text' },
    description: { control: 'text' },
  },
};
 
export default meta;
type Story = StoryObj<typeof Card>;
 
export const Default: Story = {
  args: {
    title: 'Card Title',
    description: 'This is a description of the card content.',
  },
};
 
export const WithChildren: Story = {
  args: {
    title: 'Card with Content',
    description: 'This card contains additional content.',
    children: (
      <div>
        <p>Additional card content goes here.</p>
        <button>Action Button</button>
      </div>
    ),
  },
};
 
export const LongDescription: Story = {
  args: {
    title: 'Long Description Example',
    description: 'This is a much longer description that demonstrates how the card handles multi-line text content and maintains proper spacing and readability.',
  },
};

This creates three interactive examples that designers and developers can reference. Storybook also auto-generates prop documentation from TypeScript types, reducing manual documentation work.

Keeping Design and Code in Sync

The biggest challenge with design systems is drift—when design files and code implementations slowly diverge over time. Here are three strategies to prevent drift:

1. Version Control for Design Files

Store Figma files in version control using Figma's branching feature or export design tokens to JSON and commit them to Git. This creates a historical record of design changes and enables code review workflows for design updates.

2. Automated Token Sync

Use tools like Style Dictionary or Theo to automatically convert design tokens from JSON to platform-specific formats (CSS, Swift, Kotlin). When designers update the source JSON, running the build process regenerates all platform implementations automatically.

3. Breaking Change Detection

Implement semantic versioning for your design system. Major version bumps indicate breaking changes (removing a component, changing token names), minor versions add new features, and patches fix bugs. This helps consuming applications understand the impact of updates.

Additionally, automated visual regression testing with tools like Chromatic or Percy can catch unintended visual changes before they reach production.

FAQ

Q: What are the three layers of a design system?

A: Design systems consist of three layers: tokens (primitive values like colors and spacing), components (reusable UI elements like buttons and cards), and patterns (composed interfaces like forms and navigation). Each layer builds on the previous one to create a complete system.

Q: How do you keep design and code in sync?

A: Keep design and code in sync using version control for both design files and code repositories, automated token sync tools like Style Dictionary, and breaking change detection through semantic versioning. Regular audits and automated tests help catch drift between design and implementation.

Q: What tools help with design system documentation?

A: Storybook is the most popular tool for documenting React component libraries, providing interactive component playground and automated documentation. Alternatives include Docusaurus for documentation sites, Zeroheight for design-focused docs, and Supernova for end-to-end design system management.