botserver/docs/src/chapter-02/gbtheme.md

.gbtheme UI Theming

The .gbtheme package provides simple CSS-based theming for the bot's UI interface.

What is .gbtheme?

.gbtheme is a simplified theming system that uses CSS files to customize the bot's appearance. No complex HTML templates or JavaScript required - just CSS.

Theme Structure

A theme is simply one or more CSS files in the .gbtheme folder:

botname.gbtheme/
  default.css       # Main theme file
  dark.css         # Alternative theme
  holiday.css      # Seasonal theme

Using Themes

Default Theme

Place a default.css file in your .gbtheme folder:

/* default.css */
:root {
  --primary-color: #0d2b55;
  --secondary-color: #fff9c2;
  --background: #ffffff;
  --text-color: #333333;
  --font-family: 'Inter', sans-serif;
}

.chat-container {
  background: var(--background);
  color: var(--text-color);
}

.bot-message {
  background: var(--primary-color);
  color: white;
}

.user-message {
  background: var(--secondary-color);
  color: var(--text-color);
}

Changing Themes Dynamically

Use the BASIC keyword to switch themes at runtime:

' Switch to dark theme
CHANGE THEME "dark"

' Switch back to default
CHANGE THEME "default"

' Seasonal theme
IF month = 12 THEN
  CHANGE THEME "holiday"
END IF

CSS Variables

The bot interface uses CSS custom properties that themes can override:

Variable	Description	Default
--primary-color	Main brand color	#0d2b55
--secondary-color	Accent color	#fff9c2
--background	Page background	#ffffff
--text-color	Main text	#333333
--font-family	Typography	system-ui
--border-radius	Element corners	8px
--spacing	Base spacing unit	16px
--shadow	Box shadows	0 2px 4px rgba(0,0,0,0.1)

Simple Examples

Minimal Theme

/* minimal.css */
:root {
  --primary-color: #000000;
  --secondary-color: #ffffff;
}

Corporate Theme

/* corporate.css */
:root {
  --primary-color: #1e3a8a;
  --secondary-color: #f59e0b;
  --background: #f8fafc;
  --text-color: #1e293b;
  --font-family: 'Roboto', sans-serif;
  --border-radius: 4px;
}

Dark Theme

/* dark.css */
:root {
  --primary-color: #60a5fa;
  --secondary-color: #34d399;
  --background: #0f172a;
  --text-color: #e2e8f0;
}

body {
  background: var(--background);
  color: var(--text-color);
}

Best Practices

1. Keep it simple - Just override CSS variables
2. Use one file - Start with a single default.css
3. Test contrast - Ensure text is readable
4. Mobile-first - Design for small screens
5. Performance - Keep file size small

Theme Switching in Scripts

' User preference
preference = GET USER "theme_preference"
IF preference <> "" THEN
  CHANGE THEME preference
END IF

' Theme selection based on user preferences
' System handles theme switching automatically

Integration with config.csv

You can set the default theme in your bot's configuration:

name,value
theme,default
theme-color1,#0d2b55
theme-color2,#fff9c2

These values are available as CSS variables but the .css file takes precedence.

No Build Process Required

Unlike complex theming systems, .gbtheme:

• No webpack or build tools
• No preprocessors needed
• No template engines
• Just plain CSS files
• Hot reload on change

Migration from Complex Themes

If migrating from a complex theme system:

1. Extract colors - Find your brand colors
2. Create CSS - Map to CSS variables
3. Test interface - Verify appearance
4. Remove complexity - Delete unused assets

The bot's default UI handles layout and functionality - themes just customize appearance.