0
# Theme System
1

2
Comprehensive theme configuration providing the foundation for all utility generation, including colors, spacing, typography, breakpoints, and design tokens based on Tailwind CSS standards.
3

4
## Capabilities
5

6
### Theme Object
7

8
The main theme configuration object containing all design tokens and configuration values.
9

10
```typescript { .api }
11
const theme: Theme;
12

13
interface Theme {
14
  /** Size properties */
15
  width?: Record<string, string>;
16
  height?: Record<string, string>;
17
  maxWidth?: Record<string, string>;
18
  maxHeight?: Record<string, string>;
19
  minWidth?: Record<string, string>;
20
  minHeight?: Record<string, string>;
21
  inlineSize?: Record<string, string>;
22
  blockSize?: Record<string, string>;
23
  maxInlineSize?: Record<string, string>;
24
  maxBlockSize?: Record<string, string>;
25
  minInlineSize?: Record<string, string>;
26
  minBlockSize?: Record<string, string>;
27
  
28
  /** Border and corner properties */
29
  borderRadius?: Record<string, string>;
30
  
31
  /** Responsive breakpoints */
32
  breakpoints?: Record<string, string>;
33
  verticalBreakpoints?: Record<string, string>;
34
  
35
  /** Color system */
36
  colors?: Colors;
37
  borderColor?: Colors;
38
  backgroundColor?: Colors;
39
  textColor?: Colors;
40
  shadowColor?: Colors;
41
  accentColor?: Colors;
42
  
43
  /** Typography */
44
  fontFamily?: Record<string, string>;
45
  fontSize?: Record<string, string | [string, string | CSSObject] | [string, string, string]>;
46
  fontWeight?: Record<string, string>;
47
  lineHeight?: Record<string, string>;
48
  letterSpacing?: Record<string, string>;
49
  wordSpacing?: Record<string, string>;
50
  textIndent?: Record<string, string>;
51
  textShadow?: Record<string, string | string[]>;
52
  textStrokeWidth?: Record<string, string>;
53
  
54
  /** Layout and spacing */
55
  spacing?: Record<string, string>;
56
  
57
  /** Effects */
58
  boxShadow?: Record<string, string | string[]>;
59
  blur?: Record<string, string>;
60
  dropShadow?: Record<string, string | string[]>;
61
  
62
  /** Borders and outlines */
63
  ringWidth?: Record<string, string>;
64
  lineWidth?: Record<string, string>;
65
  
66
  /** Animation and transitions */
67
  duration?: Record<string, string>;
68
  easing?: Record<string, string>;
69
  transitionProperty?: Record<string, string>;
70
  animation?: ThemeAnimation;
71
  
72
  /** Accessibility and interaction */
73
  aria?: Record<string, string>;
74
  data?: Record<string, string>;
75
  zIndex?: Record<string, string>;
76
  
77
  /** Media and container queries */
78
  media?: Record<string, string>;
79
  supports?: Record<string, string>;
80
  containers?: Record<string, string>;
81
  
82
  /** Grid layout */
83
  gridAutoColumn?: Record<string, string>;
84
  gridAutoRow?: Record<string, string>;
85
  gridColumn?: Record<string, string>;
86
  gridRow?: Record<string, string>;
87
  gridTemplateColumn?: Record<string, string>;
88
  gridTemplateRow?: Record<string, string>;
89
  
90
  /** Container configuration */
91
  container?: {
92
    center?: boolean;
93
    padding?: string | Record<string, string>;
94
    maxWidth?: Record<string, string>;
95
  };
96
  
97
  /** CSS custom properties configuration */
98
  preflightRoot?: Arrayable<string>;
99
  preflightBase?: Record<string, string | number>;
100
}
101

102
interface ThemeAnimation {
103
  keyframes?: Record<string, string>;
104
  durations?: Record<string, string>;
105
  timingFns?: Record<string, string>;
106
  properties?: Record<string, object>;
107
  counts?: Record<string, string | number>;
108
  category?: Record<string, string>;
109
}
110
```
111

112
**Usage Example:**
113

114
```typescript
115
import { theme } from "@unocss/preset-mini/theme";
116

117
// Access theme values
118
const primaryColor = theme.colors?.blue?.[500]; // '#3b82f6'
119
const smallSpacing = theme.spacing?.['1']; // '0.25rem'
120
const mediumBreakpoint = theme.breakpoints?.md; // '768px'
121
```
122

123
### Colors Object
124

