0
# Theme System
1

2
The Gemini CLI provides a comprehensive theming system with built-in themes, custom theme support, and accessibility features for terminal interface customization.
3

4
## Capabilities
5

6
### Theme Structure
7

8
Themes define the visual appearance of the terminal interface including colors, styling, and accessibility options.
9

10
```typescript { .api }
11
interface Theme {
12
  /** Theme display name */
13
  name: string;
14

15
  /** Theme category */
16
  type: 'light' | 'dark' | 'ansi' | 'custom';
17

18
  /** Primary accent color */
19
  primary?: string;
20

21
  /** Secondary accent color */
22
  secondary?: string;
23

24
  /** Background color */
25
  background?: string;
26

27
  /** Foreground/text color */
28
  foreground?: string;
29

30
  /** Additional color palette */
31
  colors?: {
32
    error?: string;
33
    warning?: string;
34
    success?: string;
35
    info?: string;
36
    muted?: string;
37
    highlight?: string;
38
  };
39

40
  /** Syntax highlighting colors */
41
  syntax?: {
42
    keyword?: string;
43
    string?: string;
44
    number?: string;
45
    comment?: string;
46
    function?: string;
47
    variable?: string;
48
  };
49
}
50
```
51

52
### Built-in Themes
53

54
The CLI includes a comprehensive set of built-in themes for various preferences.
55

56
#### Dark Themes
57

58
```typescript { .api }
59
const DARK_THEMES = [
60
  'ayu-dark',           // Modern dark theme with blue accents
61
  'atom-one-dark',      // Popular editor theme
62
  'dracula',            // High-contrast purple theme
63
  'default',            // Default dark theme
64
  'github-dark',        // GitHub's dark theme
65
  'shades-of-purple'    // Purple-focused theme
66
] as const;
67
```
68

69
#### Light Themes
70

71
```typescript { .api }
72
const LIGHT_THEMES = [
73
  'ayu-light',          // Clean light theme
74
  'default-light',      // Default light theme
75
  'github-light',       // GitHub's light theme
76
  'googlecode',         // Google Code style
77
  'xcode'               // Xcode-inspired theme
78
] as const;
79
```
80

81
#### ANSI Themes
82

83
```typescript { .api }
84
const ANSI_THEMES = [
85
  'ansi',               // Standard ANSI colors
86
  'ansi-light'          // Light ANSI variant
87
] as const;
88
```
89

90
#### Special Themes
91

92
```typescript { .api }
93
const SPECIAL_THEMES = [
94
  'no-color'            // Activated when NO_COLOR env var is set
95
] as const;
96
```
97

98
## Theme Management API
99

100
### Theme Manager
101

102
The theme system is managed through a central theme manager.
103

104
```typescript { .api }
105
interface ThemeManager {
106
  /**
107
   * Get list of all available theme names
108
   * @returns Array of theme names
109
   */
110
  getAvailableThemes(): string[];
111

112
  /**
113
   * Set the active theme
114
   * @param name - Theme name to activate
115
   * @throws Error if theme doesn't exist
116
   */
117
  setActiveTheme(name: string): void;
118

119
  /**
120
   * Get the currently active theme
121
   * @returns Current theme object
122
   */
123
  getActiveTheme(): Theme;
124

125
  /**
126
   * Load custom themes from configuration
127
   * @param themes - Custom theme definitions
128
   */
129
  loadCustomThemes(themes: Record<string, Theme>): void;
130

131
  /**
132
   * Get theme by name
133
   * @param name - Theme name
134
   * @returns Theme object or null if not found
135
   */
136
  getTheme(name: string): Theme | null;
137

138
  /**
139
   * Check if theme exists
140
   * @param name - Theme name to check
141
   * @returns True if theme exists
142
   */
143
  hasTheme(name: string): boolean;
144
}
145

146
/** Global theme manager instance */
147
const themeManager: ThemeManager;
148
```
149

150
### Theme Selection
151

152
```typescript { .api }
153
/**
154
 * Interactive theme selection interface
155
 * @returns Promise resolving to selected theme name
156
 */
157
function selectTheme(): Promise<string>;
158

159
/**
160
 * Set theme from command line or configuration
161
 * @param themeName - Name of theme to apply
162
 * @param scope - Settings scope to save in
163
 */
164
function applyTheme(
165
  themeName: string,
166
  scope: SettingScope
167
): Promise<void>;
168
```
169

170
## Custom Themes
171

172
### Custom Theme Definition
173

174
Users can define custom themes in their settings configuration.
175

176
```typescript { .api }
177
interface CustomTheme extends Theme {
178
  /** Theme type must be 'custom' */
179
  type: 'custom';
180

181
  /** Base theme to inherit from (optional) */
182
  extends?: string;
183
}
184
```
185

