1# Semantic Tokens
2 
3Purpose-based aliases referencing primitive tokens.
4 
5## Color Semantics
6 
7### Background & Foreground
8 
9```css
10:root {
11  /* Page background */
12  --color-background: var(--color-gray-50);
13  --color-foreground: var(--color-gray-900);
14 
15  /* Card/surface background */
16  --color-card: white;
17  --color-card-foreground: var(--color-gray-900);
18 
19  /* Popover/dropdown */
20  --color-popover: white;
21  --color-popover-foreground: var(--color-gray-900);
22}
23```
24 
25### Primary
26 
27```css
28:root {
29  --color-primary: var(--color-blue-600);
30  --color-primary-hover: var(--color-blue-700);
31  --color-primary-active: var(--color-blue-800);
32  --color-primary-foreground: white;
33}
34```
35 
36### Secondary
37 
38```css
39:root {
40  --color-secondary: var(--color-gray-100);
41  --color-secondary-hover: var(--color-gray-200);
42  --color-secondary-foreground: var(--color-gray-900);
43}
44```
45 
46### Muted
47 
48```css
49:root {
50  --color-muted: var(--color-gray-100);
51  --color-muted-foreground: var(--color-gray-500);
52}
53```
54 
55### Accent
56 
57```css
58:root {
59  --color-accent: var(--color-gray-100);
60  --color-accent-foreground: var(--color-gray-900);
61}
62```
63 
64### Destructive
65 
66```css
67:root {
68  --color-destructive: var(--color-red-600);
69  --color-destructive-hover: var(--color-red-700);
70  --color-destructive-foreground: white;
71}
72```
73 
74### Status Colors
75 
76```css
77:root {
78  --color-success: var(--color-green-600);
79  --color-success-foreground: white;
80 
81  --color-warning: var(--color-yellow-500);
82  --color-warning-foreground: var(--color-gray-900);
83 
84  --color-error: var(--color-red-600);
85  --color-error-foreground: white;
86 
87  --color-info: var(--color-blue-500);
88  --color-info-foreground: white;
89}
90```
91 
92### Border & Ring
93 
94```css
95:root {
96  --color-border: var(--color-gray-200);
97  --color-input: var(--color-gray-200);
98  --color-ring: var(--color-blue-500);
99}
100```
101 
102## Spacing Semantics
103 
104```css
105:root {
106  /* Component internal spacing */
107  --spacing-component-xs: var(--space-1);
108  --spacing-component-sm: var(--space-2);
109  --spacing-component: var(--space-3);
110  --spacing-component-lg: var(--space-4);
111 
112  /* Section spacing */
113  --spacing-section-sm: var(--space-8);
114  --spacing-section: var(--space-12);
115  --spacing-section-lg: var(--space-16);
116 
117  /* Page margins */
118  --spacing-page-x: var(--space-4);
119  --spacing-page-y: var(--space-6);
120}
121```
122 
123## Typography Semantics
124 
125```css
126:root {
127  /* Headings */
128  --font-heading: var(--font-size-2xl);
129  --font-heading-lg: var(--font-size-3xl);
130  --font-heading-xl: var(--font-size-4xl);
131 
132  /* Body */
133  --font-body: var(--font-size-base);
134  --font-body-sm: var(--font-size-sm);
135  --font-body-lg: var(--font-size-lg);
136 
137  /* Labels & Captions */
138  --font-label: var(--font-size-sm);
139  --font-caption: var(--font-size-xs);
140}
141```
142 
143## Interactive States
144 
145```css
146:root {
147  /* Focus ring */
148  --ring-width: 2px;
149  --ring-offset: 2px;
150  --ring-color: var(--color-ring);
151 
152  /* Opacity for disabled */
153  --opacity-disabled: 0.5;
154 
155  /* Transitions */
156  --transition-colors: color, background-color, border-color;
157  --transition-transform: transform;
158  --transition-all: all;
159}
160```
161 
162## Dark Mode Overrides
163 
164```css
165.dark {
166  --color-background: var(--color-gray-950);
167  --color-foreground: var(--color-gray-50);
168 
169  --color-card: var(--color-gray-900);
170  --color-card-foreground: var(--color-gray-50);
171 
172  --color-popover: var(--color-gray-900);
173  --color-popover-foreground: var(--color-gray-50);
174 
175  --color-muted: var(--color-gray-800);
176  --color-muted-foreground: var(--color-gray-400);
177 
178  --color-secondary: var(--color-gray-800);
179  --color-secondary-foreground: var(--color-gray-50);
180 
181  --color-accent: var(--color-gray-800);
182  --color-accent-foreground: var(--color-gray-50);
183 
184  --color-border: var(--color-gray-800);
185  --color-input: var(--color-gray-800);
186}
187```
188 
189## Usage Patterns
190 
191### Applying Semantic Tokens
192 
193```css
194/* Good - uses semantic tokens */
195.card {
196  background: var(--color-card);
197  color: var(--color-card-foreground);
198  border: 1px solid var(--color-border);
199}
200 
201/* Bad - uses primitive tokens directly */
202.card {
203  background: var(--color-gray-50);
204  color: var(--color-gray-900);
205}
206```
207 
208### Theme Switching
209 
210Semantic tokens enable instant theme switching:
211 
212```js
213// Toggle dark mode
214document.documentElement.classList.toggle('dark');
215```
216