Panel appearance

The Appearance page sets where the panel docks on your storefront, how it opens, and the colours of the conversation panel a shopper chats in: on your hosted page, in the embedded panel and in the Playground. Open Appearance in the sidebar, right under Agents. It belongs to the active site, at /dashboard/sites/{siteId}/appearance, and applies to every agent of that site.

You don't need to touch it. A colour you leave alone follows a default rule worked out from your site's brand identity, so a branded panel already looks right. Use this page when one part of the panel should differ from what your brand gives it, such as a darker visitor bubble or outlined action buttons.

The page doesn't set the font, the logo or the four brand colours: they stay on the Brand tab of your site settings, linked from the page's description.

Position and behaviourCopy Anchor Link

The first card, Position and behaviour, sets two things for the panel the web tag opens on your storefront. They don't apply to your hosted page or to the Playground, which have no storefront around them.

• Panel side: Right (the default) or Left, the edge of the screen the panel docks to and slides in from.
• Display mode:
  • Alongside the page (the default): the page stays visible and usable, and the shopper can scroll it while chatting. A click or a scroll on the page never closes the panel; the shopper closes it with the ✕ or Escape.
  • Focus on the chat: the page is dimmed and can't scroll while the panel is open. A click on the dimmed page closes the panel, and that click doesn't reach the page.

On a screen 640 px wide or narrower, the panel fills the whole width and the page behind it is locked whichever mode you choose.

Wherever the page is locked, screen readers and the keyboard also treat the panel as modal: the rest of the page can't be reached until the panel closes. In Alongside the page on a wider screen, the page stays reachable. See Keyboard and screen readers.

Choose a side or a mode, then click Save. The change reaches your storefront on its next page load: there's nothing to change in the snippet you pasted, and nothing to publish. A panel a shopper already has open keeps its side until the page reloads. See Choose which side the panel slides in from for what the tag does with these settings.

Set a colourCopy Anchor Link

1. Open Appearance in the sidebar.
2. Find the group, then the colour. The rarely changed ones sit under Advanced in their card.
3. Open the colour's menu and choose a source (see Colour sources).
4. Check the preview, then click Save at the top right.

Save stays off until you change something, a colour or a setting of the Position and behaviour card. A saved colour is live at once on your hosted page, in the embed and in the Playground, from the panel's next load. There is no version to publish and no confirmation dialog. Each save that changes something is recorded in Admin activity: a colour change with the groups it changed, and a side or opening mode change as "Panel side or opening mode changed".

The colour groupsCopy Anchor Link

The page has one card per group. A colour marked "can be None" also offers None: a transparent fill or no border.

A text colour, a hover colour, a link colour and the panel background never take None: text must show, and the panel stays opaque over your page.

Colour sourcesCopy Anchor Link

Each field names the colour it uses on its closed control, with a swatch: "Secondary · default" while it follows its default, "#F4D7C6 · custom" for a colour you picked, or the name of a brand colour or None you chose. The hover default reads "Automatic shade · default" and the suggestions border default "Neutral line · default". Open, the menu groups the sources:

• Default: the colour's default rule. The field keeps following it as your brand changes.
• My brand: Primary, Secondary, Font or Background, each with its hex code. The field takes that brand colour and follows it when you change your brand. A brand colour equal to the default is left out, since the Default row already shows it.
• Other: None on a colour that can go without, the custom colour in use when there is one, and Custom colour…. A border always offers None, so you can rule out a border the default would add. A fill whose default is already None, such as the suggestions fill, doesn't offer it, since Default gives the same result. A custom colour stays as you set it when your brand changes.

Pick a custom colourCopy Anchor Link

Custom colour… opens a picker under the field, starting from the colour in use. Drag in the colour area or type a hex code; where the browser supports it, an eyedropper picks a colour from your screen. The field and the preview follow your pick as you go.

• Apply (the check mark, or Enter in the hex box) keeps the colour. If the colour you apply equals the field's default, the field stays at Default and keeps following its rule, so opening the picker and applying without a change doesn't pin the colour.
• Cancel (the cross), Escape or a click outside puts back the value the field had before the picker opened, and the preview with it.

