Configure tenant-branded chatbot appearance

Aura Home separates customer integration from visual configuration. The SDK can request an approved theme, while the dashboard Appearance Editor lets operators publish safe color, typography, logo, stylesheet, and mode settings for the selected runtime.

SDK Theme Request

Use theme.id to ask the runtime for a named profile such as cadisa. The runtime applies it only when SDK theme override is enabled and the id is present in the tenant-local allowlist.

const aura = AuraHome.init({
  container: "#aura-home",
  baseUrl: "https://your-aura-home-runtime.example/",
  theme: {
    id: "cadisa",
    mode: "system",
    cssVariables: {
      "--color-brand-primary": "#2F6FED",
      "--color-brand-primary-hover": "#1F56C6",
      "--color-brand-accent": "#8AB4F8",
      "--aura-home-loader-background": "#f5f9ff",
      "--aura-home-loader-text": "#0b1f4d",
      "--aura-chat-header-background": "#0b1f4d",
      "--aura-chat-title-font-family": "'Montserrat', system-ui, sans-serif",
      "--aura-card-accent": "#2F6FED",
      "--aura-card-action-background": "#2F6FED",
      "--aura-card-focus-ring": "#8AB4F8"
    },
    stylesheetUrl: "https://customer.example/aura-home-theme.css"
  }
});

Tenant isolation is selected by baseUrl, not by theme.id. Treat theme ids as visual hints only.

Dashboard Appearance Editor

The dashboard Settings modal includes an Appearance workspace for the selected agent connection. It edits that connection's tenant-local runtime, so operators can manage visual profiles without changing customer portal code.

Choose built-in or published profiles, including default and cadisa.
Use the Default action to return the active runtime to the built-in default profile.
Edit theme id, display name, logo URL, stylesheet URL, and visual mode.
Switch Light, Dark, or System and see the live preview update immediately.
Edit allowlisted brand, surface, message, composer, result-card, and typography tokens.
Adjust typography per shell, title, message, input, and button elements.
Review result-card preview tabs, renderer catalog metadata, and the active theme revision.
Save drafts, publish the active theme, or move controlled JSON between environments.

Safety Model

Appearance payloads are structured configuration, not raw page content. The dashboard never sends raw HTML or scripts, and the runtime remains responsible for safe URL validation, CSS-token allowlisting, and fallback behavior.

Field	Allowed Use	Not Allowed
`theme.id`	Request an approved visual profile.	Tenant identity, routing, auth, or billing.
`cssVariables`	Colors, loader styling, spacing, and typography tokens from the runtime allowlist.	Credentials, user data, JavaScript, or raw HTML.
`cardTokens`	Result-card surface, border, accent, action, and focus-ring styling resolved by the runtime.	Unsupported renderer behavior, scripts, or data-routing decisions.
`stylesheetUrl`	Optional HTTPS stylesheet for approved customer refinements.	Untrusted scripts, mixed-content URLs, or secret-bearing URLs.
`mode`	`light`, `dark`, or `system` preview and runtime preference.	Security or tenant selection.

Result Cards and Runtime Metadata

SDK 1.2 exposes the resolved appearance payload so customer support teams can see which visual profile, result-card settings, renderer catalog, and published theme revision the runtime actually applied.

const resolved = aura.getResolvedAppearance();

aura.on("appearanceResolved", (event) => {
  const metadata = event.payload;
  console.log(metadata?.features?.resultCardsEnabled);
  console.log(metadata?.rendererCatalog);
  console.log(metadata?.cardTokens);
  console.log(metadata?.themeRevision);
});

Metadata	Use
`features.resultCardsEnabled`	Confirms whether enriched property/result cards are active.
`rendererCatalog`	Lists public renderer capabilities available to the embedded runtime.
`cardTokens`	Captures card accent, action, border, surface, and focus states after fallback resolution.
`themeRevision`	Identifies the published dashboard appearance revision used by the runtime.

Cadisa Canonical Profile

The current Cadisa profile uses a deep navy header, Cadisa blue primary actions, a lighter blue accent for focus and secondary emphasis, white and pale-blue surfaces for calm contrast, and readable Inter/Segoe UI typography with optional Montserrat for title treatments.

Operational Fallback

Runtime environment variables can provide the initial or fallback theme. Once the dashboard publishes an appearance profile, the published theme takes priority over matching environment values for that runtime.