0
# Theme System
1

2
Comprehensive theme and design system management with CSS custom properties, color palettes, and configuration. The theme system provides a complete design token system for consistent styling.
3

4
## Capabilities
5

6
### Color Palette
7

8
Complete color system with semantic color names and comprehensive shade scales.
9

10
```typescript { .api }
11
const colors: {
12
  inherit: string;
13
  current: string;
14
  transparent: string;
15
  black: string;
16
  white: string;
17
  slate: {
18
    '50': string;
19
    '100': string;
20
    '200': string;
21
    '300': string;
22
    '400': string;
23
    '500': string;
24
    '600': string;
25
    '700': string;
26
    '800': string;
27
    '900': string;
28
    '950': string;
29
  };
30
  gray: Record<string, string>;
31
  zinc: Record<string, string>;
32
  neutral: Record<string, string>;
33
  stone: Record<string, string>;
34
  red: Record<string, string>;
35
  orange: Record<string, string>;
36
  amber: Record<string, string>;
37
  yellow: Record<string, string>;
38
  lime: Record<string, string>;
39
  green: Record<string, string>;
40
  emerald: Record<string, string>;
41
  teal: Record<string, string>;
42
  cyan: Record<string, string>;
43
  sky: Record<string, string>;
44
  blue: Record<string, string>;
45
  indigo: Record<string, string>;
46
  violet: Record<string, string>;
47
  purple: Record<string, string>;
48
  fuchsia: Record<string, string>;
49
  pink: Record<string, string>;
50
  rose: Record<string, string>;
51
};
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import colors from "tailwindcss/colors";
58

59
// Access specific colors
60
const primaryBlue = colors.blue['500']; // 'oklch(62.3% 0.214 259.815)'
61
const slate50 = colors.slate['50']; // 'oklch(98.4% 0.003 247.858)'
62

63
// Use in plugin
64
plugin(function({ addUtilities }) {
65
  addUtilities({
66
    '.text-brand': {
67
      color: colors.indigo['600'],
68
    },
69
    '.bg-success': {
70
      backgroundColor: colors.green['500'],
71
    },
72
  });
73
});
74

75
// Extend theme with custom colors
76
module.exports = {
77
  theme: {
78
    extend: {
79
      colors: {
80
        'brand': colors.purple,
81
        'custom': {
82
          light: colors.sky['100'],
83
          dark: colors.slate['800'],
84
        },
85
      },
86
    },
87
  },
88
};
89
```
90

91
### Default Theme Configuration
92

93
Complete default theme providing design tokens for all utility classes.
94

