Developer Handoff Guide

Developer Handoff Guide

Reference for integrating design tokens into development workflows and design tool collaboration.

Table of Contents

• Export Formats
• Integration Patterns
• Framework Setup
• Design Tool Integration
• Handoff Checklist

Export Formats

JSON (Recommended for Most Projects)

File: design-tokens.json

{
  "meta": {
    "version": "1.0.0",
    "style": "modern",
    "generated": "2024-01-15"
  },
  "colors": {
    "primary": {
      "50": "#E6F2FF",
      "100": "#CCE5FF",
      "500": "#0066CC",
      "900": "#002855"
    }
  },
  "typography": {
    "fontFamily": {
      "sans": "Inter, system-ui, sans-serif",
      "mono": "Fira Code, monospace"
    },
    "fontSize": {
      "xs": "10px",
      "sm": "13px",
      "base": "16px",
      "lg": "20px"
    }
  },
  "spacing": {
    "0": "0px",
    "1": "4px",
    "2": "8px",
    "4": "16px"
  }
}

Use Case: JavaScript/TypeScript projects, build tools, Figma plugins

CSS Custom Properties

File: design-tokens.css

:root {
  /* Colors */
  --color-primary-50: #E6F2FF;
  --color-primary-100: #CCE5FF;
  --color-primary-500: #0066CC;
  --color-primary-900: #002855;

  /* Typography */
  --font-family-sans: Inter, system-ui, sans-serif;
  --font-family-mono: Fira Code, monospace;
  --font-size-xs: 10px;
  --font-size-sm: 13px;
  --font-size-base: 16px;
  --font-size-lg: 20px;

  /* Spacing */
  --spacing-0: 0px;
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-4: 16px;
}

Use Case: Plain CSS, CSS-in-JS, any web project

SCSS Variables

File: _design-tokens.scss

// Colors
$color-primary-50: #E6F2FF;
$color-primary-100: #CCE5FF;
$color-primary-500: #0066CC;
$color-primary-900: #002855;

// Typography
$font-family-sans: Inter, system-ui, sans-serif;
$font-family-mono: Fira Code, monospace;
$font-size-xs: 10px;
$font-size-sm: 13px;
$font-size-base: 16px;
$font-size-lg: 20px;

// Spacing
$spacing-0: 0px;
$spacing-1: 4px;
$spacing-2: 8px;
$spacing-4: 16px;

// Maps for programmatic access
$colors-primary: (
  '50': $color-primary-50,
  '100': $color-primary-100,
  '500': $color-primary-500,
  '900': $color-primary-900
);

Use Case: SASS/SCSS pipelines, component libraries

Integration Patterns

Pattern 1: CSS Variables (Universal)

Works with any framework or vanilla CSS.

/* Import tokens */
@import 'design-tokens.css';

/* Use in styles */
.button {
  background-color: var(--color-primary-500);
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  border-radius: var(--radius-md);
}

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

Pattern 2: JavaScript Theme Object

For CSS-in-JS libraries (styled-components, Emotion, etc.)

// theme.ts
import tokens from './design-tokens.json';

export const theme = {
  colors: {
    primary: tokens.colors.primary,
    secondary: tokens.colors.secondary,
    neutral: tokens.colors.neutral,
    semantic: tokens.colors.semantic
  },
  typography: {
    fontFamily: tokens.typography.fontFamily,
    fontSize: tokens.typography.fontSize,
    fontWeight: tokens.typography.fontWeight
  },
  spacing: tokens.spacing,
  shadows: tokens.shadows,
  radii: tokens.borders.radius
};

export type Theme = typeof theme;

// styled-components usage
import styled from 'styled-components';

const Button = styled.button`
  background: ${({ theme }) => theme.colors.primary['500']};
  padding: ${({ theme }) => theme.spacing['2']} ${({ theme }) => theme.spacing['4']};
  font-size: ${({ theme }) => theme.typography.fontSize.base};
`;

Pattern 3: Tailwind Config

// tailwind.config.js
const tokens = require('./design-tokens.json');

module.exports = {
  theme: {
    colors: {
      primary: tokens.colors.primary,
      secondary: tokens.colors.secondary,
      neutral: tokens.colors.neutral,
      success: tokens.colors.semantic.success,
      warning: tokens.colors.semantic.warning,
      error: tokens.colors.semantic.error
    },
    fontFamily: {
      sans: [tokens.typography.fontFamily.sans],
      serif: [tokens.typography.fontFamily.serif],
      mono: [tokens.typography.fontFamily.mono]
    },
    spacing: {
      0: tokens.spacing['0'],
      1: tokens.spacing['1'],
      2: tokens.spacing['2'],
      // ... etc
    },
    borderRadius: tokens.borders.radius,
    boxShadow: tokens.shadows
  }
};

