Hardcoded values like #3b82f6 or 16px scattered through your codebase cause color drift, rebranding headaches, and design-dev mismatches. Design tokens solve this by centralizing values like colors, spacing, and typography under named variables.

Why Use Design Tokens?

  • Consistency: One source of truth prevents color drift across a large codebase.
  • Rebranding: Change a few token values to update the entire visual identity.
  • Design-Dev Parity: Designers and developers use the same token names.
  • Multi-Platform: One token set can generate CSS, iOS, Android, and other formats.

Token Types

  • Primitive Tokens: Raw values like --blue-500: #3b82f6;
  • Semantic Tokens: Purpose-based aliases like --color-primary: var(--blue-500);
  • Component Tokens: (Optional) Specific to individual components

Implementing Tokens in Tailwind

1. Define CSS Custom Properties

/* globals.css */ :root { --color-primary: 37 99 235; /* blue-600 in RGB */ --radius-md: 0.375rem; } .dark { --color-primary: 96 165 250; /* blue-400 for dark mode */ } 

2. Map Tokens to Tailwind Theme

// tailwind.config.js module.exports = { theme: { extend: { colors: { primary: `rgb(var(--color-primary) / <alpha-value>)`, }, borderRadius: { md: 'var(--radius-md)', }, }, }, }; 

3. Use in Components

function Button() { return ( <button className="bg-primary rounded-md px-4 py-2"> Click me </button> ); } 

Key Gotchas

  • Start small: Begin with 20-30 tokens, not 300.
  • Use semantics: Always alias primitives (--color-primary: var(--blue-600))
  • Document purpose: Unclear names like --color-accent cause confusion
  • Align design/code: Use the same token names in Figma and code

Tokens enable dark mode, accessibility features, and multi-platform styling when implemented properly. The pattern works best when combined with a utility-first framework like Tailwind.

This is a shorter version of a guide I wrote at Frontkit Studio. The full post has the complete walkthrough.