Design Tokens: Systematic Design Values

Design Tokens are atomic design decisions - visual atoms that represent the foundational values of a design system. This comprehensive guide covers everything you need to know about implementing design tokens.

What are Design Tokens?

Design Tokens are named entities that store visual design attributes.

{
  "color": {
    "primary": {
      "value": "#007bff",
      "type": "color"
    },
    "text": {
      "value": "#212529",
      "type": "color"
    }
  },
  "spacing": {
    "small": {
      "value": "8px",
      "type": "spacing"
    },
    "medium": {
      "value": "16px",
      "type": "spacing"
    }
  }
}

Why Design Tokens?

Consistency - Single source of truth
- Reusability - Use across platforms
- Maintainability - Change once, update everywhere
- Platform-independent - Export to any format
- Theming - Easy theme switching

Token Categories

Colors

{
  "color": {
    "primary": {
      "50": { "value": "#e3f2fd", "type": "color" },
      "100": { "value": "#bbdefb", "type": "color" },
      "500": { "value": "#2196f3", "type": "color" },
      "700": { "value": "#1976d2", "type": "color" },
      "900": { "value": "#0d47a1", "type": "color" }
    },
    "gray": {
      "50": { "value": "#fafafa", "type": "color" },
      "100": { "value": "#f5f5f5", "type": "color" },
      "500": { "value": "#9e9e9e", "type": "color" },
      "900": { "value": "#212121", "type": "color" }
    },
    "semantic": {
      "success": { "value": "#4caf50", "type": "color" },
      "warning": { "value": "#ff9800", "type": "color" },
      "error": { "value": "#f44336", "type": "color" },
      "info": { "value": "#2196f3", "type": "color" }
    }
  }
}

Typography

{
  "font": {
    "family": {
      "sans": { "value": "Inter, system-ui, sans-serif", "type": "fontFamily" },
      "serif": { "value": "Georgia, serif", "type": "fontFamily" },
      "mono": { "value": "JetBrains Mono, monospace", "type": "fontFamily" }
    },
    "weight": {
      "regular": { "value": "400", "type": "fontWeight" },
      "medium": { "value": "500", "type": "fontWeight" },
      "bold": { "value": "700", "type": "fontWeight" }
    },
    "size": {
      "xs": { "value": "12px", "type": "fontSize" },
      "sm": { "value": "14px", "type": "fontSize" },
      "md": { "value": "16px", "type": "fontSize" },
      "lg": { "value": "18px", "type": "fontSize" },
      "xl": { "value": "24px", "type": "fontSize" },
      "2xl": { "value": "32px", "type": "fontSize" },
      "3xl": { "value": "48px", "type": "fontSize" }
    },
    "lineHeight": {
      "tight": { "value": "1.25", "type": "lineHeight" },
      "normal": { "value": "1.5", "type": "lineHeight" },
      "relaxed": { "value": "1.75", "type": "lineHeight" }
    }
  }
}

Spacing

{
  "spacing": {
    "0": { "value": "0", "type": "spacing" },
    "px": { "value": "1px", "type": "spacing" },
    "0.5": { "value": "2px", "type": "spacing" },
    "1": { "value": "4px", "type": "spacing" },
    "2": { "value": "8px", "type": "spacing" },
    "3": { "value": "12px", "type": "spacing" },
    "4": { "value": "16px", "type": "spacing" },
    "6": { "value": "24px", "type": "spacing" },
    "8": { "value": "32px", "type": "spacing" },
    "12": { "value": "48px", "type": "spacing" },
    "16": { "value": "64px", "type": "spacing" }
  }
}

Shadows

{
  "shadow": {
    "sm": { 
      "value": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
      "type": "boxShadow"
    },
    "md": { 
      "value": "0 4px 6px -1px rgba(0, 0, 0, 0.1)",
      "type": "boxShadow"
    },
    "lg": { 
      "value": "0 10px 15px -3px rgba(0, 0, 0, 0.1)",
      "type": "boxShadow"
    },
    "xl": { 
      "value": "0 20px 25px -5px rgba(0, 0, 0, 0.1)",
      "type": "boxShadow"
    }
  }
}

Border Radius

{
  "radius": {
    "none": { "value": "0", "type": "borderRadius" },
    "sm": { "value": "2px", "type": "borderRadius" },
    "default": { "value": "4px", "type": "borderRadius" },
    "md": { "value": "6px", "type": "borderRadius" },
    "lg": { "value": "8px", "type": "borderRadius" },
    "xl": { "value": "12px", "type": "borderRadius" },
    "2xl": { "value": "16px", "type": "borderRadius" },
    "full": { "value": "9999px", "type": "borderRadius" }
  }
}

Token Formats

Design Token Format (DTCG)

{
  "color": {
    "primary": {
      "$value": "#007bff",
      "$type": "color"
    }
  }
}

Style Dictionary Format

{
  "color": {
    "primary": { "value": "#007bff" }
  },
  "size": {
    "font": {
      "base": { "value": "16px" }
    }
  }
}

Implementation

CSS Variables