95
```typescript { .api }
96
const defaultTheme: {
97
  accentColor: (options: { theme: ThemeFn }) => any;
98
  animation: {
99
    none: string;
100
    spin: string;
101
    ping: string;
102
    pulse: string;
103
    bounce: string;
104
  };
105
  aria: Record<string, string>;
106
  aspectRatio: {
107
    auto: string;
108
    square: string;
109
    video: string;
110
  };
111
  backdropBlur: (options: { theme: ThemeFn }) => any;
112
  backdropBrightness: (options: { theme: ThemeFn }) => any;
113
  backdropContrast: (options: { theme: ThemeFn }) => any;
114
  backdropGrayscale: (options: { theme: ThemeFn }) => any;
115
  backdropHueRotate: (options: { theme: ThemeFn }) => any;
116
  backdropInvert: (options: { theme: ThemeFn }) => any;
117
  backdropOpacity: (options: { theme: ThemeFn }) => any;
118
  backdropSaturate: (options: { theme: ThemeFn }) => any;
119
  backdropSepia: (options: { theme: ThemeFn }) => any;
120
  backgroundColor: (options: { theme: ThemeFn }) => any;
121
  backgroundImage: Record<string, string>;
122
  backgroundOpacity: (options: { theme: ThemeFn }) => any;
123
  backgroundPosition: Record<string, string>;
124
  backgroundSize: Record<string, string>;
125
  blur: Record<string, string>;
126
  borderColor: (options: { theme: ThemeFn }) => any;
127
  borderOpacity: (options: { theme: ThemeFn }) => any;
128
  borderRadius: Record<string, string>;
129
  borderSpacing: (options: { theme: ThemeFn }) => any;
130
  borderWidth: Record<string, string>;
131
  boxShadow: Record<string, string>;
132
  boxShadowColor: (options: { theme: ThemeFn }) => any;
133
  brightness: Record<string, string>;
134
  caretColor: (options: { theme: ThemeFn }) => any;
135
  colors: () => typeof colors;
136
  columns: Record<string, string>;
137
  container: {};
138
  content: Record<string, string>;
139
  contrast: Record<string, string>;
140
  cursor: Record<string, string>;
141
  divideColor: (options: { theme: ThemeFn }) => any;
142
  divideOpacity: (options: { theme: ThemeFn }) => any;
143
  divideWidth: (options: { theme: ThemeFn }) => any;
144
  dropShadow: Record<string, string | string[]>;
145
  fill: (options: { theme: ThemeFn }) => any;
146
  flex: Record<string, string>;
147
  flexBasis: (options: { theme: ThemeFn }) => any;
148
  flexGrow: Record<string, string>;
149
  flexShrink: Record<string, string>;
150
  fontFamily: {
151
    sans: string[];
152
    serif: string[];
153
    mono: string[];
154
  };
155
  fontSize: Record<string, string | [string, { lineHeight: string }]>;
156
  fontWeight: Record<string, string>;
157
  gap: (options: { theme: ThemeFn }) => any;
158
  gradientColorStops: (options: { theme: ThemeFn }) => any;
159
  gradientColorStopPositions: Record<string, string>;
160
  grayscale: Record<string, string>;
161
  gridAutoColumns: Record<string, string>;
162
  gridAutoRows: Record<string, string>;
163
  gridColumn: Record<string, string>;
164
  gridColumnEnd: Record<string, string>;
165
  gridColumnStart: Record<string, string>;
166
  gridRow: Record<string, string>;
167
  gridRowEnd: Record<string, string>;
168
  gridRowStart: Record<string, string>;
169
  gridTemplateColumns: Record<string, string>;
170
  gridTemplateRows: Record<string, string>;
171
  height: (options: { theme: ThemeFn }) => any;
172
  hueRotate: Record<string, string>;
173
  inset: (options: { theme: ThemeFn }) => any;
174
  invert: Record<string, string>;
175
  keyframes: Record<string, Record<string, Record<string, string>>>;
176
  letterSpacing: Record<string, string>;
177
  lineHeight: Record<string, string>;
178
  listStyleType: Record<string, string>;
179
  listStyleImage: Record<string, string>;
180
  margin: (options: { theme: ThemeFn }) => any;
181
  lineClamp: Record<string, string>;
182
  maxHeight: (options: { theme: ThemeFn }) => any;
183
  maxWidth: (options: { theme: ThemeFn }) => any;
184
  minHeight: (options: { theme: ThemeFn }) => any;
185
  minWidth: (options: { theme: ThemeFn }) => any;
186
  objectPosition: Record<string, string>;
187
  opacity: Record<string, string>;
188
  order: Record<string, string>;
189
  outlineColor: (options: { theme: ThemeFn }) => any;
190
  outlineOffset: Record<string, string>;
191
  outlineWidth: Record<string, string>;
192
  padding: (options: { theme: ThemeFn }) => any;
193
  placeholderColor: (options: { theme: ThemeFn }) => any;
194
  placeholderOpacity: (options: { theme: ThemeFn }) => any;
195
  ringColor: (options: { theme: ThemeFn }) => any;
196
  ringOffsetColor: (options: { theme: ThemeFn }) => any;
197
  ringOffsetWidth: Record<string, string>;
198
  ringOpacity: (options: { theme: ThemeFn }) => any;
199
  ringWidth: Record<string, string>;
200
  rotate: Record<string, string>;
201
  saturate: Record<string, string>;
202
  scale: Record<string, string>;
203
  screens: {
204
    sm: string;
205
    md: string;
206
    lg: string;
207
    xl: string;
208
    '2xl': string;
209
  };
210
  scrollMargin: (options: { theme: ThemeFn }) => any;
211
  scrollPadding: (options: { theme: ThemeFn }) => any;
212
  sepia: Record<string, string>;
213
  skew: Record<string, string>;
214
  space: (options: { theme: ThemeFn }) => any;
215
  spacing: {
216
    px: string;
217
    0: string;
218
    0.5: string;
219
    1: string;
220
    1.5: string;
221
    2: string;
222
    2.5: string;
223
    3: string;
224
    3.5: string;
225
    4: string;
226
    5: string;
227
    6: string;
228
    7: string;
229
    8: string;
230
    9: string;
231
    10: string;
232
    11: string;
233
    12: string;
234
    14: string;
235
    16: string;
236
    20: string;
237
    24: string;
238
    28: string;
239
    32: string;
240
    36: string;
241
    40: string;
242
    44: string;
243
    48: string;
244
    52: string;
245
    56: string;
246
    60: string;
247
    64: string;
248
    72: string;
249
    80: string;
250
    96: string;
251
  };
252
  stroke: (options: { theme: ThemeFn }) => any;
253
  strokeWidth: Record<string, string>;
254
  supports: {};
255
  data: {};
256
  textColor: (options: { theme: ThemeFn }) => any;
257
  textDecorationColor: (options: { theme: ThemeFn }) => any;
258
  textDecorationThickness: Record<string, string>;
259
  textIndent: (options: { theme: ThemeFn }) => any;
260
  textOpacity: (options: { theme: ThemeFn }) => any;
261
  textUnderlineOffset: Record<string, string>;
262
  transformOrigin: Record<string, string>;
263
  transitionDelay: Record<string, string>;
264
  transitionDuration: Record<string, string>;
265
  transitionProperty: Record<string, string>;
266
  transitionTimingFunction: Record<string, string>;
267
  translate: (options: { theme: ThemeFn }) => any;
268
  size: (options: { theme: ThemeFn }) => any;
269
  width: (options: { theme: ThemeFn }) => any;
270
  willChange: Record<string, string>;
271
  zIndex: Record<string, string>;
272
};
273

274
type ThemeFn = (path: string) => any;
275
```
276

