botserver/web/desktop/THEMES.md

General Bots Desktop - Theme System Documentation

Overview

The General Bots Desktop application uses a modern, flexible theme system based on CSS custom properties (CSS variables) with HSL color format. This system allows for easy customization and dynamic theme switching without page reloads.

Architecture

1. HSL-Based Theme Variables

All themes use HSL (Hue, Saturation, Lightness) format for colors, which provides several advantages:

• Easy color manipulation
• Better accessibility control
• Smooth color transitions
• Alpha transparency support

2. Two-Layer System

The theme system uses a two-layer approach:

Layer 1: Base Theme Variables (HSL Format)

Defined in theme files (public/themes/*.css) or css/app.css:

:root {
  --background: 0 0% 100%;           /* HSL: white */
  --foreground: 222 47% 11%;         /* HSL: dark gray */
  --primary: 217 91% 60%;            /* HSL: blue */
  --card: 0 0% 98%;                  /* HSL: light gray */
  /* ... more variables */
}

Layer 2: Working CSS Variables

Automatically derived in css/app.css:

:root {
  /* Convert HSL to usable CSS colors */
  --primary-bg: hsl(var(--background));
  --primary-fg: hsl(var(--foreground));
  --accent-color: hsl(var(--primary));
  
  /* With alpha transparency */
  --glass-bg: hsla(var(--background) / 0.7);
  --accent-light: hsla(var(--primary) / 0.1);
}

Available Theme Variables

Core Theme Variables (HSL Format)

These are the base variables that themes should override:

Variable	Purpose	Example Value
--background	Main background color	0 0% 100%
--foreground	Main text color	222 47% 11%
--card	Card background	0 0% 98%
--card-foreground	Card text	222 47% 11%
--popover	Popup background	0 0% 100%
--popover-foreground	Popup text	222 47% 11%
--primary	Primary accent color	217 91% 60%
--primary-foreground	Text on primary	0 0% 100%
--secondary	Secondary elements	214 32% 91%
--secondary-foreground	Text on secondary	222 47% 11%
--muted	Muted backgrounds	214 32% 91%
--muted-foreground	Muted text	215 16% 47%
--accent	Accent elements	214 32% 91%
--accent-foreground	Text on accent	222 47% 11%
--destructive	Error/danger color	0 84% 60%
--destructive-foreground	Text on destructive	0 0% 98%
--border	Border color	214 32% 91%
--input	Input background	214 32% 91%
--ring	Focus ring color	217 91% 60%
--radius	Border radius	0.5rem

Chart Colors

For data visualization:

Variable	Purpose
--chart-1	Primary chart color
--chart-2	Secondary chart color
--chart-3	Tertiary chart color
--chart-4	Quaternary chart color
--chart-5	Quinary chart color

Working Variables (Derived)

These are automatically calculated and should not be overridden in theme files:

• Layout: --primary-bg, --primary-fg, --secondary-bg, --secondary-fg
• Glass Effects: --glass-bg, --glass-border, --glass-shadow
• Text: --text-primary, --text-secondary, --text-tertiary, --text-muted
• Interactive: --accent-color, --accent-hover, --accent-light, --accent-gradient
• Borders: --border-color, --border-light, --border-dark
• States: --bg-hover, --bg-active, --bg-disabled
• Components: --user-message-bg, --bot-message-bg, --sidebar-bg, etc.
• Status: --success-color, --warning-color, --error-color, --info-color
• Shadows: --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl

Creating a New Theme

Step 1: Create Theme File

Create a new CSS file in public/themes/yourtheme.css:

:root {
  /* Theme Name: Your Theme */
  
  /* Base colors */
  --background: 240 10% 10%;           /* Dark blue-gray */
  --foreground: 0 0% 95%;              /* Light text */
  
  /* Card colors */
  --card: 240 10% 15%;
  --card-foreground: 0 0% 95%;
  
  /* Popup colors */
  --popover: 240 10% 10%;
  --popover-foreground: 0 0% 95%;
  
  /* Primary accent (main brand color) */
  --primary: 280 80% 60%;              /* Purple */
  --primary-foreground: 0 0% 100%;
  
  /* Secondary elements */
  --secondary: 240 10% 20%;
  --secondary-foreground: 0 0% 95%;
  
  /* Muted/subtle elements */
  --muted: 240 10% 25%;
  --muted-foreground: 240 5% 60%;
  
  /* Accent highlights */
  --accent: 320 80% 60%;               /* Pink accent */
  --accent-foreground: 0 0% 100%;
  
  /* Destructive/error states */
  --destructive: 0 85% 60%;
  --destructive-foreground: 0 0% 98%;
  
  /* Borders and inputs */
  --border: 240 10% 20%;
  --input: 240 10% 20%;
  --ring: 280 80% 60%;                 /* Focus ring matches primary */
  
  /* Border radius */
  --radius: 0.5rem;
  
  /* Chart colors */
  --chart-1: 280 80% 60%;              /* Purple */
  --chart-2: 320 80% 60%;              /* Pink */
  --chart-3: 200 80% 60%;              /* Cyan */
  --chart-4: 140 80% 60%;              /* Green */
  --chart-5: 40 80% 60%;               /* Orange */
}

Step 2: Register Theme

Add your theme to js/theme-manager.js:

