0
# Theme System
1

2
Complete theming system with React Context, comprehensive design tokens, responsive utilities, and TypeScript support. The theme system provides consistent design values across all components and enables responsive design patterns.
3

4
## Capabilities
5

6
### Theme Provider and Context
7

8
React Context-based theme system for providing theme values throughout the component tree.
9

10
```typescript { .api }
11
/**
12
 * Theme context provider component
13
 * @param props - Provider props with theme and children
14
 * @returns JSX element providing theme context
15
 */
16
function ThemeProvider(props: ThemeProviderProps): JSX.Element;
17

18
interface ThemeProviderProps {
19
  /** Theme object containing all design tokens */
20
  theme: Theme;
21
  /** Child components that will have access to theme */
22
  children: ReactNode;
23
}
24

25
/**
26
 * React context for theme values
27
 */
28
const ThemeContext: React.Context<{ theme: Theme }>;
29

30
/**
31
 * Hook to access the current theme from context
32
 * @returns Current theme object with all design tokens
33
 */
34
function useTheme(): Theme;
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { ThemeProvider, useTheme } from "@keystone-ui/core";
41
// Import default theme separately - check your build configuration for exact path
42
// import { theme } from "@keystone-ui/core/themes/default";
43

44
// Use the default theme or create custom theme
45
const defaultTheme = { /* default theme object */ };
46

47
// Provide theme to application
48
function App() {
49
  return (
50
    <ThemeProvider theme={defaultTheme}>
51
      <MyComponent />
52
    </ThemeProvider>
53
  );
54
}
55

56
// Access theme in components
57
function MyComponent() {
58
  const { colors, spacing, typography } = useTheme();
59
  
60
  return (
61
    <div style={{ 
62
      color: colors.foreground,
63
      padding: spacing.medium,
64
      fontFamily: typography.fontFamily.body
65
    }}>
66
      Themed content
67
    </div>
68
  );
69
}
70

71
// Custom theme
72
const customTheme = {
73
  ...theme,
74
  colors: {
75
    ...theme.colors,
76
    background: '#f5f5f5'
77
  }
78
};
79

80
<ThemeProvider theme={customTheme}>
81
  <App />
82
</ThemeProvider>
83
```
84

85
### Default Theme
86

87
Complete default theme object containing all design tokens and system values.
88

89
```typescript { .api }
90
/**
91
 * Default theme object with complete design system tokens
92
 */
93
const theme: Theme;
94

95
/**
96
 * Theme type derived from the default theme object
97
 */
98
type Theme = typeof theme;
99
```
100

101
**Accessing the Default Theme:**
102

103
The default theme object is not directly exported from the main package entry point. To use the default theme, you'll need to import it from its specific location:
104

105
```typescript
106
// Import from themes/default - actual path may vary based on build configuration
107
import { theme } from "@keystone-ui/core/themes/default";
108

109
// Or create your own theme following the Theme type structure
110
const customTheme: Theme = {
111
  // ... your theme configuration
112
};
113
```
114

115
### Responsive Media Query Utilities
116

117
Hook providing responsive design utilities built on Facepaint for breakpoint-based styling.
118

119
```typescript { .api }
120
/**
121
 * Hook providing responsive design utilities
122
 * @returns Object with media query utilities
123
 */
124
function useMediaQuery(): MediaQueryUtilities;
125

126
interface MediaQueryUtilities {
127
  /** Facepaint media query function for array-based responsive styles */
128
  mq: (styles: ResponsiveStyles) => any;
129
  /** Generate min-width media query string */  
130
  minBreak: (key: keyof Theme['breakpoints']) => string;
131
  /** Generate max-width media query string */
132
  maxBreak: (key: keyof Theme['breakpoints']) => string;
133
}
134

135
type ResponsiveStyles = {
136
  [property: string]: any | any[];
137
};
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
import { useMediaQuery, css } from "@keystone-ui/core";
144

145
function ResponsiveComponent() {
146
  const { mq, minBreak, maxBreak } = useMediaQuery();
147
  
148
  // Array-based responsive styles
149
  const responsiveStyles = mq({
150
    fontSize: ['14px', '16px', '18px', '20px'],
151
    padding: ['8px', '12px', '16px', '24px'],
152
    color: ['blue', 'green']
153
  });
154
  
155
  // Manual media queries
156
  const manualStyles = css`
