1# Token Architecture
2 
3Three-layer token system for scalable, themeable design systems.
4 
5## Layer Overview
6 
7```
8┌─────────────────────────────────────────┐
9│  Component Tokens                       │  Per-component overrides
10│  --button-bg, --card-padding            │
11├─────────────────────────────────────────┤
12│  Semantic Tokens                        │  Purpose-based aliases
13│  --color-primary, --spacing-section     │
14├─────────────────────────────────────────┤
15│  Primitive Tokens                       │  Raw design values
16│  --color-blue-600, --space-4            │
17└─────────────────────────────────────────┘
18```
19 
20## Why Three Layers?
21 
22| Layer | Purpose | When to Change |
23|-------|---------|----------------|
24| Primitive | Base values (colors, sizes) | Rarely - foundational |
25| Semantic | Meaning assignment | Theme switching |
26| Component | Component customization | Per-component needs |
27 
28## Layer 1: Primitive Tokens
29 
30Raw design values without semantic meaning.
31 
32```css
33:root {
34  /* Colors */
35  --color-gray-50: #F9FAFB;
36  --color-gray-900: #111827;
37  --color-blue-500: #3B82F6;
38  --color-blue-600: #2563EB;
39 
40  /* Spacing (4px base) */
41  --space-1: 0.25rem;  /* 4px */
42  --space-2: 0.5rem;   /* 8px */
43  --space-4: 1rem;     /* 16px */
44  --space-6: 1.5rem;   /* 24px */
45 
46  /* Typography */
47  --font-size-sm: 0.875rem;
48  --font-size-base: 1rem;
49  --font-size-lg: 1.125rem;
50 
51  /* Radius */
52  --radius-sm: 0.25rem;
53  --radius-default: 0.5rem;
54  --radius-lg: 0.75rem;
55 
56  /* Shadows */
57  --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
58  --shadow-default: 0 1px 3px rgb(0 0 0 / 0.1);
59}
60```
61 
62## Layer 2: Semantic Tokens
63 
64Purpose-based aliases that reference primitives.
65 
66```css
67:root {
68  /* Background */
69  --color-background: var(--color-gray-50);
70  --color-foreground: var(--color-gray-900);
71 
72  /* Primary */
73  --color-primary: var(--color-blue-600);
74  --color-primary-hover: var(--color-blue-700);
75 
76  /* Secondary */
77  --color-secondary: var(--color-gray-100);
78  --color-secondary-foreground: var(--color-gray-900);
79 
80  /* Muted */
81  --color-muted: var(--color-gray-100);
82  --color-muted-foreground: var(--color-gray-500);
83 
84  /* Destructive */
85  --color-destructive: var(--color-red-600);
86  --color-destructive-foreground: white;
87 
88  /* Spacing */
89  --spacing-component: var(--space-4);
90  --spacing-section: var(--space-6);
91}
92```
93 
94## Layer 3: Component Tokens
95 
96Component-specific tokens referencing semantic layer.
97 
98```css
99:root {
100  /* Button */
101  --button-bg: var(--color-primary);
102  --button-fg: white;
103  --button-hover-bg: var(--color-primary-hover);
104  --button-padding-x: var(--space-4);
105  --button-padding-y: var(--space-2);
106  --button-radius: var(--radius-default);
107 
108  /* Input */
109  --input-bg: var(--color-background);
110  --input-border: var(--color-gray-300);
111  --input-focus-ring: var(--color-primary);
112  --input-padding: var(--space-2) var(--space-3);
113 
114  /* Card */
115  --card-bg: var(--color-background);
116  --card-border: var(--color-gray-200);
117  --card-padding: var(--space-4);
118  --card-radius: var(--radius-lg);
119  --card-shadow: var(--shadow-default);
120}
121```
122 
123## Dark Mode
124 
125Override semantic tokens for dark theme:
126 
127```css
128.dark {
129  --color-background: var(--color-gray-900);
130  --color-foreground: var(--color-gray-50);
131  --color-muted: var(--color-gray-800);
132  --color-muted-foreground: var(--color-gray-400);
133  --color-secondary: var(--color-gray-800);
134}
135```
136 
137## Naming Convention
138 
139```
140--{category}-{item}-{variant}-{state}
141 
142Examples:
143--color-primary           # category-item
144--color-primary-hover     # category-item-state
145--button-bg-hover         # component-property-state
146--space-section-sm        # category-semantic-variant
147```
148 
149## Categories
150 
151| Category | Examples |
152|----------|----------|
153| color | primary, secondary, muted, destructive |
154| space | 1, 2, 4, 8, section, component |
155| font-size | xs, sm, base, lg, xl |
156| radius | sm, default, lg, full |
157| shadow | sm, default, lg |
158| duration | fast, normal, slow |
159 
160## File Organization
161 
162```
163tokens/
164├── primitives.css     # Raw values
165├── semantic.css       # Purpose aliases
166├── components.css     # Component tokens
167└── index.css          # Imports all
168```
169 
170Or single file with layer comments:
171 
172```css
173/* === PRIMITIVES === */
174:root { ... }
175 
176/* === SEMANTIC === */
177:root { ... }
178 
179/* === COMPONENTS === */
180:root { ... }
181 
182/* === DARK MODE === */
183.dark { ... }
184```
185 
186## Migration from Flat Tokens
187 
188Before (flat):
189```css
190--button-primary-bg: #2563EB;
191--button-secondary-bg: #F3F4F6;
192```
193 
194After (three-layer):
195```css
196/* Primitive */
197--color-blue-600: #2563EB;
198--color-gray-100: #F3F4F6;
199 
200/* Semantic */
201--color-primary: var(--color-blue-600);
202--color-secondary: var(--color-gray-100);
203 
204/* Component */
205--button-bg: var(--color-primary);
206--button-secondary-bg: var(--color-secondary);
207```
208 
209## W3C DTCG Alignment
210 
211Token JSON format (W3C Design Tokens Community Group):
212 
213```json
214{
215  "color": {
216    "blue": {
217      "600": {
218        "$value": "#2563EB",
219        "$type": "color"
220      }
221    }
222  }
223}
224```
225