Framework Setup

React + CSS Variables

// App.tsx
import './design-tokens.css';
import './styles.css';

function App() {
  return (
    <button className="btn btn-primary">
      Click me
    </button>
  );
}

/* styles.css */
.btn {
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  font-weight: var(--font-weight-medium);
  border-radius: var(--radius-md);
  transition: background-color var(--animation-duration-fast);
}

.btn-primary {
  background: var(--color-primary-500);
  color: var(--color-surface-background);
}

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

React + styled-components

// ThemeProvider.tsx
import { ThemeProvider } from 'styled-components';
import { theme } from './theme';

export function AppThemeProvider({ children }) {
  return (
    <ThemeProvider theme={theme}>
      {children}
    </ThemeProvider>
  );
}

// Button.tsx
import styled from 'styled-components';

export const Button = styled.button<{ variant?: 'primary' | 'secondary' }>`
  padding: ${({ theme }) => `${theme.spacing['2']} ${theme.spacing['4']}`};
  font-size: ${({ theme }) => theme.typography.fontSize.base};
  border-radius: ${({ theme }) => theme.radii.md};

  ${({ variant = 'primary', theme }) => variant === 'primary' && `
    background: ${theme.colors.primary['500']};
    color: ${theme.colors.surface.background};

    &:hover {
      background: ${theme.colors.primary['600']};
    }
  `}
`;

Vue + CSS Variables

<!-- App.vue -->
<template>
  <button class="btn btn-primary">Click me</button>
</template>

<style>
@import './design-tokens.css';

.btn {
  padding: var(--spacing-2) var(--spacing-4);
  font-size: var(--font-size-base);
  border-radius: var(--radius-md);
}

.btn-primary {
  background: var(--color-primary-500);
  color: var(--color-surface-background);
}
</style>

Next.js + Tailwind

// tailwind.config.js
const tokens = require('./design-tokens.json');

module.exports = {
  content: ['./app/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: tokens.colors,
      fontFamily: {
        sans: tokens.typography.fontFamily.sans.split(', ')
      }
    }
  }
};

// page.tsx
export default function Page() {
  return (
    <button className="bg-primary-500 hover:bg-primary-600 px-4 py-2 rounded-md text-white">
      Click me
    </button>
  );
}

Design Tool Integration

Figma

Option 1: Tokens Studio Plugin

1. Install "Tokens Studio for Figma" plugin
2. Import design-tokens.json
3. Tokens sync automatically with Figma styles

Option 2: Figma Variables (Native)

1. Open Variables panel
2. Create collections matching token structure
3. Import JSON via plugin or API

Sync Workflow:

design_token_generator.py
        ↓
design-tokens.json
        ↓
Tokens Studio Plugin
        ↓
Figma Styles & Variables

Storybook

// .storybook/preview.js
import '../design-tokens.css';

export const parameters = {
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '#FFFFFF' },
      { name: 'dark', value: '#111827' }
    ]
  }
};

// Button.stories.tsx
import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost']
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg']
    }
  }
};

export const Primary = {
  args: {
    variant: 'primary',
    children: 'Button'
  }
};

Design Tool Comparison

Handoff Checklist

Token Generation

• Brand color defined
• Style selected (modern/classic/playful)
• Tokens generated: python scripts/design_token_generator.py "#0066CC" modern
• All formats exported (JSON, CSS, SCSS)

Developer Setup

• Token files added to project
• Build pipeline configured
• Theme/CSS variables imported
• Hot reload working for token changes

Design Sync

• Figma/design tool updated with tokens
• Component library aligned
• Documentation generated
• Storybook stories created

Validation

• Colors render correctly
• Typography scales properly
• Spacing matches design
• Responsive breakpoints work
• Dark mode tokens (if applicable)

Documentation Deliverables

Version Control

Token Versioning

{
  "meta": {
    "version": "1.2.0",
    "style": "modern",
    "generated": "2024-01-15",
    "changelog": [
      "1.2.0 - Added animation tokens",
      "1.1.0 - Updated primary color",
      "1.0.0 - Initial release"
    ]
  }
}

Breaking Change Policy

See also: token-generation.md for generation options