const themes = [
  // ... existing themes
  { id: "yourtheme", name: "🎨 Your Theme", file: "yourtheme.css" }
];

Step 3: Test Your Theme

1. Reload the application
2. Open the theme dropdown in the header
3. Select your theme from the list
4. Verify all UI elements look correct

Theme Best Practices

1. Contrast Ratios

Ensure sufficient contrast between text and backgrounds:

• Normal text: Minimum 4.5:1 contrast ratio
• Large text: Minimum 3:1 contrast ratio
• Interactive elements: Minimum 3:1 contrast ratio

2. Color Harmony

Use complementary or analogous colors:

• Monochromatic: Different shades of the same hue
• Analogous: Colors next to each other on the color wheel
• Complementary: Colors opposite on the color wheel
• Triadic: Three colors evenly spaced on the color wheel

3. Accessibility

• Test with screen readers
• Ensure keyboard navigation works
• Provide sufficient color contrast
• Don't rely on color alone to convey information

4. HSL Values

Format: H S% L% (without commas, without hsl())

• Hue (H): 0-360 (color wheel position)
• Saturation (S): 0-100% (color intensity)
• Lightness (L): 0-100% (brightness)

Examples:

--primary: 217 91% 60%;    /* Bright blue */
--primary: 217 50% 60%;    /* Desaturated blue */
--primary: 217 91% 30%;    /* Dark blue */

5. Consistency

Maintain consistent:

• Saturation levels across related colors
• Lightness values for similar elements
• Hue relationships (complementary, analogous, etc.)

Using Themes in Components

Basic Usage

.my-component {
  background: var(--primary-bg);
  color: var(--text-primary);
  border: 1px solid var(--border-color);
  border-radius: var(--radius-md);
}

With Transparency

.my-glass-component {
  background: var(--glass-bg);
  backdrop-filter: blur(10px);
  border: 1px solid var(--glass-border);
}

State Changes

.my-button {
  background: var(--accent-color);
  color: hsl(var(--primary-foreground));
}

.my-button:hover {
  background: var(--accent-hover);
}

.my-button:active {
  background: var(--bg-active);
}

Custom Transparency

.my-overlay {
  background: hsla(var(--background) / 0.9);
  color: hsl(var(--foreground));
}

.my-highlight {
  background: hsla(var(--primary) / 0.15);
}

Built-in Themes

The application includes these pre-built themes:

1. Default - Clean, modern light theme
2. Orange - Office-inspired orange theme
3. Cyberpunk - Neon cyberpunk aesthetic
4. Retrowave - 80s synthwave vibes
5. Vapor Dream - Vaporwave aesthetic
6. Y2K Glow - Y2K-era design
7. 3D Bevel - Classic 3D beveled look
8. Arcade Flash - Retro arcade style
9. Disco Fever - 70s disco aesthetic
10. Grunge Era - 90s grunge style
11. Jazz Age - Art deco inspired
12. Mellow Gold - Warm, mellow tones
13. Mid Century Modern - 50s/60s design
14. Polaroid Memories - Vintage photo aesthetic
15. Saturday Cartoons - Bright, playful colors
16. Seaside Postcard - Beach-inspired palette
17. Typewriter - Classic typewriter look
18. Xerox UI - Office copier aesthetic
19. XTree Gold - DOS file manager tribute

Dark Mode Support

The system automatically detects system dark mode preference:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) {
    /* Automatically applied dark theme variables */
    --background: 222 47% 11%;
    --foreground: 213 31% 91%;
    /* ... */
  }
}

Themes can override this by setting their own values.

Troubleshooting

Theme Not Loading

1. Check browser console for errors
2. Verify file path in js/theme-manager.js
3. Ensure CSS file is in public/themes/ directory
4. Check CSS syntax (no hsl() wrapper needed)

Colors Look Wrong

1. Verify HSL format: H S% L% (spaces, not commas)
2. Check contrast ratios
3. Test with different system preferences (light/dark mode)
4. Clear browser cache

Theme Not Persisting

Themes are saved to localStorage with key gb-theme. Check:

1. localStorage is enabled
2. No browser extensions blocking storage
3. Clear localStorage and try again

API Reference

ThemeManager

// Initialize theme system
ThemeManager.init();

// Load specific theme
ThemeManager.loadTheme('cyberpunk');

// Subscribe to theme changes
ThemeManager.subscribe((data) => {
  console.log(`Theme changed to: ${data.themeName}`);
});

// Get available themes
const themes = ThemeManager.getAvailableThemes();

Performance Considerations

• CSS custom properties update instantly
• No page reload required
• Themes are cached after first load
• Minimal performance impact
• Works with backdrop-filter and other modern CSS

Browser Support

• Chrome/Edge 88+
• Firefox 89+
• Safari 14+
• All modern browsers with CSS custom property support

Contributing

To contribute a new theme:

1. Create theme file following the structure above
2. Test thoroughly across all sections (Chat, Drive, Tasks, Mail)
3. Ensure accessibility standards are met
4. Add to theme registry in theme-manager.js
5. Document any special features or requirements

Resources

• HSL Color Picker
• Coolors Palette Generator
• WebAIM Contrast Checker
• MDN CSS Custom Properties

---

Version: 1.0
Last Updated: 2024
Maintained by: General Bots Team