157
    font-size: 14px;
158
    
159
    ${minBreak('medium')} {
160
      font-size: 18px;
161
    }
162
    
163
    ${maxBreak('small')} {
164
      display: none;
165
    }
166
  `;
167
  
168
  return <div css={responsiveStyles}>Responsive content</div>;
169
}
170
```
171

172
## Theme Structure
173

174
### Typography Scale
175

176
Complete typography system with font families, sizes, weights, and spacing.
177

178
```typescript { .api }
179
interface Typography {
180
  fontFamily: {
181
    body: string;
182
    heading: string;
183
    monospace: string;
184
  };
185
  fontSize: {
186
    xxxsmall: string;
187
    xxsmall: string;
188
    xsmall: string;
189
    small: string;
190
    medium: string;
191
    large: string;
192
    xlarge: string;
193
    xxlarge: string;
194
    xxxlarge: string;
195
    xxxxlarge: string;
196
    xxxxxlarge: string;
197
    xxxxxxlarge: string;
198
  };
199
  fontWeight: {
200
    light: number;
201
    regular: number;
202
    medium: number;
203
    semibold: number;
204
    bold: number;
205
    heavy: number;
206
  };
207
  leading: {
208
    tighter: number;
209
    tight: number;
210
    base: number;
211
    loose: number;
212
    looser: number;
213
  };
214
  tracking: {
215
    tighter: string;
216
    tight: string;
217
    base: string;
218
    loose: string;
219
    looser: string;
220
  };
221
}
222
```
223

224
### Color Palette
225

226
Comprehensive color system with neutral colors and semantic color scales.
227

228
```typescript { .api }
229
interface Palette {
230
  // Base colors
231
  black: string;
232
  white: string;
233
  current: string;
234
  transparent: string;
235
  
236
  // Neutral scale
237
  neutral100: string;
238
  neutral200: string;
239
  neutral300: string;
240
  neutral400: string;
241
  neutral500: string;
242
  neutral600: string;
243
  neutral700: string;
244
  neutral800: string;
245
  neutral900: string;
246
  
247
  // Semantic color scales (50-900)
248
  blue50: string;
249
  blue100: string;
250
  // ... through blue900
251
  
252
  green50: string;
253
  green100: string;
254
  // ... through green900
255
  
256
  red50: string;
257
  red100: string;
258
  // ... through red900
259
  
260
  yellow50: string;
261
  yellow100: string;
262
  // ... through yellow900
263
  
264
  purple50: string;
265
  purple100: string;
266
  // ... through purple900
267
  
268
  pink50: string;
269
  pink100: string;
270
  // ... through pink900
271
}
272

273
interface Colors {
274
  background: string;
275
  backgroundMuted: string;
276
  backgroundDim: string;
277
  backgroundHover: string;
278
  border: string;
279
  borderCritical: string;
280
  borderFocus: string;
281
  focusRing: string;
282
  foreground: string;
283
  foregroundMuted: string;
284
  foregroundDim: string;
285
  foregroundDisabled: string;
286
  linkColor: string;
287
  linkHoverColor: string;
288
  overlayBackground: string;
289
  loaderDark: string;
290
  loaderLight: string;
291
}
292
```
293

294
### Spacing and Layout
295

296
Spacing scales, breakpoints, sizing, and border radius values.
297

