Theming

Erato supports extensive theming capabilities to match your brand identity. You can customize colors, logos, and assistant avatars.

Theme Configuration

Themes are configured in the backend configuration file (erato.toml) and consist of:

Theme Directory - A folder containing all theme assets
Theme Configuration - JSON file defining colors and styles
Static Assets - Logos and avatar images

Setting Up a Custom Theme

Configure the theme name in erato.toml:


[frontend]
theme = "my-company"

Create the theme directory in the frontend bundle:


public/custom-theme/my-company/
├── theme.json              # Theme configuration
├── logo.svg                # Application logo (light mode)
├── logo-dark.svg           # Application logo (dark mode, optional)
├── assistant-avatar.svg    # Assistant avatar (optional)
└── locales/                # Custom translations (optional)
    ├── en/
    │   └── messages.po
    └── de/
        └── messages.po

Theme Structure

theme.json

The theme.json file defines the color scheme for both light and dark modes:


{
  "name": "My Company Theme",
  "theme": {
    "light": {
      "colors": {
        "background": {
          "primary": "#ffffff",
          "secondary": "#f5f5f5"
        },
        "foreground": {
          "primary": "#000000",
          "accent": "#0066cc"
        },
        "avatar": {
          "assistant": {
            "background": "#0066cc",
            "foreground": "#ffffff"
          },
          "user": {
            "background": "#666666",
            "foreground": "#ffffff"
          }
        }
      }
    },
    "dark": {
      "colors": {
        "background": {
          "primary": "#1a1a1a",
          "secondary": "#2d2d2d"
        },
        "foreground": {
          "primary": "#ffffff",
          "accent": "#4d94ff"
        },
        "avatar": {
          "assistant": {
            "background": "#4d94ff",
            "foreground": "#ffffff"
          },
          "user": {
            "background": "#888888",
            "foreground": "#ffffff"
          }
        }
      }
    }
  }
}

Custom Logos

Place logo files in your theme directory:

logo.svg - Main application logo (required)
logo-dark.svg - Dark mode logo (optional, falls back to logo.svg)

Custom Language Files

You can customize translation strings to match your brand’s tone and terminology. This is particularly useful for:

Changing the assistant name (e.g., “Your Company KI Assistent”)
Choosing formal vs. informal forms of address (e.g., “Du” vs. “Sie” in German)
Adapting welcome screen messages

Directory Structure

Create language files in your theme directory:


public/custom-theme/my-company/
├── theme.json
├── logo.svg
├── assistant-avatar.svg
└── locales/
    ├── en/
    │   └── messages.po
    ├── de/
    │   └── messages.po
    └── fr/
        └── messages.po

Available Branding Translation IDs

These translation IDs are designed for brand customization and have stable IDs guaranteed across versions:

ID	Purpose	Default (en)	Default (de)
`branding.assistant_name`	The name/label shown for AI messages	”Assistant"	"Assistent”
`branding.user_form_of_address`	Generic label for user messages (fallback when no user name available)	“You"	"Du”
`branding.welcomeScreen.title`	Welcome screen heading	”Welcome to AI Assistant"	"Willkommen beim KI-Assistenten”
`branding.welcomeScreen.subtitle`	Welcome screen subheading	”Get expert help…"	"Erhalten Sie Expertenunterstützung…”
`branding.welcomeScreen.description`	Welcome screen description text	”Ask questions…"	"Stellen Sie Fragen…”
`branding.page_title_suffix`	Browser tab title suffix	”LLM Chat"	""

Example: Custom Translations

messages.po (for German):


msgid ""
msgstr ""
"Language: de\n"
 
#. js-lingui-explicit-id
#: src/components/ui/Chat/ChatMessage.tsx
msgid "branding.assistant_name"
msgstr "Your Company KI Assistent"
 
#. js-lingui-explicit-id
#: src/components/ui/Chat/ChatMessage.tsx
msgid "branding.user_form_of_address"
msgstr "Sie"

Note: The .po files are the source of truth. In development, you can edit both, but only .po files should be version controlled.

For technical details on how the translation override system works, see Internationalization (i18n).

User Display Name Priority

When displaying user messages, the system follows this priority:

User’s actual name (from userProfile.name) - e.g., “Daniel Schmidt”
Form of address (branding.user_form_of_address) - e.g., “Du”, “Sie”, “You”

This allows personalization when user identity is known, while maintaining your brand’s preferred formality level for anonymous users.

Custom Assistant Avatar

You can customize the assistant’s profile picture by adding an assistant-avatar.svg (or other image format) to your theme directory.

Using the Theme Directory

When you have a theme configured, place the avatar file in:


public/custom-theme/my-company/assistant-avatar.svg

The avatar will be automatically detected and used.

Using Additional Environment Configuration

You can also override the assistant avatar path using the additional_environment configuration:


[frontend]
theme = "my-company"
additional_environment = { "THEME_ASSISTANT_AVATAR_PATH" = "/custom-theme/my-company/assistant-avatar.svg" }

Supported Image Formats

SVG (recommended for scalability and quality)
PNG, JPG, or other browser-supported image formats

Fallback Behavior

If no custom avatar is provided, the assistant will display with:

A colored circle using the theme’s avatar.assistant.background color
The letter “A” in the avatar.assistant.foreground color

Environment Variables

You can also configure theme assets using environment variables (useful for development):

VITE_CUSTOMER_NAME - Theme directory name
VITE_LOGO_PATH - Override logo path (light mode)
VITE_LOGO_DARK_PATH - Override logo path (dark mode)
VITE_ASSISTANT_AVATAR_PATH - Override assistant avatar path

Deployment

Docker

Mount your theme directory into the container:


docker run -v ./my-theme:/app/public/custom-theme/my-company erato-image

Kubernetes

Use a ConfigMap to store your theme:


apiVersion: v1
kind: ConfigMap
metadata:
  name: erato-theme
data:
  theme.json: |
    {
      "name": "My Theme",
      "theme": { ... }
    }
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: erato
spec:
  template:
    spec:
      containers:
        - name: erato
          volumeMounts:
            - name: theme
              mountPath: /app/public/custom-theme/my-company
      volumes:
        - name: theme
          configMap:
            name: erato-theme

For logos and avatars (binary files), use an init container or a PersistentVolume.