Themes configuration

config.json on the DIAL Chat Themes service defines every theme users can pick in DIAL Chat, the colors of each theme, and the logos and favicon Chat shows. This reference describes the format DIAL Chat 1.x reads. It is for platform engineers who brand a DIAL deployment; it assumes you know the DIAL Chat Themes service.

File format

{
  "themes": [
    {
      "id": "light",
      "displayName": "Light",
      "colors": {
        "bg-layer-base": "#F5F7FA",
        "text-primary": "#161B2D"
      }
    },
    {
      "id": "dark",
      "displayName": "Dark",
      "colors": {
        "bg-layer-base": "#0C101D",
        "text-primary": "#F3F4F6"
      }
    }
  ],
  "images": {
    "chat-logo-light": "logo-light.svg",
    "chat-logo-dark": "logo-dark.svg",
    "chat-favicon": "favicon.png"
  }
}

Field	Description
`themes[].id`	The theme ID, in kebab case. Overlay hosts select a theme by this ID.
`themes[].displayName`	The label in the theme picker, for IDs other than `light` and `dark`.
`themes[].colors`	Color tokens, as hex values. See Colors.
`images`	Image file names, shared by every theme. See Logos and favicon.

Colors

Chat applies each entry in colors as a CSS custom property on the <html> element: bg-layer-base becomes --bg-layer-base. Do not write the -- prefix.

Keys are not validated. A misspelled key loads without error and changes nothing.
Omitted keys fall back to light values. A key a theme leaves out takes Chat's built-in light value, so a dark theme that sets only some tokens renders with light patches. Start a new theme from a complete one.
Fonts are not themeable. theme-font in colors has no visible effect in Chat 1.x.

Color tokens

These are the tokens Chat 1.x reads; anything else in colors is inert.

Surfaces

bg-layer-sunken   bg-layer-base     bg-layer-raised
bg-backdrop       bg-error          bg-warning
bg-info           bg-success        bg-entity-icon

bg-entity-icon is the plate behind model and agent icons. Many vendor logos are a dark glyph on a transparent background, so a dark theme should set it to a light value.

Controls

bg-control-accent               bg-control-accent-hover
bg-control-accent-alpha         bg-control-accent-alpha-hover
bg-control-accent-alpha-active
bg-control-neutral              bg-control-neutral-default
bg-control-neutral-hover-muted  bg-control-neutral-hover-strong
bg-control-neutral-active       bg-control-inverted
bg-control-error                bg-control-error-hover
bg-control-error-active         bg-control-error-alpha-hover
bg-control-error-alpha-active
bg-control-disable-primary      bg-control-disable-secondary
bg-gradient-1                   bg-gradient-1-hover
bg-gradient-1-active            bg-gradient-2
bg-gradient-2-hover             bg-gradient-2-active

The bg-gradient-* stops paint the accent gradient behind primary buttons and under the selected tab.

Decorative fills

bg-visual-blue      bg-visual-green-1   bg-visual-green-2
bg-visual-brown     bg-visual-red       bg-visual-violet-1
bg-visual-violet-2

Text

text-primary       text-secondary       text-tertiary
text-accent
text-error         text-warning         text-warning-icon
text-info          text-success
text-control-permanent        text-control-inverted
text-control-accent-hover     text-control-accent-active
text-control-disable-primary  text-control-disable-secondary
text-visual-blue     text-visual-brown-1   text-visual-brown-2
text-visual-green-1  text-visual-green-2   text-visual-green-3
text-visual-red      text-visual-violet-1  text-visual-violet-2

Strokes

stroke-primary      stroke-secondary     stroke-tertiary
stroke-error        stroke-error-alpha   stroke-warning
stroke-info         stroke-success       stroke-accent
stroke-accent-alpha stroke-default       stroke-focus
stroke-accent-focus stroke-gradient-1    stroke-gradient-2
stroke-control-disable-primary

Stroke widths are fixed and not themeable.

Shadows

shadow-xs-1  shadow-xs-2  shadow-sm-1  shadow-sm-2  shadow-md-1  shadow-md-2  shadow-lg

Renamed tokens

The DIAL UI Kit 0.14 renamed several tokens. The old names are not read anywhere, so a theme that still uses them renders the built-in light value for each.

Old token	Use now
`bg-control-disable`	`bg-control-disable-primary`
`bg-control-neutral-hover`	`bg-control-neutral-hover-muted`
`text-control-disable-alpha`, `text-control-disable-beta`	`text-control-disable-primary`, `text-control-disable-secondary`
`text-control-blue-hover`, `text-control-blue-active`	`text-control-accent-hover`, `text-control-accent-active`
`bg-control-accent-gradient-from`, `-to`	`bg-gradient-1`, `bg-gradient-2`
`stroke-control-accent-gradient-from`, `-to`	`stroke-gradient-1`, `stroke-gradient-2`
`stroke-focus-black`	`stroke-focus`
`stroke-focus-blue`	`stroke-accent-focus`
`stroke-hover-alpha`	Removed; move its value to `stroke-accent-alpha`

Theme IDs and the picker

Users pick a theme in Settings → Preferences. The picker offers every theme in the file; light and dark always come first, and the others follow in file order.

Themes in the file	The picker shows
`light` and `dark`	Light, Dark, System
`light`, `dark`, and `brand-night`	Light, Dark, Brand Night, System
`light` and `brand-night`	Light, Brand Night
One theme or none	No picker

System follows the operating system's color scheme and is offered only when both light and dark exist.
Labels for light, dark, and System are translated. Other themes use their displayName, which is not translated.
The choice is stored in the browser, per user and device. A user who never chose gets light, whatever the file lists first.

An overlay host can set the theme by ID with the theme option; see Chat Overlay API.

Logos and favicon

DIAL Chat 1.x reads three fields of images:

Field	Used for
`chat-logo-light`	The header logo while the active theme is not `dark`
`chat-logo-dark`	The header logo while the active theme is `dark`
`chat-favicon`	The browser tab favicon, the brand icon on the Sign In page, and the navigation icon. SVG, or a 32 × 32 PNG.

Values are file names on the themes service, fetched through Chat's image proxy, so they can contain only letters, digits, -, _, and ..
The logos are shared by every theme: a custom theme other than dark shows chat-logo-light.
An SVG favicon does not render in older Safari releases; use a PNG if they matter. Scripts inside an SVG never run.

Other clients read their own fields from the same file: DIAL Admin reads admin-logo-light, admin-logo-dark, and admin-favicon, and Model Garden reads model-garden-logo-light, model-garden-logo-dark, and model-garden-favicon.

Fields from the legacy Chat

The default config.json still carries fields for the legacy Chat 0.x, so one themes service can serve both:

Chat 1.x accepts and ignores themes[].app-logo, images.favicon, images.default-model, and images.default-addon.
The legacy color tokens, such as bg-layer-0 to bg-layer-4 and the bg-auth-layer-* sign-in colors, have no effect in Chat 1.x.

To move a legacy theme to Chat 1.x, follow the token mapping in DIAL Chat's Theme Customization guide.

File format​

Colors​

Color tokens​

Renamed tokens​

Theme IDs and the picker​

Logos and favicon​

Fields from the legacy Chat​

Further reading​