Appearance
Chat Themes Configuration
Chat Themes control how your public chat interface looks and behaves. Create reusable visual identities — colors, typography, spacing, header branding — and apply them across multiple agents for consistent brand experiences.
Overview
Access Chat Themes at /chat-themes to create and manage visual configurations for your public-facing chat interfaces.
What is a Chat Theme?
A chat theme owns visual identity and behavior defaults. It does NOT own per-agent content (greeting messages, welcome modals, suggested prompts) — those live in each agent's Chat Experience configuration.
The 3-Layer Model
Chat appearance resolves from three layers, highest priority first:
| Layer | Owns | Edited in |
|---|---|---|
| Agent Chat UI | Per-agent content: greeting, suggested prompts, follow-up prompts, auto-message. Also overrides theme behavior defaults (showHeader, showNewChatInNav, maxMessageLength) per-field. | Agent form → Chat Experience tab |
| Chat Theme | Reusable visual identity (branding) + behavior defaults (defaults). Agents can override defaults but never visuals. | /chat-themes editor |
| Component defaults | Fallback values when neither agent nor theme specifies a setting. | Code |
Key principle: branding is theme-only — once you set colors and typography in a theme, all agents using that theme share the same visual identity. Behavior like "show header" lives in defaults and agents can override it individually.
Example Use Case:
Theme: "Company Brand"
- Preset: Blue (base color palette)
- Primary color: #0052CC (brand exact)
- User bubble: navy bg, white text
- Font: Inter
Applied to:
- Support Agent (shows header, auto-connect on)
- Sales Agent (no header, follow-up prompts on)
- FAQ Agent (all defaults)
Result: Consistent brand colors across all agents; each agent controls its own layout.Chat Theme List
The main themes page displays all your custom themes.
View Modes
- List View: Table with detailed information
- Grid View: Visual cards showing color previews
Theme Card/Row
Each theme displays:
- Color Preview: Gradient showing the theme colors
- Name & Description: Theme identification
- Default Badge: Shows if this is your default theme
- In Use Count: Number of agents using this theme
- Actions: Configure, View, Duplicate, Set/Clear Default, Delete
Creating a Chat Theme
Navigate to /chat-themes/create for the theme editor. Editing an existing theme (/chat-themes/{id}) opens the same editor with the saved tokens already applied.
Editor Layout
The editor is a split-panel interface: a non-interactive live preview on the left and a Controls panel on the right. There is no click-to-edit canvas; all colour and style inputs are in the Controls panel.
| Region of the screen | What it does |
|---|---|
| Toolbar (top) | Theme name, surface tabs (Chat / Welcome / Sidebar), device-width preview (desktop / tablet / mobile), light/dark switch, undo/redo, Settings drawer, and Save |
| Preview (centre) | Non-interactive live <GnosariChat> instance seeded with a demo conversation (user message, assistant reply with markdown and avatar, message input). Every Controls panel change is reflected here in real time; the preview is not clickable for editing |
| Controls panel (right) | Brand — colour-theme preset picker, custom primary accent hex, surface hex, and a read-only derived-ramp preview of all tokens that auto-derive from accent + surface; Shape & type — global corner radius, font family, message density; Background pattern — pattern type, intensity, and color-source toggle; Advanced (collapsed accordion) — raw per-region hex overrides for user bubble, assistant bubble, header, and input (power-user escape hatch; a warn-inline fires when an override produces a sub-AA contrast pair) |
| Settings drawer (Settings button) | Theme details (name, description, identifier, default), behaviour defaults, and the custom CSS class (branding.className) |
Undo / redo and saving
Every change — Controls panel edits and the behaviour toggles in the drawer — pushes onto a single undo stack. Use the toolbar buttons or ⌘/Ctrl+Z / ⌘/Ctrl+⇧+Z. The undo floor is the loaded (or freshly initialised) theme, so undo can never wipe a loaded theme back to empty. An unsaved-changes dot sits on the Save button; saving fires a "Theme saved" confirmation. A saved theme renders identically in the editor preview, on /chat, and in the embedded widget (parity by construction).
Reset actions
Two distinct reset actions exist — they are not interchangeable:
| Action | Location | What it resets |
|---|---|---|
| Reset demo conversation | Preview header (next to the agent selector) | Restores the seeded demo transcript in the preview. Tokens are untouched. |
| Reset theme to preset | Controls panel → Brand → Colour theme section | Clears all token overrides (accent, surface, input, header text, bubbles, radius, …) and restores the preset's base palette. One undo entry. |
Where each setting lives
The reference tables below describe what each token and setting does — they remain accurate regardless of where the control sits in the editor.
| Setting group | Where to find it now |
|---|---|
| Theme details (name, description, identifier, default) | Settings drawer → Details (name also editable inline in the toolbar) |
| Colour preset + custom accent + surface | Controls panel → Brand |
| Bubble / surface / header colours (raw per-region overrides) | Controls panel → Advanced (collapsed accordion) |
| Font, global corner radius, density | Controls panel → Shape & type |
| Background pattern | Controls panel → Background pattern |
| Behaviour defaults (header, sidebar, model selection, auto-connect) | Settings drawer → Behaviour |
| Custom CSS class | Settings drawer → Advanced (branding.className) |
| Welcome experience & prompts | Agent-level content (see Welcome Experience and Prompts below) — set as theme defaults, each agent can override |
Theme Details
Basic information about your theme (set in the Settings drawer → Details; the name is also editable inline in the toolbar).
| Field | Description | Required |
|---|---|---|
| Name | Friendly theme name (e.g., "Customer Support Theme") | Yes |
| Description | Brief description of theme purpose | No |
| Identifier | URL-friendly slug (auto-generated from name) | Auto |
| Set as Default | Apply this theme to new agents automatically | No |
Example:
Name: Customer Support Professional
Description: Clean, professional theme for support conversations
Identifier: customer-support-professional
Default: YesColor Theme and Branding Tokens
The preset picker, accent, and surface inputs live in the Controls panel → Brand; per-region hex overrides (bubble, header, input) live in Controls panel → Advanced; font, radius, density, and background pattern live in their respective Controls panel sections. The tables below are the token reference — they describe what each token controls regardless of where the control sits in the editor.
Preset Color Themes
Choose from 22 professionally designed color palettes as a starting point.
Classic Themes (7)
| Theme | Best For |
|---|---|
| Purple | Creative services, design agencies |
| Blue | Corporate, financial services, tech support |
| Green | Eco-friendly, health & wellness, nature |
| Orange | Food & beverage, events, retail |
| Pink | Fashion, beauty, lifestyle |
| Indigo | Legal, consulting, premium services |
| Cyan | Tech startups, SaaS, innovation |
Fresh & Modern Themes (7)
| Theme | Best For |
|---|---|
| Rose | Wedding services, gifts, luxury |
| Amber | Premium products, high-end services |
| Teal | Wellness, meditation, healthcare |
| Fuchsia | Entertainment, nightlife, bold brands |
| Sky | Travel, aviation, cloud services |
| Emerald | Jewelry, luxury goods, finance |
| Violet | Music, arts, entertainment |
Social & Trendy Themes (8)
| Theme | Best For |
|---|---|
| Sunset | Photography, travel, experiences |
| Ocean | Marine services, water sports, travel |
| Forest | Outdoor activities, eco products |
| Neon | Gaming, tech, nightlife |
| Gold | VIP services, luxury, finance |
| Coral | Hospitality, restaurants, home decor |
| Lavender | Wellness, beauty, relaxation |
| Mint | Health, hygiene, modern brands |
A preset is a starting-point token bundle that the chat interface expands at render time. Selecting a preset covers the base color scheme — explicit tokens you set below override the preset value by value.
Custom Tokens
Custom tokens let you override individual design decisions within the preset. Explicit tokens win over the preset. All token fields are optional.
Color Tokens
Primary path: Accent (Primary Color) and Surface are the only direct user inputs on the primary editor path. All other tokens — on-surface text, hover/active states, border, link, gradient stops — derive automatically with WCAG-AA contrast guaranteed in both light and dark modes. The Advanced panel exposes raw per-region hex overrides for edge cases; any sub-AA override triggers a warn-inline in the editor and CI red-gates the merge.
| Token | What it controls | Format |
|---|---|---|
| Primary Color | Input focus rings, send button, avatar, badges, links | Hex: #7c3aed or #fff |
| Surface (Light) | Chat background in light mode | Hex: #ffffff |
| Surface (Dark) | Chat background in dark mode | Hex: #0a0a0a |
| Input Background | Message composer background | Hex: #f4f4f5 |
| Input Border | Message composer border | Hex: #e4e4e7 |
| Placeholder Text | Composer placeholder text colour | Hex: #a1a1aa |
Bubble Tokens
Configure user and assistant message bubbles independently:
| Token | Options |
|---|---|
| Background | Hex color |
| Text | Hex color |
| Radius | none / sm / md / lg / xl |
Example — brand-matched bubbles:
User bubble: bg #0052CC, text #ffffff, radius xl
Assistant bubble: bg #f4f4f5, text #18181b, radius xlLayout Tokens
| Token | Options | Default |
|---|---|---|
| Global Radius | none / sm / md / lg / xl | preset value |
| Density | compact / comfortable / spacious | comfortable |
| Font Family | See allowlist below | Inter |
Font Family allowlist (only these values are accepted):
Inter · system-ui · Roboto · Open Sans · Lato
Montserrat · Poppins · Source Sans 3 · Nunito · DM Sans
Lora · Playfair Display · JetBrains MonoHeader Tokens
| Token | Description |
|---|---|
| Header Background | Hex override for the chat header bar |
| Header Text | Hex colour for the agent name and text in the header bar |
Background Pattern
Add subtle decorative patterns to the chat background (Controls panel → Background pattern).
Pattern Types
| Pattern | Description |
|---|---|
| None | Solid background color, no pattern |
| Dots | Repeating dot grid |
| Grid | Subtle grid lines |
| Waves | Flowing wave pattern |
| Circles | Overlapping circles |
| Stripes | Diagonal stripes |
| Hexagons | Honeycomb pattern |
Intensity Levels
| Intensity | Opacity Range |
|---|---|
| Subtle | 5-10% |
| Medium | 15-25% |
| Strong | 30-40% |
Use Theme Color
- On: Pattern uses the primary color token
- Off: Pattern uses neutral gray tones
Welcome Experience
Configure how users are greeted when they first open the chat. Preview it with the Welcome surface tab in the toolbar.
These are theme-level defaults. Each agent can override them individually in the agent's Chat Experience tab.
Agent Greeting
First message from AI (appears automatically):
| Field | Description |
|---|---|
| Show Greeting Message | Display AI greeting with typewriter effect |
| Greeting Text | The message the agent "types" when chat starts |
Empty State
What users see before sending first message:
| Field | Description |
|---|---|
| Title | Heading when no messages exist |
| Description | Subtitle in empty state |
| Welcome Image | Icon or image URL for empty state |
Interface & Behavior Defaults
Control behavior defaults for chat interface elements (Settings drawer → Behaviour). Each agent using this theme can override these per-field in its Chat Experience configuration.
Behavior Defaults
| Setting | Description | Default |
|---|---|---|
| Show Header | Display top navigation header | On |
| Show New Chat in Nav | Show "new chat" action in navigation | On |
Note: The conversation sidebar is an owner-authenticated-only feature and is not configurable here. Internal pages that mount the owner's chat hardcode
:show-sidebar="true"directly.
Prompts
Help users start conversations with clickable suggestions.
These are theme-level defaults. Each agent can override them individually in the agent's Chat Experience tab.
Suggested Prompts
Clickable prompts shown in empty state (before first message):
Each prompt has:
- Icon: Visual identifier (e.g.,
i-heroicons-shopping-cart) - Title: Short label (e.g., "Track Order")
- Text: Full prompt sent to AI (e.g., "Where is my order?")
Follow-Up Prompts
Suggestions shown after AI's first response:
| Field | Description | Default |
|---|---|---|
| Enable Follow-Ups | Show suggestions after first response | Off |
| Title | Section heading | "Try asking..." |
| Max Visible | Number of prompts to show | 3 |
Configuration Presets
Quick-start templates for common use cases. Presets emit v2 {branding, defaults} bundles — they set visual branding and behavior defaults. Content (greeting, welcome modal text, suggested prompts) is not part of a preset; it lives in each agent's configuration.
Available Presets
| Preset | Description |
|---|---|
| Minimal | Clean, simple interface — basic chat, no extras |
| Standard | Balanced interface — header on, suggested prompts defaults on |
| Full Featured | All configurable options enabled — header, model selection, follow-up prompts |
| Showcase | Demonstration-ready setup — visible header, auto-connect, follow-up prompts on |
| Embeddable | Optimized for website embedding — minimal chrome, no header |
Applying a Preset:
- Click "Load Preset" dropdown
- Select preset
- Configuration updates automatically
- Customize further as needed
Behavior Settings
Advanced configuration options (set in the Settings drawer → Behaviour — listed here for reference).
| Setting | Description | Default |
|---|---|---|
| Auto Connect | Automatically establish chat connection | On |
| Enable Model Selection | Allow users to switch AI models | Off |
| Max Message Length | Character limit for user messages. Configurable via agent chat_ui.maxMessageLength → theme defaults.maxMessageLength → component default (4000) | 4000 |
File uploads/attachments are not a theme setting — they're a plain per-agent capability toggled in the agent form's Data Collection section (or via MCP). See Chat Attachments for the upload UX and the wizard guardrail that keeps agent instructions honest about this setting.
Using Themes with Agents
Assigning a Theme
- Edit an agent (
/gnosaris/[id]/edit) - Go to Publication section
- Select a chat theme from dropdown
- Save agent
The theme applies to:
- Public chat URL (
/chat/[agent_identifier]) - Embedded widgets
- Password-protected chats
Default Theme
Set a theme as default to auto-apply to new agents:
- Edit theme or check "Set as Default" when creating
- All new agents use this theme automatically
- Existing agents keep their current theme
- Only one theme can be default at a time
Multiple Agents, One Theme
Apply the same theme to multiple agents for consistent brand identity:
Theme: "Company Support Style"
- Preset: Blue
- Primary color: #0052CC
- Font: Inter
- Density: comfortable
Applied to: Sales Agent, Support Agent, Onboarding Agent
Each agent controls: greeting, welcome modal text, suggested prompts, header visibilityTheme Management
Duplicating Themes
Create variations of existing themes:
- Click Duplicate on any theme
- Enter new name (e.g., "Summer Theme - Variant")
- New theme created with all settings copied
- Edit as needed
Deleting Themes
Cannot delete themes currently assigned to agents.
- Unassign theme from all agents first
- Click Delete on theme
- Type theme name to confirm
- Theme permanently removed
Setting/Clearing Default
Set as Default:
- Click "Set as Default" action
- Previous default theme loses default status
- New agents use this theme automatically
Clear Default:
- Click "Clear Default" on current default theme
- No default theme (new agents have no theme until assigned)
Legacy Theme Upgrade
Themes created before v2 show an upgrade banner in the editor. Editing and saving any field upgrades the theme to the v2 schema automatically. The theme continues working as-before until you save.
Live Preview
The Preview in the centre of the editor is the live preview — every change is applied to a real <GnosariChat> instance in real time, so what you see is exactly what visitors get on /chat and in the embedded widget.
Preview Features
- Color tokens applied to all elements as you set them
- Background pattern rendered
- Welcome modal appearance (Welcome surface tab)
- Empty state with title and description
- Message bubble styling (user and assistant), seeded with a demo conversation
- Device-width preview (desktop / tablet / mobile) and light / dark switching from the toolbar
Tips & Best Practices
Color Psychology
Professional/Corporate → Blue, Indigo, Cyan
Creative/Artistic → Purple, Violet, Fuchsia
Eco-Friendly/Natural → Green, Emerald, Forest
Energetic/Fun → Orange, Amber, Sunset
Calming/Wellness → Teal, Lavender, Mint
Luxury/Premium → Gold, Rose, CoralBrand Matching
For exact brand colors, go beyond the preset:
- Pick the closest preset as a base
- Override
colorPrimarywith your exact hex - Set
userBubble.bgto match your brand color - Set
fontFamilyto your brand font (if in the allowlist)
A preset alone sets the base palette; custom tokens give per-element precision.
Pattern Selection
Minimal/Professional → None or Subtle Dots
Playful/Casual → Medium Circles or Waves
Technical/Modern → Grid or Hexagons
Traditional → Subtle StripesPrompt Writing
Write effective suggested prompts:
Good:
- "Track my order"
- "How do I return an item?"
- "What are your hours?"
Avoid:
- "Click here"
- "Help" (too vague)
- "asdfasdfasdf" (test data left in)Troubleshooting
Preview Not Updating
The preview updates live as you change any Controls panel field. If it looks stuck:
- Check you're editing in the right Controls panel section — Brand, Shape & type, Background pattern, or the Advanced accordion (the per-region hex overrides live there, collapsed by default)
- Make sure the Controls panel field actually committed (the unsaved-changes dot on Save should appear)
- Use the Reset demo conversation button (preview header) to re-seed the transcript, or hard-reload the page
- Clear browser cache
Theme Won't Save
Solutions:
- Fill all required fields (Name)
- Check for validation errors (red borders)
- Ensure unique identifier (not used by another theme)
Theme Not Appearing on Agent
Solutions:
- Verify agent access level is Public or Password Protected
- Check agent is using correct chat theme ID
- Clear browser cache and reload chat page
- Ensure theme is not deleted
What's Next?
- Chat Attachments: Let visitors attach an image or PDF to a message
- Chat Sidebar: Implement global floating chat widget
- Widget Embedding: Embed chat on external websites with theme styling
- Agent Publication: Configure agents to use your custom themes