125
Complete color palette with semantic color names and numeric scales, compatible with Tailwind CSS.
126

127
```typescript { .api }
128
const colors: Colors;
129

130
interface Colors {
131
  [key: string]: Colors & { DEFAULT?: string } | string;
132
}
133
```
134

135
The colors object includes:
136

137
**Standard Colors** (each with scales 50-950):
138
- `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`
139

140
**Neutral Colors** (each with scales 50-950):
141
- `gray`, `slate`, `zinc`, `neutral`, `stone`
142

143
**Special Colors**:
144
- `black`: `'#000'`
145
- `white`: `'#fff'`
146
- `transparent`: `'transparent'`
147
- `current`: `'currentColor'`
148
- `inherit`: `'inherit'`
149

150
**Theme-specific Colors**:
151
- `light`: Light theme color scales (50-950)
152
- `dark`: Dark theme color scales (50-950)
153

154
**Color Aliases**:
155
- `lightblue` / `lightBlue` → `sky`
156
- `warmgray` / `warmGray` → `stone`
157
- `truegray` / `trueGray` → `neutral`
158
- `coolgray` / `coolGray` → `gray`
159
- `bluegray` / `blueGray` → `slate`
160

161
**Usage Examples:**
162

163
```typescript
164
import { colors } from "@unocss/preset-mini/colors";
165

166
// Standard color access
167
const primaryBlue = colors.blue[500]; // '#3b82f6'
168
const lightGray = colors.gray[100]; // '#f3f4f6'
169

170
// Default color values (color[400])
171
const defaultBlue = colors.blue.DEFAULT; // '#60a5fa'
172

173
// Short scale access (numeric/100)
174
const blue5 = colors.blue[5]; // Same as colors.blue[500]
175

176
// Special colors
177
const transparent = colors.transparent; // 'transparent'
178
const currentColor = colors.current; // 'currentColor'
179

180
// Aliases
181
const skyBlue = colors.lightBlue[300]; // Same as colors.sky[300]
182
```
183

184
### Default Theme Values
185

186
The theme includes comprehensive default values for all CSS properties:
187

188
**Spacing Scale** (0-96, plus larger values):
189
```typescript
190
spacing: {
191
  '0': '0px',
192
  '1': '0.25rem',  // 4px
193
  '2': '0.5rem',   // 8px
194
  '4': '1rem',     // 16px
195
  '8': '2rem',     // 32px
196
  // ... continues to 96
197
  'xs': '0.75rem',
198
  'sm': '0.875rem',
199
  // ... additional named sizes
200
}
201
```
202

203
**Breakpoints**:
204
```typescript
205
breakpoints: {
206
  'sm': '640px',
207
  'md': '768px',
208
  'lg': '1024px',
209
  'xl': '1280px',
210
  '2xl': '1536px',
211
}
212
```
213

214
**Font Families**:
215
```typescript
216
fontFamily: {
217
  'sans': ['ui-sans-serif', 'system-ui', ...],
218
  'serif': ['ui-serif', 'Georgia', ...],
219
  'mono': ['ui-monospace', 'SFMono-Regular', ...],
220
}
221
```
222

223
**Border Radius**:
224
```typescript
225
borderRadius: {
226
  'none': '0px',
227
  'sm': '0.125rem',
228
  'DEFAULT': '0.25rem',
229
  'md': '0.375rem',
230
  'lg': '0.5rem',
231
  'xl': '0.75rem',
232
  '2xl': '1rem',
233
  '3xl': '1.5rem',
234
  'full': '9999px',
235
}
236
```
237

238
### Theme Customization
239

240
The theme can be extended or overridden in UnoCSS configuration:
241

242
```typescript
243
import { defineConfig } from "unocss";
244
import { presetMini } from "@unocss/preset-mini";
245

246
export default defineConfig({
247
  presets: [presetMini()],
248
  theme: {
249
    // Extend existing colors
250
    colors: {
251
      brand: {
252
        50: '#eff6ff',
253
        500: '#3b82f6',
254
        900: '#1e3a8a',
255
      },
256
    },
257
    // Override breakpoints
258
    breakpoints: {
259
      'xs': '475px',
260
      'sm': '640px',
261
      'md': '768px',
262
      'lg': '1024px',
263
      'xl': '1280px',
264
      '2xl': '1400px',
265
    },
266
    // Add custom spacing
267
    spacing: {
268
      '18': '4.5rem',
269
      '88': '22rem',
270
    },
271
  },
272
});
273
```