Theme and customization

Every chat space has one published theme: a closed JSON document that decides how the chat page looks, which features it offers, how large attachments may be, and what the interface says. A theme is data only. There is no CSS, HTML or script in it, and the validator rejects any key it does not know.

The lifecycle

In the console, the identity app's Chat tab has a live editor: every change is validated as you type, the preview beside it renders the real chat page with demo channels and a demo actor (it never touches your relay), and a pause saves the draft. Publish and history are buttons on the same screen.

buzz.space.enable publishes the default Orkestia theme, so a new space always has one.

A theme document

A document may be partial. Anything you leave out keeps the default.

{
  "brand": {"display_name": "Acme Support", "logo_url": "https://example.com/logo.png"},
  "appearance": {"color_scheme": "system"},
  "tokens": {
    "color": {"primary": "#0f766e", "bubble_self": "#0f766e"},
    "radius": {"bubble": 12},
    "density": "comfortable"
  },
  "layout": {"mode": "full"},
  "features": {"member_channel_create": true, "read_receipts": true, "missed_message_emails": true},
  "media": {
    "max_bytes": 10485760,
    "max_per_message": 4,
    "allowed_types": ["image/png", "image/jpeg", "application/pdf"],
    "allow_in_private_channels": false
  },
  "copy": {"locale": "en", "strings": {"composer.placeholder": "Ask the team or mention an assistant"}}
}

start_workflow("buzz.theme.save-draft", {"space_uuid": "<space uuid>", "document": { ... }})
start_workflow("buzz.theme.publish", {"space_uuid": "<space uuid>"})

Sections

Contrast below WCAG AA (4.5 to 1) on the text and bubble pairs is a warning in the editor, not a rejection.

Feature flags

The chat page also shows an actor's progress line, its tool trace and its quick replies. Those are on by default and are not theme flags today.

Three flags are enforced by the platform

member_channel_create, member_channel_join and missed_message_emails are read on the server from the published theme. With the flag off, the matching workflows refuse with buzz_feature_disabled: <flag>, so the page can hide the control and the console shows why.

Attachment limits (media)

A space may only make a limit smaller. The type list is deliberately short and has no wildcards: SVG, archives and executables are not allowed (see Limits).

These limits are what the chat page enforces before it uploads, and what buzz.session.issue reports back to the client. The relay itself only applies its own, much larger, global ceilings.

Beyond the theme

Ask your AI assistant

Read the published theme of my chat space with data.buzz.theme.get and summarize the brand, colors and which feature flags are off.

Validate this theme with buzz.theme.validate and list every error and contrast warning: <paste JSON>.

Change my chat's primary color to #0f766e and turn on member_channel_create. Save it as a draft, show me the diff, and publish only after I confirm.

Roll my chat theme back to version 3 with buzz.theme.rollback.

For AI agents