Widget theming: CSS tokens and parts

The widget’s appearance is driven by CSS custom properties on its host element. Three layers feed the same variables, and the precedence is simple: your page’s CSS on #sa-widget > the page’s ShukaiConfig.theme > the owner’s theme in the panel > the built-in defaults. A page’s ShukaiConfig.theme, if set, replaces the owner’s theme as a whole — it does not merge token by token (Configuration). The panel is a friendly front end to what you could also set in CSS.

In the panel: the colours are on Widget → Appearance → Brand & colours (Widget settings). This page is the same in CSS and code.

#sa-widget {
  --sa-primary: #e11d48;
  --sa-launcher-radius: 16px;
  --sa-font: "Inter", sans-serif;
}

Set the variables on #sa-widget, not on :root — the host’s all: initial does not reset custom properties, but the orb’s slot variables default to initial and read only from the host.

The theme tokens

In ShukaiConfig.theme and in the panel the token is written without the prefix ({ "launcher-radius": "16px" }); unknown tokens are ignored, and a value is rejected if it contains ;, {, }, <, >, a backslash, url(, expression, javascript: or @import, or runs past 200 characters. Page CSS has no such limit — it is your page.

The orb’s variables

The orb’s body colour is voiceOrbColor (or the primary), drawn through a derived palette per state. Page CSS may set, beyond the theme tokens:

• --sa-orb-<state> and --sa-orb-<state>-ink for the twelve states (idle, listening, thinking, speaking, dormant, acting, consent, happy, confused, muted, offline, raised);
• the skin’s slots, --sa-orb-<skin>-<slot> (Launcher and skins); Robot 2.0 keeps its older names --sa-orb-face, --sa-orb-eye, --sa-orb-mouth;
• --sa-orb-mark — the ink of the ? / ! badge and the raised hand; page CSS only, not a theme token.

Never set the *-auto variables: auto-contrast is computed once at mount from the served colours. If you override the visor or the eyes from page CSS, set both — an auto-picked partner is not re-derived for a colour JavaScript cannot see.

::part() for everything the tokens do not reach

Every piece of the widget’s UI carries a part name, so a page can restyle it the ordinary way. A page’s ::part() rule beats any normal declaration inside the shadow root.

#sa-widget::part(companion-bubble) {
  box-shadow: none;
}
#sa-widget::part(nav-suggestion) {
  border-radius: 4px;
}

One exception: on touch devices the widget forces its inputs to 16 px !important (to stop iOS zooming on focus), so ::part(companion-composer-input) { font-size: 14px } loses there.

Custom CSS from the panel

Widget.custom_css is set through the management API only — the panel has no field for it — and is appended last inside the shadow root, so it wins ties with the widget’s own rules. It can never touch the host page. Two things about it: a page’s ::part() rule still beats it, and the right-to-left padding rules are more specific than a plain selector, so .sa-bubble { padding: … } is ignored for Arabic and Hebrew visitors unless written as .root[data-dir="rtl"] .sa-bubble (Languages and RTL).