Widget theming

The default widget looks reasonable on any site, but you'll want it to match your brand. Every theme setting lives under Bot settings → Theme, with a live preview next to the form.

Theme tab

Open any bot → Settings → Theme. The tab splits into two columns: controls on the left, a live iframe preview on the right. Changes render in the preview within 150ms — we debounce edits to keep the iframe responsive.

The preview uses an HMAC-signed token scoped to your workspace, so what you see is exactly what a visitor will see, including auth-gated features.

Colors

Primary color — 6-digit hex value (#rrggbb). Drives the chat bubble, send button, and accent highlights. Default #6366f1.
Radius — 0–24px slider. Applied to the bubble, message balloons, and input. 0 = sharp corners, 24 = pill-shaped.
Position — left or right. Anchors the bubble to the bottom corner of the page.

Pick a primary that has enough contrast against both light and dark backgrounds — the widget reuses it for foreground text on the send button and accent elements.

Theme mode

light — fixed light theme.
dark — fixed dark theme.
auto — follows the visitor's prefers-color-scheme.

Auto is the default and handles both OS-level and site-level dark mode without extra config.

Font stack

Pick one of four system-font stacks for widget text. All four use the visitor's OS fonts — no network request, no web-font download, no licensing concerns.

system-sans (default) — native sans-serif stack (San Francisco, Segoe UI, Roboto, …).
system-serif — native serif stack.
system-mono — native monospace stack.
system-rounded — native rounded stack where available (SF Rounded on macOS/iOS, falls back to the sans stack elsewhere).

Custom web fonts aren't supported today. If brand consistency needs a specific typeface, pair system-sans with a tight primary color and let the rest of the page set typographic tone.

Quick reply chips

Quick replies are pre-defined prompts a visitor can tap to start a conversation — "Pricing?", "Book a demo", "How do I cancel?".

Up to 5 chips per bot.
Each chip is a single string — tapping it drops that exact text into the composer so the visitor can send or edit it. Max 200 characters per chip. Duplicates are stripped on save.
Chips render above the input on first open and disappear once the visitor sends anything.

Use them to reduce the blank-input barrier. Good chip copy is verb-first and under 4 words.

Custom CSS variables

Override any of ten safelisted CSS variables via the JSON field in the theme tab. Values are validated against a safe-character regex (no url(), no @import, no javascript:) and capped at 50 characters each.

{
  "--mv-primary": "#6366f1",
  "--mv-primary-hover": "#4f46e5",
  "--mv-bg": "#0b0d10",
  "--mv-surface": "#12161b",
  "--mv-text": "#e6e8ea",
  "--mv-text-muted": "#7c848e",
  "--mv-border": "#1e232a",
  "--mv-shadow": "0 12px 32px rgba(0, 0, 0, 0.35)",
  "--mv-radius": "16px",
  "--mv-font-family": "system-ui, sans-serif"
}

The full allowlist is: --mv-primary, --mv-primary-hover, --mv-bg, --mv-surface, --mv-text, --mv-text-muted, --mv-border, --mv-shadow, --mv-radius, --mv-font-family. Unknown keys are rejected on save. These cascade into the widget's shadow DOM — other CSS variables are intentionally locked because we change them between versions.

For deeper customization (layout, new elements, removing branding), Scale includes white-label widget support. Contact us for the details.

Live preview

The preview iframe uses the same runtime bundle your visitors load, mounted with an HMAC-signed token:

Token carries workspace_id + bot_id + a short expiry.
HMAC prevents preview-token tampering.
Debounce: 150ms between the last edit and the preview postMessage that applies it.

This means the preview won't thrash as you drag the radius slider — you see the final value, not every intermediate tick.

Open the playground from the preview footer to test full conversations against your themed bot. Retrieval and theming are orthogonal — if chunks look wrong, that's a knowledge issue, not theming. See Knowledge sources.

Brand assets

Logo URL — shown in the widget header. SVG or PNG, square-ish aspect ratio, served over HTTPS.
Avatar URL — shown next to bot messages. 64×64 recommended.

Assets are fetched client-side from the URL you provide — we don't re-host them. Use your CDN. If the URL fails to load, the widget falls back to initials.

Applying changes

Theme edits render in the live preview immediately, but aren't stored until you click Save changes on the settings form. Once saved, the next visitor to load your embed gets the new theme as soon as the CDN cache refreshes; to force an immediate refresh, hard-reload the host page.

Best practices

Start with the defaults. Most brands only need to change the primary color.
Test light and dark. The auto mode is only as good as both sides of the theme.
Keep chip labels short and action-oriented.
Save your CSS variable overrides somewhere outside Mevichat — a design token file in your repo is ideal.