186
**Usage Examples:**
187

188
```json
189
{
190
  "ui": {
191
    "customThemes": {
192
      "my-dark-theme": {
193
        "name": "My Dark Theme",
194
        "type": "custom",
195
        "primary": "#00d4ff",
196
        "secondary": "#ff6b6b",
197
        "background": "#1a1a1a",
198
        "foreground": "#e6e6e6",
199
        "colors": {
200
          "error": "#ff5555",
201
          "warning": "#f1fa8c",
202
          "success": "#50fa7b",
203
          "info": "#8be9fd"
204
        }
205
      },
206
      "corporate": {
207
        "name": "Corporate Theme",
208
        "type": "custom",
209
        "extends": "github-light",
210
        "primary": "#0366d6",
211
        "secondary": "#28a745"
212
      }
213
    }
214
  }
215
}
216
```
217

218
### Theme Inheritance
219

220
Custom themes can inherit from built-in themes:
221

222
```typescript { .api }
223
/**
224
 * Resolve theme inheritance chain
225
 * @param theme - Theme with potential inheritance
226
 * @param baseThemes - Available base themes
227
 * @returns Fully resolved theme
228
 */
229
function resolveThemeInheritance(
230
  theme: CustomTheme,
231
  baseThemes: Record<string, Theme>
232
): Theme;
233
```
234

235
## Theme Configuration
236

237
### Settings Integration
238

239
Themes are configured through the settings system:
240

241
```typescript { .api }
242
interface UISettings {
243
  /** Active theme name */
244
  theme?: string;
245

246
  /** Custom theme definitions */
247
  customThemes?: Record<string, CustomTheme>;
248

249
  /** Theme-related UI options */
250
  hideWindowTitle?: boolean;
251
  showLineNumbers?: boolean;
252
  showCitations?: boolean;
253
}
254
```
255

256
### Environment-Based Themes
257

258
Themes can be automatically selected based on environment:
259

260
```typescript { .api }
261
/**
262
 * Detect appropriate theme based on environment
263
 * @returns Recommended theme name
264
 */
265
function detectEnvironmentTheme(): string;
266

267
// Environment detection logic
268
const environmentThemes = {
269
  /** NO_COLOR environment variable set */
270
  NO_COLOR: 'no-color',
271

272
  /** Cloud Shell environment */
273
  CLOUD_SHELL: 'ansi',
274

275
  /** Terminal with limited color support */
276
  LIMITED_COLORS: 'ansi-light'
277
};
278
```
279

280
## Interactive Theme Selection
281

282
### Theme Picker Interface
283

284
The CLI provides an interactive theme selection interface accessible via `/theme` command.
285

286
```typescript { .api }
287
interface ThemePickerOptions {
288
  /** Show theme previews */
289
  showPreview: boolean;
290

291
  /** Group themes by category */
292
  groupByType: boolean;
293

294
  /** Include custom themes */
295
  includeCustom: boolean;
296

297
  /** Current theme for highlighting */
298
  currentTheme: string;
299
}
300

301
/**
302
 * Display interactive theme picker
303
 * @param options - Picker configuration
304
 * @returns Selected theme name or null if cancelled
305
 */
306
function showThemePicker(
307
  options: ThemePickerOptions
308
): Promise<string | null>;
309
```
310

311
### Theme Preview
312

313
```typescript { .api }
314
interface ThemePreview {
315
  /** Sample code with syntax highlighting */
316
  codeSnippet: string;
317

318
  /** UI elements preview */
319
  uiElements: string[];
320

321
  /** Color palette display */
322
  colorPalette: string;
323
}
324

325
/**
326
 * Generate theme preview
327
 * @param theme - Theme to preview
328
 * @returns Preview content
329
 */
330
function generateThemePreview(theme: Theme): ThemePreview;
331
```
332

333
## Accessibility Features
334

335
### High Contrast Support
336

337
```typescript { .api }
338
interface AccessibilityTheme extends Theme {
339
  /** High contrast mode enabled */
340
  highContrast: boolean;
341

342
  /** Minimum contrast ratios */
343
  contrastRatios: {
344
    normal: number;
345
    large: number;
346
  };
347

348
  /** Screen reader optimizations */
349
  screenReaderOptimized: boolean;
350
}
351

352
/**
353
 * Validate theme accessibility
354
 * @param theme - Theme to validate
355
 * @returns Accessibility compliance report
356
 */
357
function validateThemeAccessibility(theme: Theme): {
358
  compliant: boolean;
359
  issues: string[];
360
  suggestions: string[];
361
};
362
```
363