:root {
  /* Colors */
  --color-primary-50: #e3f2fd;
  --color-primary-500: #2196f3;
  --color-primary-900: #0d47a1;
  
  /* Typography */
  --font-family-sans: Inter, system-ui, sans-serif;
  --font-size-sm: 14px;
  --font-size-md: 16px;
  
  /* Spacing */
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-4: 16px;
  
  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
  
  /* Border radius */
  --radius-sm: 4px;
  --radius-md: 8px;
}

/* Usage */
.button {
  background-color: var(--color-primary-500);
  font-family: var(--font-family-sans);
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--radius-sm);
  box-shadow: var(--shadow-sm);
}

SCSS Variables

// _variables.scss
$color-primary-500: #2196f3;
$font-family-sans: Inter, system-ui, sans-serif;

// _mixins.scss
@mixin button-base {
  background-color: $color-primary-500;
  font-family: $font-family-sans;
}

JavaScript/TypeScript

// tokens.ts
export const tokens = {
  colors: {
    primary: {
      500: '#2196f3',
      900: '#0d47a1',
    },
  },
  spacing: {
    1: '4px',
    2: '8px',
    4: '16px',
  },
} as const;

// Helper function
export const getToken = (path: string) => {
  const keys = path.split('.');
  let value: any = tokens;
  for (const key of keys) {
    value = value[key];
  }
  return value;
};

Using Style Dictionary

Installation

npm install style-dictionary --save-dev

Configuration

// style-dictionary.config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{
        destination: '_variables.css',
        format: 'css/variables'
      }]
    },
    scss: {
      transformGroup: 'scss',
      buildPath: 'build/scss/',
      files: [{
        destination: '_variables.scss',
        format: 'scss/map-flat'
      }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'build/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/module'
      }]
    }
  }
};

Build

# Build all platforms
npx style-dictionary build

# Or build specific platform
npx style-dictionary build --platform css

Token Aliases

Referencing Tokens

{
  "color": {
    "primary": {
      "value": "#007bff"
    },
    "primary-hover": {
      "value": "{color.primary}"
    },
    "primary-light": {
      "value": "{color.primary.500}",
      "type": "color"
    }
  },
  "button": {
    "background": {
      "value": "{color.primary}"
    },
    "text": {
      "value": "#ffffff"
    }
  }
}

Computed Values

{
  "color": {
    "primary": {
      "value": "#007bff"
    },
    "primary-darker": {
      "value": "rgba({color.primary}, 0.8)",
      "type": "color"
    }
  }
}

Theming

Light/Dark Theme

{
  "color": {
    "bg": {
      "light": { "value": "#ffffff", "type": "color" },
      "dark": { "value": "#1a1a1a", "type": "color" }
    },
    "text": {
      "light": { "value": "#212121", "type": "color" },
      "dark": { "value": "#ffffff", "type": "color" }
    }
  }
}

CSS Theme Switching

:root {
  --color-bg: #ffffff;
  --color-text: #212121;
}

[data-theme="dark"] {
  --color-bg: #1a1a1a;
  --color-text: #ffffff;
}

body {
  background-color: var(--color-bg);
  color: var(--color-text);
}

Multiple Themes

/* Theme 1: Default */
.theme-default {
  --color-primary: #007bff;
  --color-secondary: #6c757d;
}

/* Theme 2: Ocean */
.theme-ocean {
  --color-primary: #0d6efd;
  --color-secondary: #6610f2;
}

/* Theme 3: Forest */
.theme-forest {
  --color-primary: #198754;
  --color-secondary: #6c757d;
}

Figma Integration

Token Studio

# Install Token Studio plugin
# Available in Figma Community

Install Token Studio plugin
Create tokens in Figma
Export to JSON
Process with Style Dictionary

Figma Variables (Native)

// Get Figma variables via API
const figmaTokens = {
  colors: {
    primary: figma.variables.getVariableByTokenName('primary').value
  }
};

Best Practices

Naming Conventions

// Good: Semantic naming
{
  "color": {
    "action": {
      "primary": { "value": "#007bff" },
      "secondary": { "value": "#6c757d" }
    },
    "background": {
      "default": { "value": "#ffffff" },
      "subtle": { "value": "#f8f9fa" }
    }
  }
}

// Avoid: Too specific
{
  "color": {
    "blue-button-background": { "value": "#007bff" },
    "blue-button-text": { "value": "#ffffff" }
  }
}

Organization

{
  "color": {
    "brand": { ... },
    "semantic": { ... },
    "neutral": { ... }
  },
  "font": { ... },
  "spacing": { ... },
  "shadow": { ... },
  "radius": { ... },
  "transition": { ... }
}

External Resources

Conclusion

Design Tokens provide a systematic approach to design consistency. Key points:

Create a single source of truth for design values
Use semantic naming over literal values
Export to multiple platforms (CSS, SCSS, JS, iOS, Android)
Support theming with token aliases
Use Style Dictionary for automated processing

Tokens bridge the gap between design systems and implementation, ensuring consistency across all platforms.