Nothing is stored until you click Save.

Default coloursCopy Anchor Link

A colour you leave at Default follows this rule. "Readable" means your font colour when it reaches 4.5:1 contrast on what it sits on, and black or white otherwise. A text on a fill set to None is measured against the panel background, since the panel shows through.

When a hover colour is set, the text on a hovered button follows the text rule again on that hover colour, unless you set the text colour yourself.

A hovered suggestion whose fill is on Default or None takes the panel's muted surface, a light neutral tint of the background. Once you set a fill, a hovered suggestion keeps its colours with a light automatic shade of that fill. Either way its text stays readable, and there is no field for it.

A field at its default shows a short line under it when its rule adapted: a text that switched to black or white to stay readable, and the action buttons border, which appears only when the fill blends into the panel.

Contrast warningCopy Anchor Link

When you choose a colour (a brand colour or a custom colour, checked live while you pick), the field checks it against what it sits on and warns below the WCAG 2.2 AA threshold:

• a text colour (action text, visitor text, highlights text, assistant text, links, suggestions text) against its fill, or the panel background when that fill is None: 4.5:1, the threshold for text;
• a border (action buttons, suggestions), the action buttons fill and the action buttons hover against the panel background: 3:1, the threshold for icons, borders and other non-text elements, since these draw the button's edge and its selected state.

The warning gives the measured ratio and a recommended colour: the nearest colour, moving toward black (or white on a dark backdrop), that reaches the threshold on the same backdrop. For example, "Contrast 3.2:1, below the 4.5:1 recommended for text. Recommended colour: #767676." It never blocks: you can still save, and the colour is applied as you set it.

The Panel background isn't checked: the panel's plain text (question titles, the message field) follows it, your font colour when it reaches 4.5:1 on it, and black or white otherwise. The other colours aren't checked while they follow their default: the text defaults switch to black or white on their own when your font colour reads poorly. The suggestions border default is the exception to the 3:1 rule above: it keeps the faint outline suggestions always had, which can sit under 3:1 on a light background. A border colour you set yourself is checked against 3:1 as usual. The visitor, highlights and suggestions fills aren't checked on their own: the text colours on them carry the check.

The previewCopy Anchor Link

Beside the fields, the Preview is a frozen schematic of the panel with your unsaved colours. It has four zones: Visitor (the shopper's message), Action buttons (an action card and the send button), Highlights and Suggestions. Point at a zone to see its colour group's name. The zones are painted by the same colour code as the live panel, so the colours match what shoppers get once you save.

The preview is for colours only. It draws no assistant text and no links, nothing in it can be clicked or focused, and it has no agent behind it. The hover colours don't appear in it. To check the colours in a real conversation, save, then open the Playground.

Who can change itCopy Anchor Link

Anyone who can see agents (Agents: View or Agents: Edit) can open the page. Changing the colours, the side or the opening mode needs Sites: Edit, since they are site settings like the brand. Without it, the fields and the Position and behaviour choices are read-only and there is no Save button. A member without either agents permission sees a restricted-access notice instead.

Over the API and MCPCopy Anchor Link

The same settings are three fields of the site: panelColors, panelPosition (right or left) and panelBackdrop (false for Alongside the page, true for Focus on the chat).

• REST: read them on Get a site and List sites, and set them with Update a site. panelColors replaces the stored colours whole, and null clears them all. panelPosition and panelBackdrop each take a value and refuse null; leave one out to keep it as it is.
• MCP: list_sites returns them, and the set_site_panel_appearance tool sets any of them, with Sites: Edit.

A colour is a brand reference (primary, secondary, text for the font colour, background), a #rrggbb hex, or none on fills and borders. A colour left out follows its default.

{
  "panelPosition": "left",
  "panelBackdrop": false,
  "panelColors": {
    "visitor": { "fill": "#2b2b2b", "text": "#ffffff" },
    "suggestions": { "fill": "none", "border": "primary" }
  }
}