298
```typescript { .api }
299
interface Spacing {
300
  none: number;
301
  xxsmall: number;
302
  xsmall: number;
303
  small: number;
304
  medium: number;
305
  large: number;
306
  xlarge: number;
307
  xxlarge: number;
308
}
309

310
interface Breakpoints {
311
  small: number;   // 576px
312
  medium: number;  // 768px
313
  large: number;   // 992px
314
  xlarge: number;  // 1200px
315
}
316

317
interface Sizing {
318
  xxsmall: number; // 16px
319
  xsmall: number;  // 20px
320
  small: number;   // 24px
321
  medium: number;  // 32px
322
  large: number;   // 38px
323
  xlarge: number;  // 42px
324
  xxlarge: number; // 48px
325
}
326

327
interface Radii {
328
  none: number;    // 0
329
  xsmall: number;  // 4px
330
  small: number;   // 6px
331
  medium: number;  // 8px
332
  large: number;   // 12px
333
  full: number;    // 9999px
334
}
335
```
336

337
### Visual Effects
338

339
Shadows, elevation, opacity, and animation values.
340

341
```typescript { .api }
342
interface Shadow {
343
  s100: string; // Cards
344
  s200: string; // Inline dialogs
345
  s300: string; // Tooltip
346
  s400: string; // Modals
347
  s500: string; // Toasts
348
}
349

350
interface Elevation {
351
  e100: number; // 100 - Cards
352
  e200: number; // 200 - Inline dialogs
353
  e300: number; // 300 - Tooltip
354
  e400: number; // 400 - Modals
355
  e500: number; // 500 - Toasts
356
}
357

358
interface Opacity {
359
  full: number;     // 1
360
  none: number;     // 0
361
  disabled: number; // 0.65
362
}
363

364
interface Animation {
365
  duration0: string;    // 0ms
366
  duration50: string;   // 40ms
367
  duration100: string;  // 130ms
368
  // ... through duration1000
369
  
370
  spring: string;       // cubic-bezier(0.2, 0, 0, 1.6)
371
  easeInOut: string;    // cubic-bezier(.45, 0, .40, 1)
372
  easeIn: string;       // cubic-bezier(0.2, 0, 0, 1)
373
  easeOut: string;      // cubic-bezier(0.165, 0.840, 0.440, 1)
374
  linear: string;       // cubic-bezier(0, 0, 1, 1)
375
}
376
```
377

378
### Component-Specific Tokens
379

380
Specialized tokens for headings, controls, and form fields.
381

382
```typescript { .api }
383
interface HeadingStyles {
384
  h1: HeadingStyle;
385
  h2: HeadingStyle;
386
  h3: HeadingStyle;
387
  h4: HeadingStyle;
388
  h5: HeadingStyle;
389
  h6: HeadingStyle;
390
}
391

392
interface HeadingStyle {
393
  color: string;
394
  family: string;
395
  size: string;
396
  transform: string;
397
  weight: number;
398
}
399

400
interface ControlSizes {
401
  small: ControlSize;
402
  medium: ControlSize;
403
  large: ControlSize;
404
}
405

406
interface ControlSize {
407
  borderRadius: number;
408
  borderWidth: number;
409
  gutter: number;
410
  paddingX: number;
411
  paddingY: number;
412
  height: number;
413
  gap: number;
414
  fontSize: number | string;
415
  indicatorBoxSize: number | string;
416
  indicatorFontSize: number | string;
417
}
418
```
419

420
### Contextual Color Tones
421

422
Semantic color schemes for different UI states and contexts.
423

424
```typescript { .api }
425
interface Tones {
426
  active: Tone;
427
  passive: Tone;
428
  positive: Tone;
429
  warning: Tone;
430
  negative: Tone;
431
  help: Tone;
432
}
433

434
interface Tone {
435
  focusRing: string;
436
  border: [string, string, string];      // [default, hover, active]
437
  fill: [string, string, string];        // [default, hover, active]
438
  tint: [string, string, string];        // [subtle, medium, stronger]
439
  foreground: [string, string, string];  // [default, hover, active]
440
  fillForeground: [string, string, string]; // Text on fill backgrounds
441
}
442

443
interface SelectableColors {
444
  silver: SelectableColor;
445
  grey: SelectableColor;
446
  blue: SelectableColor;
447
  pink: SelectableColor;
448
  green: SelectableColor;
449
  purple: SelectableColor;
450
}
451

452
interface SelectableColor {
453
  border: string;
454
  fill: string;
455
  fillForeground: string;
456
  foreground: string;
457
  tint: string;
458
}
459
```
460