277
**Usage Examples:**
278

279
```typescript
280
import defaultTheme from "tailwindcss/defaultTheme";
281

282
// Extend default theme
283
module.exports = {
284
  theme: {
285
    extend: {
286
      fontFamily: {
287
        sans: ['Inter', ...defaultTheme.fontFamily.sans],
288
      },
289
      spacing: {
290
        ...defaultTheme.spacing,
291
        '18': '4.5rem',
292
        '88': '22rem',
293
      },
294
      screens: {
295
        ...defaultTheme.screens,
296
        '3xl': '1600px',
297
      },
298
    },
299
  },
300
};
301

302
// Use in plugin
303
plugin(function({ addComponents, theme }) {
304
  addComponents({
305
    '.btn': {
306
      padding: `${theme('spacing.2')} ${theme('spacing.4')}`,
307
      fontSize: theme('fontSize.sm'),
308
      fontWeight: theme('fontWeight.medium'),
309
      borderRadius: theme('borderRadius.md'),
310
    },
311
  });
312
});
313
```
314

315
### Color Palette Utilities
316

317
Utility for flattening nested color objects into flat key-value pairs.
318

319
```typescript { .api }
320
/**
321
 * Flattens a nested color palette object into flat key-value pairs
322
 * @param colors - Nested color object with color scales
323
 * @returns Flattened object with dot-notation keys
324
 */
325
function flattenColorPalette(colors: Colors): Record<string, string>;
326

327
interface Colors {
328
  [key: string | number]: string | Colors;
329
}
330
```
331

332
**Usage Examples:**
333

334
```typescript
335
import flattenColorPalette from "tailwindcss/lib/util/flattenColorPalette";
336
import colors from "tailwindcss/colors";
337

338
// Flatten default colors
339
const flatColors = flattenColorPalette(colors);
340
// Result: { 'blue-50': 'oklch(...)', 'blue-100': 'oklch(...)', ... }
341

342
// Flatten custom colors
343
const customColors = {
344
  primary: {
345
    50: '#eff6ff',
346
    100: '#dbeafe',
347
    500: '#3b82f6',
348
    900: '#1e3a8a',
349
  },
350
  secondary: '#10b981',
351
};
352

353
const flattened = flattenColorPalette(customColors);
354
// Result: { 'primary-50': '#eff6ff', 'primary-100': '#dbeafe', 'primary-500': '#3b82f6', 'primary-900': '#1e3a8a', 'secondary': '#10b981' }
355

356
// Use in plugin
357
plugin(function({ addUtilities, theme }) {
358
  const colors = flattenColorPalette(theme('colors'));
359
  const utilities = Object.entries(colors).reduce((acc, [key, value]) => {
360
    acc[`.border-${key}`] = { borderColor: value };
361
    return acc;
362
  }, {});
363
  
364
  addUtilities(utilities);
365
});
366
```
367

368
## Theme Configuration
369

