botserver/docs/src/chapter-04/structure.md

Theme Structure

The gbtheme package follows a conventional layout that separates concerns between markup, styling, scripts, and assets.

theme-name.gbtheme/
├── web/
│   ├── index.html          # Main application shell
│   ├── chat.html          # Conversation UI
│   └── login.html         # Authentication page
├── css/
│   ├── main.css           # Core styles
│   ├── components.css     # UI component styling
│   └── responsive.css     # Media‑query breakpoints
├── js/
│   ├── app.js            # Front‑end logic, WebSocket handling
│   └── websocket.js      # Real‑time communication layer
└── assets/
    ├── images/
    ├── fonts/
    └── icons/

Design Principles

• Separation of concerns – HTML defines structure, CSS defines appearance, JS defines behavior.
• Custom properties – css/variables.css (included in main.css) provides theme colors, spacing, and radius that can be overridden per‑bot.
• Responsive – responsive.css uses mobile‑first breakpoints (@media (min-width: 768px)) to adapt the layout.
• Asset locality – All images, fonts, and icons are stored under assets/ to keep the theme self‑contained and portable.

Extending a Theme

1. Duplicate an existing theme folder (e.g., default.gbtheme → mybrand.gbtheme).
2. Edit css/main.css to change colors via the :root variables.
3. Replace web/index.html header/footer with brand‑specific markup.
4. Add new icons to assets/icons/ and reference them in the HTML.

The system automatically picks up any theme placed under @/templates/… when the bot’s configuration (.gbtheme entry in config.csv) points to the folder name.