| name | design-tokens-structure |
| description | Architects token systems with primitive, semantic, and component layers. Use when structuring tokens from scratch, adding multi-theme support, setting up token aliasing, or organizing token hierarchies. |
Design Tokens Structure
Overview
Establish the architectural foundation for a scalable design token system. Defines the three-layer token hierarchy (primitive → semantic → component) that enables theming, multi-brand support, and maintainable design systems.
When to Use
- Starting a new design system from scratch
- Restructuring an existing token system
- Adding multi-theme or multi-brand support
- Converting hardcoded values to tokens
- Creating a token governance strategy
Implementation Checklist
Copy this checklist when architecting a token system:
Token Architecture Setup:
- [ ] Audit existing values and establish naming conventions
- [ ] Define primitive tokens (raw values, context-free)
- [ ] Define semantic tokens (purpose-based, reference primitives)
- [ ] Create theme overrides (dark.json, brand variants)
- [ ] Add component tokens for complex stateful components
- [ ] Configure build output (CSS variables, Tailwind, JSON)
Quick Reference: Token Layers
| Layer | Also Called | Purpose | Example |
|---|
| Primitive | Core, Base, Global | Raw values, context-free | blue-500: #3b82f6 |
| Semantic | Alias, Purpose, Role | Meaning-based references | color-primary: {blue-500} |
| Component | Specific, Local | Component-scoped tokens | button-bg: {color-primary} |
The Three-Layer Architecture
┌─────────────────────────────────────────────────────────┐
│ COMPONENT TOKENS │
│ button-bg, card-border, input-focus-ring │
│ ↓ references │
├─────────────────────────────────────────────────────────┤
│ SEMANTIC TOKENS │
│ color-primary, color-bg-surface, spacing-page │
│ ↓ references │
├─────────────────────────────────────────────────────────┤
│ PRIMITIVE TOKENS │
│ blue-500, gray-100, spacing-16, radius-8 │
│ (raw values only) │
└─────────────────────────────────────────────────────────┘
Layer 1: Primitive Tokens
Raw design values with no semantic meaning. These are the building blocks.
Characteristics
- Context-free (no "primary", "background", etc.)
- Named by their intrinsic property (color: hue, spacing: size)
- Never change between themes
- Comprehensive palette of options
Structure
{
"primitive": {
"color": {
"gray": {
"50": { "value": "#f9fafb" },
"100": { "value": "#f3f4f6" },
"200": { "value": "#e5e7eb" },
"300": { "value": "#d1d5db" },
"400": { "value": "#9ca3af" },
"500": { "value": "#6b7280" },
"600": { "value": "#4b5563" },
"700": { "value": "#374151" },
"800": { "value": "#1f2937" },
"900": { "value": "#111827" },
"950": { "value": "#030712" }
},
"blue": {
"50": { "value": "#eff6ff" },
"100": { "value": "#dbeafe" },
"200": { "value": "#bfdbfe" },
"300": { "value": "#93c5fd" },
"400": { "value": "#60a5fa" },
"500": { "value": "#3b82f6" },
"600": { "value": "#2563eb" },
"700": { "value": "#1d4ed8" },
"800": { "value": "#1e40af" },
"900": { "value": "#1e3a8a" }
},
"green": { },
"red": { },
"amber": { }
},
"spacing": {
"0": { "value": "0" },
"1": { "value": "0.25rem" },
"2": { "value": "0.5rem" },
"3": { "value": "0.75rem" },
"4": { "value": "1rem" },
"5": { "value": "1.25rem" },
"6": { "value": "1.5rem" },
"8": { "value": "2rem" },
"10": { "value": "2.5rem" },
"12": { "value": "3rem" },
"16": { "value": "4rem" },
"20": { "value": "5rem" },
"24": { "value": "6rem" }
},
"radius": {
"none": { "value": "0" },
"sm": { "value": "0.125rem" },
"md": { "value": "0.375rem" },
"lg": { "value": "0.5rem" },
"xl": { "value": "0.75rem" },
"2xl": { "value": "1rem" },
"full": { "value": "9999px" }
},
"font": {
"family": {
"sans": { "value": "Inter, system-ui, sans-serif" },
"mono": { "value": "JetBrains Mono, monospace" }
},
"size": {
"xs": { "value": "0.75rem" },
"sm": { "value": "0.875rem" },
"md": { "value": "1rem" },
"lg": { "value": "1.125rem" },
"xl": { "value": "1.25rem" },
"2xl": { "value": "1.5rem" },
"3xl": { "value": "1.875rem" },
"4xl": { "value": "2.25rem" }
},
"weight": {
"normal": { "value": "400" },
"medium": { "value": "500" },
"semibold": { "value": "600" },
"bold": { "value": "700" }
}
}
}
}
Layer 2: Semantic Tokens
Purpose-based tokens that reference primitives. These tokens change between themes.
Characteristics
- Named by purpose/role, not appearance
- Reference primitive tokens only
- The only layer that changes per theme
- Describe "what for", not "what it looks like"
Structure
{
"semantic": {
"color": {
"bg": {
"primary": { "value": "{primitive.color.gray.50}" },
"secondary": { "value": "{primitive.color.gray.100}" },
"tertiary": { "value": "{primitive.color.gray.200}" },
"inverse": { "value": "{primitive.color.gray.900}" },
"brand": { "value": "{primitive.color.blue.500}" }
},
"text": {
"primary": { "value": "{primitive.color.gray.900}" },
"secondary": { "value": "{primitive.color.gray.600}" },
"tertiary": { "value": "{primitive.color.gray.500}" },
"inverse": { "value": "{primitive.color.gray.50}" },
"brand": { "value": "{primitive.color.blue.600}" },
"link": { "value": "{primitive.color.blue.600}" }
},
"border": {
"primary": { "value": "{primitive.color.gray.200}" },
"secondary": { "value": "{primitive.color.gray.300}" },
"focus": { "value": "{primitive.color.blue.500}" }
},
"status": {
"success": { "value": "{primitive.color.green.500}" },
"warning": { "value": "{primitive.color.amber.500}" },
"error": { "value": "{primitive.color.red.500}" },
"info": { "value": "{primitive.color.blue.500}" }
},
"interactive": {
"primary": { "value": "{primitive.color.blue.500}" },
"primary-hover": { "value": "{primitive.color.blue.600}" },
"primary-active": { "value": "{primitive.color.blue.700}" },
"secondary": { "value": "{primitive.color.gray.100}" },
"secondary-hover": { "value": "{primitive.color.gray.200}" }
}
},
"spacing": {
"page": { "value": "{primitive.spacing.6}" },
"section": { "value": "{primitive.spacing.12}" },
"element": { "value": "{primitive.spacing.4}" },
"inline": { "value": "{primitive.spacing.2}" }
},
"radius": {
"interactive": { "value": "{primitive.radius.md}" },
"container": { "value": "{primitive.radius.lg}" },
"pill": { "value": "{primitive.radius.full}" }
}
}
}
Dark Theme Override
{
"semantic": {
"color": {
"bg": {
"primary": { "value": "{primitive.color.gray.950}" },
"secondary": { "value": "{primitive.color.gray.900}" },
"tertiary": { "value": "{primitive.color.gray.800}" },
"inverse": { "value": "{primitive.color.gray.50}" }
},
"text": {
"primary": { "value": "{primitive.color.gray.50}" },
"secondary": { "value": "{primitive.color.gray.400}" },
"tertiary": { "value": "{primitive.color.gray.500}" },
"inverse": { "value": "{primitive.color.gray.900}" }
},
"border": {
"primary": { "value": "{primitive.color.gray.800}" },
"secondary": { "value": "{primitive.color.gray.700}" }
}
}
}
}
Layer 3: Component Tokens
Component-specific tokens that reference semantic tokens. Optional but powerful for complex components.
Characteristics
- Scoped to a specific component
- Reference semantic tokens (rarely primitives)
- Enable component-level customization
- Used for complex, stateful components
Structure
{
"component": {
"button": {
"primary": {
"bg": { "value": "{semantic.color.interactive.primary}" },
"bg-hover": { "value": "{semantic.color.interactive.primary-hover}" },
"text": { "value": "{semantic.color.text.inverse}" },
"border": { "value": "transparent" },
"radius": { "value": "{semantic.radius.interactive}" },
"padding-x": { "value": "{primitive.spacing.4}" },
"padding-y": { "value": "{primitive.spacing.2}" }
},
"secondary": {
"bg": { "value": "{semantic.color.interactive.secondary}" },
"bg-hover": { "value": "{semantic.color.interactive.secondary-hover}" },
"text": { "value": "{semantic.color.text.primary}" },
"border": { "value": "{semantic.color.border.primary}" }
},
"disabled": {
"bg": { "value": "{primitive.color.gray.100}" },
"text": { "value": "{primitive.color.gray.400}" }
}
},
"input": {
"bg": { "value": "{semantic.color.bg.primary}" },
"text": { "value": "{semantic.color.text.primary}" },
"placeholder": { "value": "{semantic.color.text.tertiary}" },
"border": { "value": "{semantic.color.border.primary}" },
"border-focus": { "value": "{semantic.color.border.focus}" },
"radius": { "value": "{semantic.radius.interactive}" },
"padding-x": { "value": "{primitive.spacing.3}" },
"padding-y": { "value": "{primitive.spacing.2}" }
},
"card": {
"bg": { "value": "{semantic.color.bg.primary}" },
"border": { "value": "{semantic.color.border.primary}" },
"radius": { "value": "{semantic.radius.container}" },
"padding": { "value": "{semantic.spacing.element}" },
"shadow": { "value": "{primitive.shadow.md}" }
}
}
}
CSS Output
Generated Variables
:root {
--primitive-color-gray-50: #f9fafb;
--primitive-color-gray-900: #111827;
--primitive-color-blue-500: #3b82f6;
--primitive-spacing-4: 1rem;
}
:root {
--color-bg-primary: var(--primitive-color-gray-50);
--color-text-primary: var(--primitive-color-gray-900);
--color-interactive-primary: var(--primitive-color-blue-500);
--spacing-element: var(--primitive-spacing-4);
}
[data-theme="dark"] {
--color-bg-primary: var(--primitive-color-gray-950);
--color-text-primary: var(--primitive-color-gray-50);
}
:root {
--button-primary-bg: var(--color-interactive-primary);
--button-primary-text: var(--color-text-inverse);
--card-bg: var(--color-bg-primary);
--card-padding: var(--spacing-element);
}
Usage in Components
.card {
background: var(--color-bg-primary);
color: var(--color-text-primary);
border: 1px solid var(--color-border-primary);
padding: var(--spacing-element);
}
.card {
background: var(--card-bg);
padding: var(--card-padding);
}
.card {
background: var(--primitive-color-gray-50);
}
File Organization
Recommended Structure
tokens/
├── primitive/
│ ├── colors.json
│ ├── spacing.json
│ ├── typography.json
│ ├── radius.json
│ └── shadows.json
├── semantic/
│ ├── light.json # Light theme semantic mappings
│ └── dark.json # Dark theme overrides
├── component/
│ ├── button.json
│ ├── input.json
│ └── card.json
└── index.json # Combines all for build
Flat vs Nested
Nested (Recommended for large systems):
{
"color": {
"bg": {
"primary": { "value": "..." }
}
}
}
Output: --color-bg-primary
Flat (Simpler for small systems):
{
"color-bg-primary": { "value": "..." }
}
Output: --color-bg-primary
Naming Conventions
Pattern: {category}-{property}-{variant}-{state}
| Category | Examples |
|---|
| color | color-bg-primary, color-text-secondary |
| spacing | spacing-page, spacing-inline |
| radius | radius-interactive, radius-container |
| font | font-size-lg, font-weight-bold |
| shadow | shadow-md, shadow-lg |
Semantic Naming Guidelines
| Use | Avoid |
|---|
color-text-primary | color-dark-gray |
color-bg-surface | color-white |
color-interactive-primary | color-blue |
spacing-page | spacing-24px |
color-status-error | color-red |
When to Add Each Layer
| Situation | Layers Needed |
|---|
| Simple app, single theme | Primitive + Semantic |
| Multi-theme (light/dark) | Primitive + Semantic (per theme) |
| Complex components | All three layers |
| Multi-brand (white-label) | All three + brand-specific overrides |
| Design tool sync | Primitive only to start |
Anti-Patterns
| Anti-Pattern | Problem | Solution |
|---|
| Semantic references semantic | Circular/complex chains | Semantic → Primitive only |
| Using primitives in components | Breaks theming | Use semantic tokens |
| Color names in semantic | Leaks visual info | Use purpose names |
| Too many component tokens | Maintenance burden | Only for complex states |
| Skipping semantic layer | Can't theme | Always have semantic layer |
Migrating Existing Tokens
Step 1: Audit Current Usage
Find all hardcoded values and existing variables.
Step 2: Create Primitive Layer
Extract unique values into primitives.
Step 3: Create Semantic Layer
Map primitives to purposes.
Step 4: Update Components
Replace hardcoded values with semantic tokens.
Step 5: Add Themes
Create theme-specific semantic overrides.
.button {
background: #3b82f6;
color: white;
}
.button {
background: var(--color-interactive-primary);
color: var(--color-text-inverse);
}