461
### Form Field Styling Tokens
462

463
Comprehensive styling tokens for form inputs, controls, and interactive states.
464

465
```typescript { .api }
466
interface Fields {
467
  // Base control styling
468
  controlBackground?: string;
469
  controlBorderColor?: string;
470
  controlBorderRadius?: number | string;
471
  controlBorderWidth?: number | string;
472
  controlForeground?: string;
473
  
474
  // Input field styling
475
  inputBackground?: string;
476
  inputBorderColor?: string;
477
  inputBorderRadius?: number | string;
478
  inputBorderWidth?: number | string;
479
  inputForeground?: string;
480
  inputPlaceholder?: string;
481
  
482
  // Labels and legends
483
  labelColor?: string;
484
  legendColor?: string;
485
  
486
  // Special controls
487
  switchForeground?: string;
488
  
489
  // Interactive states
490
  disabled: FieldStateTokens;
491
  focus: FieldStateTokens;
492
  hover: FieldStateTokens;
493
  invalid: FieldStateTokens;
494
  selected: FieldStateTokens;
495
}
496

497
interface FieldStateTokens {
498
  // Shared properties
499
  labelColor?: string;
500
  legendColor?: string;
501
  shadow?: string;
502
  
503
  // Control-specific properties
504
  controlBackground?: string;
505
  controlBorderColor?: string;
506
  controlBorderRadius?: number | string;
507
  controlForeground?: string;
508
  
509
  // Input-specific properties
510
  inputBackground?: string;
511
  inputBorderColor?: string;
512
  inputBorderRadius?: number | string;
513
  inputForeground?: string;
514
  iconColor?: string;
515
}
516
```
517

518
## Custom Theming
519

520
Create custom themes by extending or overriding the default theme:
521

522
```typescript
523
import { theme as defaultTheme } from "@keystone-ui/core";
524

525
// Extend existing theme
526
const customTheme = {
527
  ...defaultTheme,
528
  colors: {
529
    ...defaultTheme.colors,
530
    background: '#fafafa',
531
    foreground: '#333333'
532
  },
533
  spacing: {
534
    ...defaultTheme.spacing,
535
    huge: 64 // Add custom spacing value
536
  }
537
};
538

539
// Use custom theme
540
<ThemeProvider theme={customTheme}>
541
  <App />
542
</ThemeProvider>
543
```
544

545
## TypeScript Integration
546

547
The theme system provides full TypeScript support with type-safe access to all theme values:
548

549
```typescript
550
import { Theme } from "@keystone-ui/core";
551

552
// Type-safe theme usage
553
function useCustomStyles() {
554
  const theme = useTheme();
555
  
556
  // All theme properties are typed
557
  const styles = {
558
    color: theme.colors.foreground,        // ✓ Type-safe
559
    fontSize: theme.typography.fontSize.large, // ✓ Type-safe  
560
    padding: theme.spacing.medium,         // ✓ Type-safe
561
    // backgroundColor: theme.colors.invalid  // ✗ TypeScript error
562
  };
563
  
564
  return styles;
565
}
566

567
// Responsive prop type helper
568
type ResponsiveProp<T> = T | readonly (T | null)[];
569

570
// Usage in custom components
571
interface MyComponentProps {
572
  color?: ResponsiveProp<keyof Theme['palette']>;
573
  spacing?: ResponsiveProp<keyof Theme['spacing']>;
574
}
575
```