364
### Color Blindness Support
365

366
```typescript { .api }
367
/**
368
 * Adjust theme for color blindness
369
 * @param theme - Original theme
370
 * @param type - Color blindness type
371
 * @returns Adjusted theme
372
 */
373
function adjustThemeForColorBlindness(
374
  theme: Theme,
375
  type: 'protanopia' | 'deuteranopia' | 'tritanopia'
376
): Theme;
377

378
/**
379
 * Test theme color combinations
380
 * @param theme - Theme to test
381
 * @returns Color accessibility report
382
 */
383
function testThemeColorAccessibility(theme: Theme): {
384
  combinations: Array<{
385
    foreground: string;
386
    background: string;
387
    contrast: number;
388
    wcagLevel: 'AA' | 'AAA' | 'fail';
389
  }>;
390
};
391
```
392

393
## Theme Development
394

395
### Theme Creation Utilities
396

397
```typescript { .api }
398
/**
399
 * Create theme from color palette
400
 * @param name - Theme name
401
 * @param palette - Color palette
402
 * @param type - Theme type
403
 * @returns Generated theme
404
 */
405
function createThemeFromPalette(
406
  name: string,
407
  palette: {
408
    primary: string;
409
    secondary: string;
410
    background: string;
411
    foreground: string;
412
  },
413
  type: 'light' | 'dark'
414
): Theme;
415

416
/**
417
 * Generate theme variants
418
 * @param baseTheme - Base theme
419
 * @returns Theme variants (light/dark)
420
 */
421
function generateThemeVariants(baseTheme: Theme): {
422
  light: Theme;
423
  dark: Theme;
424
};
425
```
426

427
### Theme Validation
428

429
```typescript { .api }
430
interface ThemeValidation {
431
  /** Validation success */
432
  valid: boolean;
433

434
  /** Validation errors */
435
  errors: string[];
436

437
  /** Validation warnings */
438
  warnings: string[];
439

440
  /** Missing required properties */
441
  missing: string[];
442
}
443

444
/**
445
 * Validate theme configuration
446
 * @param theme - Theme to validate
447
 * @returns Validation results
448
 */
449
function validateTheme(theme: Theme): ThemeValidation;
450
```
451

452
## Advanced Theme Features
453

454
### Dynamic Themes
455

456
```typescript { .api }
457
interface DynamicTheme extends Theme {
458
  /** Theme adapts to time of day */
459
  timeAdaptive: boolean;
460

461
  /** Theme adapts to system preference */
462
  systemAdaptive: boolean;
463

464
  /** Schedule for time-based switching */
465
  schedule?: {
466
    lightTheme: string;
467
    darkTheme: string;
468
    switchTimes: {
469
      toDark: string;    // "18:00"
470
      toLight: string;   // "06:00"
471
    };
472
  };
473
}
474

475
/**
476
 * Apply dynamic theme based on current conditions
477
 * @param dynamicTheme - Dynamic theme configuration
478
 * @returns Resolved theme name
479
 */
480
function resolveDynamicTheme(dynamicTheme: DynamicTheme): string;
481
```
482

483
### Theme Export/Import
484

485
```typescript { .api }
486
/**
487
 * Export theme to file
488
 * @param theme - Theme to export
489
 * @param format - Export format
490
 * @returns Exported theme data
491
 */
492
function exportTheme(
493
  theme: Theme,
494
  format: 'json' | 'css' | 'scss'
495
): string;
496

497
/**
498
 * Import theme from file
499
 * @param data - Theme data
500
 * @param format - Import format
501
 * @returns Imported theme
502
 */
503
function importTheme(
504
  data: string,
505
  format: 'json' | 'css' | 'scss'
506
): Theme;
507
```
508

509
### Theme Marketplace Integration
510

511
```typescript { .api }
512
interface ThemePackage {
513
  /** Package metadata */
514
  name: string;
515
  version: string;
516
  author: string;
517
  description: string;
518

519
  /** Included themes */
520
  themes: Record<string, Theme>;
521

522
  /** Package tags */
523
  tags: string[];
524

525
  /** Download statistics */
526
  stats: {
527
    downloads: number;
528
    rating: number;
529
  };
530
}
531

532
/**
533
 * Browse available theme packages
534
 * @param query - Search query
535
 * @returns Available theme packages
536
 */
537
function browseThemePackages(
538
  query?: string
539
): Promise<ThemePackage[]>;
540

541
/**
542
 * Install theme package
543
 * @param packageName - Package to install
544
 * @param scope - Installation scope
545
 */
546
function installThemePackage(
547
  packageName: string,
548
  scope: SettingScope
549
): Promise<void>;
550
```