370
### Responsive Breakpoints
371

372
Default screen breakpoints for responsive design:
373

374
```typescript { .api }
375
const screens = {
376
  sm: '40rem',    // 640px
377
  md: '48rem',    // 768px  
378
  lg: '64rem',    // 1024px
379
  xl: '80rem',    // 1280px
380
  '2xl': '96rem', // 1536px
381
};
382
```
383

384
### Spacing Scale
385

386
Core spacing scale used for padding, margin, width, height, and more:
387

388
```typescript { .api }
389
const spacing = {
390
  px: '1px',
391
  0: '0px',
392
  0.5: '0.125rem',  // 2px
393
  1: '0.25rem',     // 4px
394
  1.5: '0.375rem',  // 6px
395
  2: '0.5rem',      // 8px
396
  2.5: '0.625rem',  // 10px
397
  3: '0.75rem',     // 12px
398
  3.5: '0.875rem',  // 14px
399
  4: '1rem',        // 16px
400
  5: '1.25rem',     // 20px
401
  6: '1.5rem',      // 24px
402
  7: '1.75rem',     // 28px
403
  8: '2rem',        // 32px
404
  9: '2.25rem',     // 36px
405
  10: '2.5rem',     // 40px
406
  11: '2.75rem',    // 44px
407
  12: '3rem',       // 48px
408
  14: '3.5rem',     // 56px
409
  16: '4rem',       // 64px
410
  20: '5rem',       // 80px
411
  24: '6rem',       // 96px
412
  28: '7rem',       // 112px
413
  32: '8rem',       // 128px
414
  36: '9rem',       // 144px
415
  40: '10rem',      // 160px
416
  44: '11rem',      // 176px
417
  48: '12rem',      // 192px
418
  52: '13rem',      // 208px
419
  56: '14rem',      // 224px
420
  60: '15rem',      // 240px
421
  64: '16rem',      // 256px
422
  72: '18rem',      // 288px
423
  80: '20rem',      // 320px
424
  96: '24rem',      // 384px
425
};
426
```
427

428
### Typography Scale
429

430
Font sizes with corresponding line heights:
431

432
```typescript { .api }
433
const fontSize = {
434
  xs: ['0.75rem', { lineHeight: '1rem' }],     // 12px
435
  sm: ['0.875rem', { lineHeight: '1.25rem' }], // 14px
436
  base: ['1rem', { lineHeight: '1.5rem' }],    // 16px
437
  lg: ['1.125rem', { lineHeight: '1.75rem' }], // 18px
438
  xl: ['1.25rem', { lineHeight: '1.75rem' }],  // 20px
439
  '2xl': ['1.5rem', { lineHeight: '2rem' }],   // 24px
440
  '3xl': ['1.875rem', { lineHeight: '2.25rem' }], // 30px
441
  '4xl': ['2.25rem', { lineHeight: '2.5rem' }],   // 36px
442
  '5xl': ['3rem', { lineHeight: '1' }],           // 48px
443
  '6xl': ['3.75rem', { lineHeight: '1' }],        // 60px
444
  '7xl': ['4.5rem', { lineHeight: '1' }],         // 72px
445
  '8xl': ['6rem', { lineHeight: '1' }],           // 96px
446
  '9xl': ['8rem', { lineHeight: '1' }],           // 128px
447
};
448
```
449

450
### Animation Presets
451

452
Built-in animation utilities:
453

454
```typescript { .api }
455
const animation = {
456
  none: 'none',
457
  spin: 'spin 1s linear infinite',
458
  ping: 'ping 1s cubic-bezier(0, 0, 0.2, 1) infinite',
459
  pulse: 'pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite',
460
  bounce: 'bounce 1s infinite',
461
};
462

463
const keyframes = {
464
  spin: {
465
    to: { transform: 'rotate(360deg)' },
466
  },
467
  ping: {
468
    '75%, 100%': {
469
      transform: 'scale(2)',
470
      opacity: '0',
471
    },
472
  },
473
  pulse: {
474
    '50%': { opacity: '.5' },
475
  },
476
  bounce: {
477
    '0%, 100%': {
478
      transform: 'translateY(-25%)',
479
      animationTimingFunction: 'cubic-bezier(0.8,0,1,1)',
480
    },
481
    '50%': {
482
      transform: 'none',
483
      animationTimingFunction: 'cubic-bezier(0,0,0.2,1)',
484
    },
485
  },
486
};
487
```