# WD: Widget design

Track WD (owner decision, 2026-11-15). This document is WD-1: the audit of the chatbot widget and its Appearance settings, what comparable widgets do, and the proposal. WD-2 is the clickable prototype in Storybook ("Widget design"). Both wait for the owner's approval; nothing in the production widget changes before it.

Status: **design approved 2026-11-15** by the owner ("all approved"): the research, the prototype and every open question with its recommendation below. Built in WD-3 to WD-11.

## The brief (owner, 2026-11-15, condensed)

The Appearance settings (brand colours, theme, colour style, the colours of single parts) look outdated next to the redesigned admin. The widget should feel premium in its colours and in every function, and leave room for voice: visitors talk to the chatbot and it answers aloud.

## Audit of today's widget

Looked at on `development` on 2026-11-15 in WordPress Playground (WordPress 7.1.4, PHP 8.3, Twenty Twenty-Five, networking off, Pro forced through the e2e option). The chat and history routes were answered in the browser with invented sample content, so the real widget rendered every state without a provider. The screenshots are in Storybook under "Widget design/Today (audit)" (files in `tests/storybook/widget-design/audit/`); the ids below refer to them.

### How it is built

- **Mount:** `#kimaai-chatbot` in the page's own DOM. No iframe and no shadow root (checked in the browser). One stylesheet, `build/chatbot.css`, from `src/chatbot/index.scss` (1,871 lines, 47 `!important`) and `src/global/chatbotColorPalette.css`.
- **Theme pipeline:** `ChatbotTheme::normalize()` (PHP) resolves the stored `appearance.theme` (version 2) and `ChatbotTheme::cssVars()` writes custom properties inline on the mount; `data-kimaai-mode` and `data-kimaai-style` pick the rules in the stylesheet. Colours are mixed in the browser with `color-mix(in oklch, ...)`; nothing checks contrast.
- **Fonts:** the widget inherits the site's font (DS decision, 2026-11-13). The message field does not: it shows the browser's default monospace, because nothing sets `font: inherit` on the textarea (checked: `monospace` inside a `Manrope` page).
- **Isolation from the theme:** class and id selectors, a few element resets under `:is(#kimaai-chatbot, [data-kimaai-chatbot])`, and `!important` where themes won. A theme's element rules for `button`, `ul` or `a` still reach the widget (19).

### Surfaces and states

| Surface                    | Today                                                                                                                           | What looks dated, and why                                                                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launcher (01, 16)          | A robot picture in a pale 72 px circle                                                                                          | The picture is the product's mascot, not the site's brand; the pale tint makes it look disabled; no label option                                        |
| Attention popover (02, 13) | Outline buttons stacked above a speech bubble with an arrow                                                                     | Two visual languages; the buttons float without a container; no name or avatar                                                                          |
| Panel and header (03)      | Brand-coloured header with "Talk to our AI agent:" above the name, full screen and close                                        | Title with a colon reads like a form label; the header is the loudest part of the widget                                                                |
| Welcome (03)               | One small greeting bubble, outline quick actions, a four-row text field                                                         | No sense of who answers or what to ask; most of the panel is empty                                                                                      |
| Thinking (04)              | "KimaAI is thinking…" and a dark timer in the send button                                                                       | Says the product's name, not what happens; a timer reads as a slow system                                                                               |
| Answer and sources (05)    | Tinted bubble; sources as an underlined numbered list, related pages as a boxed card; Copy inside the bubble; thumbs outside it | Three styles in one answer; actions are split across two places                                                                                         |
| Error (06)                 | A red line of text                                                                                                              | No retry and no way to a person                                                                                                                         |
| Feedback (07)              | A text field after thumbs down                                                                                                  | No reasons to pick; the field is in the default monospace                                                                                               |
| Renderables (08)           | Booking card, product HTML as underlined links, a ticket box                                                                    | Each renderable has its own look; WooCommerce product HTML depends on the theme                                                                         |
| Consent (09)               | The composer is replaced by a text and a full-width button                                                                      | Starters stay clickable but do nothing visible; a dead end on phones                                                                                    |
| Handoff (10)               | A ghost "Talk to a person" button above the composer                                                                            | Always visible, takes a row on every message                                                                                                            |
| Rating at the end (11)     | A modal over the chat after three answers                                                                                       | Its comment field runs past the dialog's edge                                                                                                           |
| Dark (12, 13)              | Night surfaces                                                                                                                  | The header and the body merge; the launcher becomes a dark circle                                                                                       |
| Styles (14, 15)            | Classic, Minimalist, Glossy, Neon                                                                                               | Glossy looks like Classic; Minimalist and Neon replace the site's brand colour with their own (`#3C3C62`, `#7C3AED`) unless the colour preset is Custom |
| Phone (17)                 | Full screen                                                                                                                     | The greeting slides under the header; the field takes a quarter of the screen                                                                           |
| Right to left (20)         | Mirrors correctly, Yekan for Persian                                                                                            | Fine; keep                                                                                                                                              |
| Ask AI dialog (21)         | A plain list on a grey scrim                                                                                                    | Not the widget's look; no answer preview                                                                                                                |
| Search answer (22)         | A small box with one button                                                                                                     | Fine in function, plain in look                                                                                                                         |

### Measured contrast (WCAG 2.2 AA asks 4.5:1 for text)

| Where                                            | Colours                | Ratio          |
| ------------------------------------------------ | ---------------------- | -------------- |
| Quick action text, Classic light                 | `#6767FD` on `#FFFFFF` | 4.26:1, fails  |
| Quick action text, Neon light                    | `#C084FC` on `#FAFAFA` | 2.53:1, fails  |
| Quick action text, Minimalist light              | `#A9A9C8` on `#F5F7FF` | 2.13:1, fails  |
| Header text with a custom primary `#F5C518` (18) | `#FFFFFF` on `#F5C518` | 1.63:1, fails  |
| Header, Classic light                            | `#FFFFFF` on `#5250E6` | 5.76:1, passes |

Nothing stops a site owner from choosing a combination that fails; the admin shows no warning.

### Appearance settings today

Four cards on the Appearance page (AD-6): General, Branding, Messages, Attention popover. 31 settings; the colour field alone holds 23 values. Screenshots: 31a, 31b.

| Card              | Setting (key under `chatbot.appearance`)                                                                                                                                              | What it controls                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| General           | `isEnable`                                                                                                                                                                            | Floating widget on every page, or only where the block or shortcode is                                                 |
| General           | `position`                                                                                                                                                                            | Left or right                                                                                                          |
| General           | `offset.bottom`, `offset.right`                                                                                                                                                       | Distances from the edges (Pro today)                                                                                   |
| Branding          | `icon`, `customIconUrl`                                                                                                                                                               | Launcher and header picture: nine bundled pictures, or a URL (Pro)                                                     |
| Branding          | `showHeaderIcon`                                                                                                                                                                      | The picture in the header                                                                                              |
| Branding          | `theme.mode`                                                                                                                                                                          | Light, dark or system                                                                                                  |
| Branding          | `theme.style`                                                                                                                                                                         | Classic, Minimalist, Glossy or Neon: radius, shadow, and (with the Default preset) their own colours                   |
| Branding          | `theme.colorPreset`                                                                                                                                                                   | Default or Custom; Custom means the seed colours below are your own                                                    |
| Branding          | `theme.colors.primary`, `.accent`, `.surface`, `.neutral`                                                                                                                             | Seed colours for light mode                                                                                            |
| Branding          | `theme.darkColors.accent`, `.surface`, `.neutral`                                                                                                                                     | Seed colours for dark mode; only editable while the mode is Dark, not with System                                      |
| Branding          | `theme.advanced.*` (13 keys)                                                                                                                                                          | Body, header, AI message, user message, input and footer background and text, and the border; one value for both modes |
| Messages          | `chatTitle`, `chatName`                                                                                                                                                               | The two header lines                                                                                                   |
| Messages          | `greeting`, `placeholder`                                                                                                                                                             | First message and field hint                                                                                           |
| Messages          | `aiDisclosure`, `aiDisclosureText`                                                                                                                                                    | The AI notice (EU AI Act Art. 50)                                                                                      |
| Messages          | `showMessageCopyButton`                                                                                                                                                               | Copy under answers                                                                                                     |
| Messages          | `aiAvatarIcon`, `aiAvatarUrl`, `userAvatarIcon`, `userAvatarUrl`                                                                                                                      | Pictures next to messages (custom URL is Pro)                                                                          |
| Messages          | `disclaimer`                                                                                                                                                                          | A line under the chat                                                                                                  |
| Messages          | `poweredBy`                                                                                                                                                                           | "Powered by KimaAI" link, off by default (WordPress.org guideline 10)                                                  |
| Attention popover | `attentionEnabled`, `attentionMessage`, `attentionDelay`, `attentionSound`, `attentionShowQuickActions` (Pro), `attentionShowOnceWhenClickOnClose`, `attentionShowOnceWhenInteracted` | The popover beside the launcher                                                                                        |

**What is wrong with the model, not only the look:**

1. **Seven seed colours and thirteen overrides** come before any sense of the result. "Accent", "surface" and "neutral" are designer words; the result of a change is only visible in the preview.
2. **A style changes the colours.** With the Default preset, picking Minimalist or Neon replaces the brand colour; with Custom, the style's colours are ignored. The same select does two different things.
3. **Dark colours are hidden** unless the mode is Dark, so a site on System cannot set them.
4. **Overrides ignore the mode.** A white "body background" set for light also paints the dark widget.
5. **No contrast rule** (see the table above).
6. Leftovers: `offset` has a `defaultValue` of 50 px in the field and a default of 24 px in the schema; the colour field's help texts use US spelling and an em dash.

## What comparable widgets do

From their public documentation, read on 2026-11-15. "Not found" means the documentation did not say.

| Product                          | Palette                                                                                      | Light / dark                                             | Shapes and font                                                                         | Launcher                                      | Settings screen                                | Branding removal                                                  |
| -------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- |
| Intercom Messenger (Fin)         | Separate colours: home background, action (primary) colour; per mode                         | Light, Dark, Match system (dark mode since October 2025) | Font from a fixed list (Inter, Poppins, Montserrat, Roboto, Open Sans, Lato, Noto Sans) | Side, spacing, custom image                   | Live preview on the right, "Save and set live" | Brand colours and logo editable only on Advanced and Expert plans |
| Crisp                            | A colour theme, or custom base colours from which it generates lighter and darker variants   | Not found for the chatbox                                | Not found                                                                               | Position offsets                              | Live preview                                   | "We run on Crisp" removable on the paid Plus plan                 |
| Zendesk messaging                | Primary, message and action colours; the SDK has about 25 keys                               | Not found (a 2025 community request asks for it)         | Radius 0 to 20 px                                                                       | Square, circle or custom; optional text label | Admin Center preview                           | Zendesk logo removable only on Suite Enterprise                   |
| Chatbase                         | Header, user message and button colours; newer surface with a tinted greyscale and an accent | Light or dark                                            | Font from a list; width small, medium, large                                            | Left or right                                 | "Chat interface" section                       | "Powered by" removal as a paid add-on                             |
| Voiceflow                        | **One colour**, 10 shades generated by HSL interpolation                                     | Not found                                                | `fontFamily`, `inherit` uses the site's font                                            | Icon or label, image, side, spacing           | Not found                                      | Not found                                                         |
| Botpress Webchat                 | **One colour** generates the theme                                                           | Light or dark                                            | Radius scale, variant solid or soft, header solid or glass, font from a list            | Bubble or custom element                      | Live preview on the right, "Publish"           | Not confirmed                                                     |
| Kapa.ai                          | **One brand colour** for interactive elements; surfaces independent of it                    | Light, dark, auto, or follow the site's own dark class   | Font family, size, scale factor                                                         | Hide it and use your own button               | Attributes, no screen                          | Not found                                                         |
| ElevenLabs agents widget (voice) | Separate colours; an orb avatar from two colours                                             | Not found                                                | Border and button radius                                                                | Variants tiny, compact, full, expandable      | Not found                                      | `disable_banner` flag                                             |

Only Zendesk documents a contrast rule: its "on" colours default to black or white "for accessibility". None documents an automatic contrast check. OpenAI's ChatKit, as a reference for presets rather than settings screens, offers radius (pill, round, soft, sharp) and density (compact, normal, spacious) as named steps.

**Voice in web widgets:** ElevenLabs' widget has voice-only, voice and text, and chat modes, labels for listening and speaking, a mute button, a transcript, and terms shown before the call starts. Voiceflow's web chat has dictation, voice output and a hands-free voice mode that "behaves like a phone call". Intercom's Fin Voice works only in phone workflows, not in the web Messenger.

**Isolation:** only Zendesk documents it: its widget renders inside an iframe, so the site's CSS cannot style it. Kapa, Voiceflow and Botpress document class names for custom CSS instead.

**What KimaAI takes from this:** one brand colour with a derived palette (Voiceflow, Botpress, Kapa), named style presets instead of free values (Botpress, ChatKit), light, dark and automatic (Intercom, Kapa), the live preview on the right (Intercom, Botpress, and already KimaAI's admin), and a launcher with an optional label (Zendesk, Voiceflow). What none of them documents and KimaAI adds: a contrast rule that holds for any brand colour, and a report in the settings of what it changed.

## Proposal

### Theme model

Three decisions make the whole look; everything else is optional.

1. **Brand colour**, one hex value. Suggestions from the active theme's palette (`theme.json`) sit under the picker.
2. **Style**, one of four presets. A style sets shapes, depth and where the brand colour shows; it never sets colours of its own.
3. **Colour mode**: Light, Dark or Match the site (stored as `auto`): light or dark as the site's own colours, read from the page the widget sits on (owner, WD-11; it first followed each visitor's `prefers-color-scheme`, which put a dark widget on sites that have no dark mode).

| Style       | Header                                                           | Answers                                     | Corners (panel / message / control) | Depth             | Replaces      |
| ----------- | ---------------------------------------------------------------- | ------------------------------------------- | ----------------------------------- | ----------------- | ------------- |
| **Calm**    | Neutral, the avatar in brand colour                              | Plain text with a small avatar, like a page | 20 / 18 / 12 px                     | Soft shadow       | (new default) |
| **Bold**    | Brand colour with a soft highlight                               | Tinted bubbles                              | 20 / 18 / 12 px                     | Soft shadow       | Classic       |
| **Glass**   | Transparent over a frosted panel with a glow of the brand colour | Tinted bubbles                              | 24 / 20 / 14 px                     | Brand-tinted glow | Glossy, Neon  |
| **Minimal** | Neutral, hairline border                                         | Plain text                                  | 10 / 10 / 8 px                      | None, a border    | Minimalist    |

**The palette is derived** (prototype: `tests/storybook/widget-design/theme.js`; to be ported to PHP for the first paint and kept equal by shared test fixtures in Jest and PHPUnit):

- **Neutrals** (panel, raised surfaces, borders, text, secondary text) lean slightly towards the brand's hue in OKLCH, with chroma capped so a warm brand does not turn dark surfaces brown.
- **Fills** (the visitor's messages, the send and primary buttons): the brand colour itself. Text on a fill is white or near-black, whichever has more contrast (the Zendesk rule); for any colour one of the two reaches 4.5:1.
- **A fill that melts into the panel** (under 3:1, WCAG 1.4.11): light mode keeps the brand colour and adds a 1 px edge in a darker shade of it; dark mode lifts the fill's lightness.
- **The brand as text or icon** (links, outlines, citations): its lightness is moved (same hue and chroma) until it reaches 4.5:1 on every surface it sits on.
- **Header in Bold and the launcher:** the exact brand colour, with white or near-black on it.

**Checked for every colour, light and dark:** text, secondary text, header text, answers, the visitor's messages, buttons and links at 4.5:1; buttons on the panel (or their edge) and input borders at 3:1. The engine was run on the six sample colours of the prototype (KimaAI action `#5250E6`, forest green `#1F7A4D`, coral `#E4572E`, sun yellow `#F5C518`, sand `#EFE6D2`, navy `#0B1B3F`) and on black, in all four styles: every check passes in both modes ("Widget design/Theme/Contrast rules on six brand colours").

**The settings say what moved.** Under the colour mode: "Readable in light and dark" when the colour is used as it is, or "with small adjustments" and the list, for example "Dark: links and icons `#5250E6` → `#7079FF`".

**Advanced, behind a disclosure:** corners (sharp, rounded, round), density (comfortable, compact), font, and the colours of single parts, **set separately for light and dark**, each with its contrast ratio next to it. An override may fail the contrast rule; it then shows its ratio in red. The derived colours never fail.

### Typography

- **Default: the site's font**, as decided in DS (2026-11-13): the widget looks like part of the site, and nothing is downloaded. The form controls inherit it too (fixes today's monospace field).
- **Options under Advanced:** System (for sites with a decorative or script font) and Geist (the admin's font, OFL, 28 KB for Latin; loaded only when chosen).
- Persian keeps Yekan (`:lang(fa)`), other Arabic-script languages Vazirmatn, as in the admin.
- Sizes: 15 px body (14 px compact), 22 px welcome heading, 12.5 px secondary text, tabular figures for times and prices.

### Radius, density and motion

- Radius from the style, scaled by the Corners setting (sharp × 0.45, round × 1.3).
- Density compact: 14 px text and spacing × 0.78.
- Motion from the brand tokens (120, 200 and 360 ms): the panel rises from the launcher, messages fade in, the thinking line shimmers, the voice orb breathes. With `prefers-reduced-motion` all of it stops and every state is still said in words.

### The redesigned surfaces

Shown in "Widget design/Widget", each as its own story, light and dark, left to right and Persian, desktop and phone.

| Surface           | Design                                                                                                                                                                                         |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launcher          | The brand colour with a speech-bubble mark (or today's picture, or the site's logo); circle, rounded square, or with a label ("Ask Kima"); a chevron while open                                |
| Attention popover | One card: avatar, name, the message, two suggestions as chips, dismiss                                                                                                                         |
| Header            | Avatar, name, one line under it ("AI assistant · answers from example-shop.test"), a ⋯ menu (new conversation, voice, talk to a person, larger window, download transcript) and close          |
| Welcome           | A large avatar, a heading ("Hi, I’m Kima from Example Shop"), one line of text, the quick actions as full-width rows with icons                                                                |
| Thinking          | What is happening, in the site's words: "Searching example-shop.test ✓, Reading 3 pages…"                                                                                                      |
| Streaming         | A caret; the send button turns into Stop                                                                                                                                                       |
| Answer            | Text with numbered citations; sources as chips under it; one action row: copy, read aloud, helpful, not helpful                                                                                |
| Source            | Opens inside the panel: breadcrumb, title, the quoted passage with the matching words marked, Open the page                                                                                    |
| Error             | A card with the reason, Try again and Talk to a person                                                                                                                                         |
| Not helpful       | Reasons as chips, an optional comment, Send                                                                                                                                                    |
| Consent           | A card above the field; the field and the suggestions wait until it is accepted                                                                                                                |
| Handoff           | In the menu, and as a card when it happens ("Connecting you to our team")                                                                                                                      |
| Rating at the end | A sheet from the bottom of the panel with five stars and a comment, not a modal over the conversation                                                                                          |
| Renderables       | One card shape for all: lead form, booking with days and times, product cards in a row, choices as radio cards, the site's own form (Contact Form 7, Gravity Forms), ticket with its reference |
| Composer          | One rounded field that grows; empty: dictation and Voice; with text: Send; while answering: Stop. AI notice and the site's note below                                                          |
| Phone             | Full screen with safe areas; the same layout                                                                                                                                                   |
| Ask AI dialog     | A command-palette dialog: "Ask AI: …" first, pages below, the answer with sources in the dialog, Continue in chat                                                                              |
| Search answer     | A card above the results with a brand glow; idle, writing (skeleton), the answer with sources, Continue in chat, helpful                                                                       |

### The Appearance page

In the admin's design (AD), beside the live preview ("Widget design/Appearance settings"). The preview shows the closed launcher, the welcome, an answer or voice, on desktop or phone, for a visitor in light or dark mode.

1. **Theme:** brand colour (picker, hex, the theme's palette, KimaAI default), style (four drawn cards in the chosen colour), colour mode, and the contrast report.
2. **Launcher:** icon (mark, today's picture, your logo, more icons), shape, label, position, distances.
3. **Header and name:** name, the line under it, avatar (mark, initial, picture, upload).
4. **Welcome and messages:** heading, text, suggestions (link to Quick actions), placeholder, AI notice, answer actions, the note under the chat, "Powered by" link.
5. **Voice** (planned, VC): voice conversations and dictation, switched off until VC builds them.
6. **Attention popover:** as today.
7. **Advanced** (closed): corners, density, font, colours of single parts per mode.

### How stored settings carry over

A migration writes the new model to a **new key, `appearance.look`**, and leaves `appearance.theme` (version 2) as it is, so a downgrade to 1.5.x still shows the old look. The export and import carry both; an import of an old file runs `LegacyAppearance` and then this mapping. The old key is removed two minor releases later. Nothing is asked of the site owner.

The mapping reads the version 2 theme through `ChatbotTheme::normalize()` first, so a style's own colours resolve as they do today.

| Today                                                                                                                               | New                                                                                        | Rule                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `theme.mode` light, dark, system                                                                                                    | `look.mode` light, dark, auto                                                              | One to one                                                                                                                                          |
| `theme.style` classic, minimalist, glossy, neon                                                                                     | `look.style` bold; today's style in `look.carried.style`                                   | Every existing site is Bold (owner decision 2: none changes its look on its own); today's components keep the old style's shapes until WD-5 to WD-8 |
| `theme.colors.primary` (resolved)                                                                                                   | `look.brand`                                                                               | So a Neon site keeps `#7C3AED`, a Minimalist site `#3C3C62`                                                                                         |
| `theme.colorPreset`                                                                                                                 | (none)                                                                                     | Custom only meant "my seed colours"; the values below carry it                                                                                      |
| `theme.colors.surface`, `.neutral`, `.accent`, when Custom and not the style's own                                                  | `look.parts.light.panelBackground`, `.text`, `.links`                                      | Kept as overrides                                                                                                                                   |
| `theme.darkColors.*`, same rule                                                                                                     | `look.parts.dark.*`                                                                        |                                                                                                                                                     |
| Today's colours as the stylesheet resolved them: light surface, text, answers, field, footer, border; dark the same plus the header | `look.parts.light.*` where the site showed light, `look.parts.dark.*` where it showed dark | So the site looks as before (owner, WD-3 review); a site that never showed dark gets the engine's dark                                              |
| Every colour the carry-over writes                                                                                                  | Also in `look.carried.parts`                                                               | Carried colours keep rendering on a free site while unchanged ("nothing they set is lost"); a changed one is Pro                                    |
| `theme.advanced.headerBackground`, or else `bodyBackground`                                                                         | `look.parts.<mode>.headerBackground`                                                       | Today "body" paints the header unless the header has its own colour                                                                                 |
| `theme.advanced.headerText`, or else `bodyText`                                                                                     | `look.parts.<mode>.headerText`                                                             |                                                                                                                                                     |
| `theme.advanced.aiMessage*`, `userMessage*`, `input*`, `footer*`, `border`                                                          | `look.parts.<mode>.answer*`, `visitor*`, `input*`, `footer*`, `border`                     | `<mode>`: the modes the site shows today (light, dark, or both for system), because today one value paints both                                     |
| `icon`, `customIconUrl`, `showHeaderIcon`                                                                                           | Unchanged                                                                                  | A site keeps its picture on the launcher and in the header                                                                                          |
| `aiAvatarIcon`, `aiAvatarUrl`                                                                                                       | Unchanged                                                                                  | "None" keeps answers without an avatar                                                                                                              |
| `userAvatarIcon`, `userAvatarUrl`                                                                                                   | Unchanged, not offered to new sites                                                        | Shown when a site set one                                                                                                                           |
| `chatName`                                                                                                                          | Name                                                                                       |                                                                                                                                                     |
| `chatTitle`                                                                                                                         | The line under the name                                                                    | The old default "Talk to our AI agent:" (in the site's language) becomes the new default "AI assistant"                                             |
| `greeting`                                                                                                                          | Welcome text                                                                               | The new welcome heading starts empty on existing sites                                                                                              |
| `showMessageCopyButton`                                                                                                             | Answer actions                                                                             |                                                                                                                                                     |
| `isEnable`, `position`, `offset`, `placeholder`, `aiDisclosure*`, `disclaimer`, `poweredBy`, `attention*`                           | Unchanged                                                                                  |                                                                                                                                                     |

New sites get Calm, the KimaAI mark, the brand default `#5250E6` and Light. The filters `kimaai_chatbot_theme_styles` and `kimaai_chatbot_color_presets` keep working (a filtered style maps to Bold with its primary colour as the brand) and become deprecated through `apply_filters_deprecated`, which HK documents.

### Front-end robustness

Today a theme's element rules reach the widget (19: a simulated set of common theme rules for buttons, lists and links turned the copy button into a black block and indented the sources), and the field shows monospace on every site.

**Proposal: a shadow root.** The floating widget, the inline block and the Ask AI dialog render inside an open shadow root on their mount element, with the widget's stylesheet adopted into it. The site's CSS then cannot select anything inside; only inherited properties cross (font family, colour, direction), and the widget sets every one of them on its root except the font family, which it inherits on purpose.

- **Exceptions in the light DOM, through a slot:** the site's own forms (Contact Form 7, Gravity Forms) and WooCommerce product HTML, which need the site's styles and scripts. Product cards should move to data plus the widget's own card; the HTML stays as the fallback.
- **Fonts:** `@font-face` rules are registered in the document, not in the shadow root.
- **React:** portals and events work in a shadow root since React 17; dialogs portal into the shadow root, not into `body`.
- **Tests:** the e2e suite runs the widget on Twenty Twenty-Five, the classic e2e theme and a fixture of hostile theme CSS, and compares computed styles.
- **Without a shadow root** (if the owner prefers): a reset of every element inside the widget at higher specificity plus `font: inherit` on controls. It helps but does not stop `!important` rules from themes.

### Accessibility

- The panel is a labelled region; opening moves focus to the field, Escape closes and returns focus to the launcher. Menus are menus, the rating sheet and the source view are dialogs inside the panel.
- Streaming answers are announced once complete, not word by word; the thinking line is a polite status.
- Targets of 32 to 36 px (WCAG 2.5.8 asks for 24), focus ring in the derived link colour at 2 px, no state shown by colour alone (the voice states have words, ratings have numbers).
- Contrast: the engine's rules above; forced-colours mode keeps borders.
- Reflow: the phone layout from 440 px down, readable at 200 % zoom.
- Right to left with logical properties; technical values (URLs, references, times) stay left to right.
- Voice: captions always on screen, the transcript in the chat afterwards, no microphone before an explicit start, every control reachable by keyboard.

### Voice-ready layout

Designed now, built in VC ("Widget design/Voice mode").

- **Entry points:** in the empty field, a microphone for dictation (the visitor's speech becomes text in the field) and a Voice button for a spoken conversation; the ⋯ menu has "Voice conversation"; every answer has Read aloud.
- **Before the microphone opens:** what happens (when the microphone is on, that speech is turned into text by the site's AI provider and the audio is not stored, that the transcript stays in the chat), Start voice conversation or Type instead, and the privacy link. VC decides the wording with the consent research.
- **States:** connecting, listening (red dot, live caption of the visitor's words), thinking (the question stays on screen), speaking (the answer as a caption, "Start talking to interrupt"), microphone off. An orb in the brand colour shows the state; the words say it too.
- **Controls:** Transcript, Mute, End, Type. End returns to the chat with a "Voice conversation · 1 min" divider and each turn marked "Spoken".
- **Errors:** microphone blocked (how to allow it, Try again, Type instead), not available in this browser (Type instead).
- **Settings:** a Voice card on the Appearance page, switched off and marked Planned until VC.

### Free and Pro

Freemium stays (BM, option b). The look is part of the first impression of the free plugin, so the three decisions are free; what costs money or is specific to brands with strict guidelines is Pro.

| Free                                                                                                | Pro                                                      |
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Brand colour, the four styles, colour mode with Auto, the contrast engine                           | Colours of single parts per mode                         |
| Launcher shape, label, position and **distances** (Pro today; competitors offer them in every plan) | Own logo on the launcher, own avatar (Pro today)         |
| Corners, density, font                                                                              | Suggestions in the attention popover (Pro today)         |
| All texts, the AI notice, the bundled icons, the KimaAI mark                                        | Voice (proposed for VC, because speech costs per minute) |
| The new Ask AI and search answer look (their features keep their own plans)                         | White-label credit in the footer (Pro today)             |

### Open questions for the owner (approved as recommended, 2026-11-15)

| Question                             | Recommendation                                                                                                                                     |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Default style for new sites       | **Calm**: the widget feels part of the site, the brand colour stays where it carries meaning                                                       |
| 2. Existing sites                    | Carry over to **Bold**, the style closest to Classic, so no site changes its look without the owner choosing; the admin offers Calm with one click |
| 3. Default colour mode for new sites | **Light**; Auto offered. A dark widget on a light site looks out of place for visitors with a dark system setting                                  |
| 4. Font                              | **The site's font** (DS decision), with System and Geist under Advanced                                                                            |
| 5. Isolation                         | **Shadow root** with the site's forms in the light DOM                                                                                             |
| 6. Today's robot pictures            | Keep them under "More icons"; the KimaAI mark becomes the default                                                                                  |
| 7. Visitor avatar                    | Not offered to new sites; shown where a site set one                                                                                               |
| 8. Distances from the edges          | **Free**                                                                                                                                           |
| 9. Overrides that fail contrast      | Allowed under Advanced with the ratio in red; the derived colours never fail                                                                       |
| 10. Storage                          | A new key `appearance.look`; `appearance.theme` stays for two minor releases so a downgrade keeps the old look                                     |

### Build items after the approval (WD-3 and later)

1. Theme engine in PHP and JS with shared fixtures, `appearance.look`, the migration and the import path.
2. Shadow root mount and the hostile-CSS e2e fixture.
3. Shell: launcher, popover, panel, header and menu, welcome, phone layout.
4. Conversation and composer: messages, sources and the source view, thinking and streaming, Stop, error, feedback, consent, handoff, rating sheet.
5. Renderables in the shared card.
6. Ask AI dialog and search answer.
7. The Appearance page with the new preview and the contrast report.
8. Voice entry points as hidden placeholders for VC (feature status hidden).

Each with its tests and screenshots in real WordPress, as AD did.

## WD-2: the prototype

Storybook, section "Widget design". Prototype code only (`tests/storybook/widget-design/`); the production widget is unchanged. Sample content is invented (a made-up outdoor shop).

- **Today (audit):** the screenshots above.
- **Widget:** "Clickable (start here)": open the launcher, send or pick a suggestion (thinking, streaming, sources), open a source, rate, use the ⋯ menu, try Voice; the dashed bar switches the style, six brand colours and the mode. Then one story per state, dark, Persian right to left, the styles, the advanced options, and unusual brand colours.
- **Voice mode:** a clickable run and every state.
- **Theme:** the four styles on one colour, light and dark, the unusual colours in every style, and the contrast checks.
- **Ask AI and search answer.**
- **Appearance settings:** the page in the admin's design with the live preview; a very light brand colour shows the contrast report; Advanced and the free plan.

Phones: the widget stories are drawn for 390 px wide screens too.

Published on the AI box Storybook (2026-11-15), 76 stories, among them:

- [Widget: clickable](https://aibox.tailda25c5.ts.net:6443/kimaai/?path=/story/widget-design-widget--clickable)
- [Voice mode: clickable](https://aibox.tailda25c5.ts.net:6443/kimaai/?path=/story/widget-design-voice-mode--clickable)
- [Appearance settings](https://aibox.tailda25c5.ts.net:6443/kimaai/?path=/story/widget-design-appearance-settings--default)
- [Theme: four styles on one colour](https://aibox.tailda25c5.ts.net:6443/kimaai/?path=/story/widget-design-theme--styles) and [contrast rules on six colours](https://aibox.tailda25c5.ts.net:6443/kimaai/?path=/story/widget-design-theme--all-colours)
- [Ask AI and search answer](https://aibox.tailda25c5.ts.net:6443/kimaai/?path=/story/widget-design-ask-ai-and-search-answer--results)
- [Today (audit)](https://aibox.tailda25c5.ts.net:6443/kimaai/?path=/story/widget-design-today-audit--audit)

**Checked:** screenshots of every story at 1440 and 390 px; axe (WCAG 2.0 to 2.2 A and AA rules) reports no violations in the widget on 13 stories (answer, welcome, dark, sun yellow, sand, navy dark, lead form and booking, Persian, Glass, Minimal, not helpful, voice listening, voice intro). The Appearance page is drawn for the desktop admin; the AD prototype's shell has no phone layout.

## Sources

- Intercom: [Set up and customize the Messenger](https://www.intercom.com/help/en/articles/6612589-set-up-and-customize-the-messenger), [Dark mode for Messenger](https://www.intercom.com/changes/en/114292-dark-mode-for-messenger), [Fin Voice in phone workflows](https://www.intercom.com/help/en/articles/12918513-use-fin-voice-in-phone-workflows).
- Crisp: [Change the chatbox colour](https://help.crisp.chat/en/article/how-to-change-the-chatbox-color-1txcz7t/), [Customise the chatbox](https://help.crisp.chat/en/article/how-to-customize-my-chatbox-1hj537j/), [Remove "We run on Crisp"](https://help.crisp.chat/en/article/how-to-remove-we-run-on-crisp-branded-links-dkrg1d/).
- Zendesk: [Name and appearance of the Web Widget](https://support.zendesk.com/hc/en-us/articles/4500747797914-Configuring-the-name-and-appearance-of-the-Web-Widget), [Web Widget colour SDK](https://developer.zendesk.com/documentation/zendesk-web-widget-sdks/sdks/web/client-color/), [Messaging Web Widget cookbook](https://support.zendesk.com/hc/en-us/articles/10292484466330-Messaging-Web-Widget-cookbook), [Dark mode request](https://support.zendesk.com/hc/en-us/community/posts/8913674465434-Dark-mode-for-the-messaging-web-widget).
- Chatbase: [Update agent styles](https://www.chatbase.co/docs/api-reference/v2/agents/update-agent-styles.md), [Chat bubble colours](https://www.chatbase.co/changelog/customize-your-chat-bubble-colors), [Pricing](https://www.chatbase.co/pricing).
- Voiceflow: [Custom web chat styling](https://www.voiceflow.com/docs/documentation/deploy/widget/custom-web-chat-styling.md).
- Botpress: [Configure your webchat](https://www.botpress.com/docs/webchat/get-started/configure-your-webchat), [StylesheetProvider](https://botpress.com/docs/webchat/react-library/components/stylesheet-provider).
- Kapa.ai: [Widget theming](https://docs.kapa.ai/integrations/website-widget/configuration/theming).
- ElevenLabs: [Widget API](https://elevenlabs.io/docs/api-reference/widget/get.md), [Widget customisation](https://elevenlabs.io/docs/eleven-agents/customization/widget.md).
- OpenAI ChatKit: [Theme option](https://openai.github.io/chatkit-js/api/openai/chatkit/type-aliases/themeoption/).
- WCAG 2.2: [1.4.3 Contrast (Minimum)](https://www.w3.org/TR/WCAG22/#contrast-minimum), [1.4.11 Non-text Contrast](https://www.w3.org/TR/WCAG22/#non-text-contrast), [2.5.8 Target Size (Minimum)](https://www.w3.org/TR/WCAG22/#target-size-minimum), [2.3.3 Animation from Interactions](https://www.w3.org/TR/WCAG22/#animation-from-interactions).
- KimaAI: `docs/research/DS-design-system.md` (brand, fonts, dark palette), `docs/research/AD-admin-redesign.md` (admin design, preview, real WordPress pass).

## WD-3: Theme engine (build notes)

**The engine.** `src/global/chatbotLook.js` (JS, the admin's preview) and `app/ChatBot/ChatbotLook.php` (PHP, the variables printed for the widget, the contrast report, the carry-over) are the prototype's `theme.js`, ported. Input: `appearance.look` = brand, style (`calm`, `bold`, `glass`, `minimal`), mode (`light`, `dark`, `auto`), corners (`sharp`, `rounded`, `round`), density (`comfortable`, `compact`), font (`site`, `system`, `geist`) and `parts.light` / `parts.dark`, the colours of single parts (header background and text, panel background, text, links, answer background and text, visitor background and text, message field background and text, footer background and text, border). Output per colour mode (`derive(look, scheme)`): `vars` (the CSS custom properties), `parts` (every part's colour), `checks` (each rule with both colours, the ratio, pass, and `own` when a part colour of the site is involved) and `adjusted` (uses of the brand colour the engine moved, from and to). Additions to the prototype: the parts `links` and `footerBackground` (the carry-over needs them), a footer text check, the part colours of single parts that are not hex are dropped, and the neutral header, plain answers and footer follow a panel colour of the site's own.

**One fixture for both.** `tests/fixtures/chatbot-look.json` holds 31 inputs (the six sample brands and black in Calm, every style on the KimaAI brand, sun yellow in Bold, navy in Minimal, corners, shorthand and invalid values, Pro parts with two failing on purpose) with their expected normalised look, flags, variables, checks and adjustments. `tests/js/global/chatbotLook.test.js` and `tests/unit/ChatBot/ChatbotLookTest.php` both read it; both also check that every derived colour passes for ten brand colours in every style and mode. To keep the two languages equal to the last bit, the JS takes cube roots as PHP does (`x ** (1/3)`, not `Math.cbrt`).

**The seam to the mount (WD-4).** One function, the same in both languages: `lookVars(look, scheme)` / `ChatbotLook::vars($look, $scheme)` returns `{'--kimaai-w-…': value}` for one resolved colour mode, and `lookAttributes(look)` / `ChatbotLook::attributes($look)` the style flags `data-kimaai-mode` (`light`, `dark`, or `system` for Auto, as the stylesheet reads it today), `data-kimaai-style`, `data-kimaai-density`, `data-kimaai-font`.

- Front end: `ChatbotAssets::generateDynamicCss()` prints the variables in the document on `:is(#kimaai-chatbot, [data-kimaai-chatbot]).kimaai-chatbot` (the light or dark set; for Auto the light set and the dark set under `@media (prefers-color-scheme: dark)`), and `themeAttributes()` puts the flags on every chat root. Custom properties inherit into a shadow root, so the shadow mount needs no code for colours: it keeps the host's id or `data-kimaai-chatbot`, the `kimaai-chatbot` class and the flags, and its stylesheet reads the flags with `:host([data-kimaai-…])`. The CSS is attached to the `kimaai-chatbot` style handle; if WD-4 stops printing that stylesheet in the document, it must keep this inline CSS there.
- Admin preview: `ChatbotPreview` calls `lookVars` with the unsaved look and sets the result inline on the preview's root.
- Variables: `--kimaai-w-` + brand, on-brand, accent, accent-edge, on-accent, accent-text, accent-soft, on-accent-soft, bg, raised, sunken, hover, border, border-strong, text, muted, header-bg, header-text, header-muted, answer-bg, answer-text, visitor-bg, visitor-text, input-bg, input-text, footer-bg, footer-text, glow, danger, danger-soft, success, success-soft, r-panel, r-bubble, r-control (the radii already scaled by Corners). Density and font are flags only.

**Today's components keep working.** `src/global/chatbotColorPalette.css` maps the names they read (`--kimaai-chatbot-primary`, `-surface`, `-neutral`, `-accent`, `-link`, the `-default` of header, messages, input, footer, border and code, and the dark mode's `-dark-*-base`) to the engine's variables, with the brand tokens as fallbacks; the seed-and-mix rules per mode are gone, as the engine resolves each mode. The `-override` layer and the filters stay: `kimaai_chatbot_theme_vars` gets the engine's variables per colour mode (new arguments: the look and the mode; the normalised version 2 theme stays the second argument), and old names it sets still win; `kimaai_chatbot_theme` (six colours) works as before. The shapes per style for today's components are keyed on the new style names (Calm and Bold as Classic, Glass as Glossy with a glow of the brand colour, Minimal as Minimalist). The disclaimer line lost its `opacity: 0.8`: on the derived footer text it fell to 3.8:1 (axe), now 4.6:1.

**Settings.** `appearance.look` in `app/Admin/config/chatbot.php`, defaults for new sites: Calm, Light, `#5250e6` (the DS action colour, as the research says), rounded, comfortable, the site's font. `appearance.theme` keeps its schema and values but no field. The existing Appearance page edits the look through `ChatbotThemeField`, now a stand-in with brand colour, style, colour mode, corners, density and font (no part colours; WD-9 builds the page). It keeps stored part colours when it saves. `ChatbotTheme::cssVars()`, `rootAttributes()`, `jsConfig()` and the admin's `chatbotTheme.js` were used only by the old field and preview and are removed; `normalize()` and the styles stay for the carry-over.

**Carry-over.** `LookCarryOver::fromTheme()` maps as the table above. The research's first table sent Glossy and Neon to Glass and Minimalist to Minimal; that is superseded by the owner's decision 2 ("existing sites move to Bold, so none changes its look on its own") and the roadmap's "nothing they set is lost" (lead, WD-3 review), because every style of today had a brand header and brand messages in light mode, which only Bold has. So:

- every site is Bold in its resolved primary (`ChatbotTheme::normalize()`), in the same mode (System to Auto); a style from `kimaai_chatbot_theme_styles` too;
- today's style goes to `look.carried.style`; the root then carries `data-kimaai-legacy-style` (only while the style is Bold), and `chatbotColorPalette.css` gives today's components that style's radius, shadow and overlay, as before, until WD-5 to WD-8 restyle them;
- today's colours as the stylesheet before WD-3 resolved them become colours of single parts, for the modes the site showed: light: the surface (panel, field, footer), the text colour (text, answers, field, footer), answers tinted 7 % with the primary, the border (20 % primary; Neon 65 %; Minimalist 12 % of the text colour); dark: the dark surface and text, header and footer mixed 60 % and answers 45 % with the night border `#2a2a52`, the border 22 % primary, the dark accent as links. `ChatbotLook::mix()` mixes as CSS `color-mix(in oklch)` does. A site that never showed dark gets the engine's dark;
- custom seed colours that are not the style's own, and the overrides of single parts for every mode the site shows, go over them; "body" becomes the header's colour **in light mode only**, because the dark mode's header had its own default and body never painted it. Values that are not hex are dropped;
- everything it writes is also stored in `look.carried.parts`.

Engine-derived colours remain where today's were derived too: the header and visitor fills (the brand), the text on them, secondary text. There the engine's contrast rules apply, which is the only visible difference (see the checks below). It runs:

- in migration `Version2026111510`;
- in the settings' schema upgrade, before the defaults fill the look in (the same place as LegacyAppearance and 2026111304). That covers a downgrade and upgrade: 1.5.x prunes the unknown `look` on its schema upgrade, so the next upgrade carries over the theme as 1.5.x left it (tested);
- in the settings import, after LegacyAppearance, for an export without a look (a newer export keeps its look);
- when the widget renders a stored appearance without a look (`LookCarryOver::look()`), e.g. options written by WP-CLI.

`appearance.theme` is never written.

**A fix on the way.** A 1.5.13 site stores 1.5.13's default theme colours (`#4545f9`, …). `LegacyAppearance` took them for custom colours, so a site with colours from before the theme system lost them on `development` (1.5.13 showed them). It now treats 1.5.13's defaults as defaults too, as 1.5.13 did.

**Free and Pro.** Colours of single parts are Pro: `ChatbotLook::forPlan()` (and `lookForPlan` in the preview) leaves them out at render on a free site; they stay stored. Carried colours are grandfathered: a part whose colour still equals its `look.carried.parts` value renders on a free site; changing it ends that for the part (the stored value no longer matches), and changing it back restores it. The stand-in field lists the stored colours of single parts (all on Pro, the carried ones on free) with Reset (back to the carried colour) and "Use the brand colour" (no colour of its own). It sends every part, an unset one as empty, because a save merges into the stored look and would otherwise keep a removed colour. Everything else is free.

**Checked in Playground** (WordPress latest, PHP 8.3, no networking, chat routes answered in the browser with invented content; shots in the WD-3 shots folder: `before/` on the base commit, `after/` with the first mapping, `after2/` with the owner's decisions, `diff/` the pixels that differ between `before/` and `after2/` in red).

With the owner's decisions (after2), each carried-over site against before, share of the screenshot whose pixels differ by more than 12 of 255 in a channel:

| Scenario                                    | Differs                | What                                                                                                                             |
| ------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Classic light, and at 390 px                | 0.05 %, 0.18 %         | The disclaimer line (opacity removed, 3.8:1 to 4.6:1)                                                                            |
| Classic dark; System with a dark visitor    | 0.05 %                 | The disclaimer line                                                                                                              |
| Minimalist light                            | 0.04 %                 | The disclaimer line                                                                                                              |
| Minimalist dark                             | 0.77 %                 | The visitor's message and the send button: `#3c3c62` melted into the panel (1.7:1); the engine lifts the fill to `#5e5f88` (3:1) |
| Glossy light; Neon light; Neon dark         | 0.04 %, 0.05 %, 0.06 % | The disclaimer line                                                                                                              |
| Custom colours with overrides, Pro and free | 0.05 %                 | The disclaimer line; the free site keeps its carried navy header and coral messages                                              |
| Sun yellow custom                           | 0.28 %                 | The header and message text near-black instead of white (1.6:1)                                                                  |
| New site                                    | (different on purpose) | Calm, Light, `#5250e6`                                                                                                           |

In the admin on a free carried-over site, a carried colour changed to black is stored and the preview and the site show the brand colour there (Pro); Reset gives the carried colour back; "Use the brand colour" stores the part as empty.

With the first mapping (after, superseded):

- Classic light (Bold): looks as before (brand header and messages, tinted answers); the panel is the engine's near-white, the footer text the derived secondary grey.
- Classic dark and System with a dark visitor: the surfaces are the engine's near-neutral dark instead of navy `#15153a`, and the header is the brand (Bold) instead of a dark mix.
- Minimalist (Minimal) and Glossy or Neon (Glass): the brand header goes (Minimal's and Glass's header is neutral; Glass's glow comes with WD-5), Minimal's visitor messages are grey, not the brand.
- Custom colours with overrides, Pro: as before. The same site on the free plan: the navy header and the coral messages fall back to the brand (parts are Pro).
- Sun yellow custom: the header and buttons keep the yellow with near-black text instead of white at 1.6:1.
- New site: Calm, Light, `#5250e6`.
- Also: a classic theme, Persian right to left on a 390 px phone in dark, the admin page (change style, mode and brand, the preview follows, Save stores the look). axe (WCAG 2.0 to 2.2 A and AA) on the open widget: no violations in Bold, Calm, Minimal light, Glass dark, sun yellow and navy.

**Left for others.** The radii, the density and the font flags are emitted but today's components use their old radius per style; WD-5 to WD-8 read `--kimaai-w-*` and the flags. The Geist font loading is WD-4's. The contrast report and the part colours in the admin are WD-9's (`derive()` gives both). The deprecation of `kimaai_chatbot_theme_styles` and `kimaai_chatbot_color_presets` through `apply_filters_deprecated` is not done (HK). The Storybook mocks still set `window.kimaaiAdmin.chatbotTheme`, which nothing reads now.

## WD-4: Shadow root mount (build notes)

Built 2026-11-15 on `wd/shadow`. Looked at in WordPress Playground (the e2e blueprint without networking, a fake chat provider, invented sample content for a made-up outdoor shop) on Twenty Twenty-Five and a classic theme (Georgia, square black buttons), light and dark, left to right and Persian, 1440 and 390 px, the base commit's build next to this one.

- **Every mount renders in a shadow root.** `src/chatbot/index.js` puts each chat root (`#kimaai-chatbot`, and every `[data-kimaai-chatbot]`: the inline chat of the block and the shortcode, the Ask-AI modal's root, the search answer box) into an open shadow root on that root (`attachWidgetRoot`, `src/chatbot/adapters/browser/shadowMount.js`) and renders React into `.kimaai-chatbot-shadow-root` inside it. The root keeps its id, classes and data attributes, so PHP, the blocks and the shortcode print what they printed before.
- **The stylesheet, measured.** `build/chatbot.css` is 70,429 bytes (9.4 KB gzip, 460 rules) and the page keeps loading it: for the fonts, the theme's custom properties on the root and the content in the light DOM. Three ways to get it into the roots:
    - a `<link>` to the same file inside each root: served from the memory cache, but a root renders unstyled until it has loaded, and the rules cannot be adapted to the shadow root;
    - the CSS bundled into the script: no request, but the same 9.4 KB twice on every page;
    - **chosen:** the rules of the page's own `<link id="kimaai-chatbot-css">`, read once through the CSSOM, adapted, and adopted by every root as one constructed stylesheet. No request (the e2e test counts one request for `chatbot.css`), no unstyled frame, 1.3 ms median on the Mac (Chrome, reading, adapting and parsing all rules). When the page has no readable copy (an optimiser combined or deferred it, a CDN on another origin without CORS) the mount fetches `kimaaiChatbot.stylesheetUrl` once; a browser without adoptable stylesheets gets a `<style>` element.
- **Adapting the rules** (`toShadowCss`, `src/chatbot/core/utils/shadowCss.js`): a selector on the chat root, `:is(#kimaai-chatbot, [data-kimaai-chatbot])` with what follows on the same element (`[data-kimaai-mode='dark']`, `.kimaai-chatbot`, `:is(.kimaai-chatbot-inline, ...)`), becomes `:host(...)` with the same condition, and `:root` becomes `:host`. `:host()` adds one class to the weight of every such rule, so the rules win and lose against each other as before: the computed styles of the open chat, the dark mode, the consent box, the classic theme and the inline chat were compared property by property. The one rule keyed on a root class without the root selector (inline and Ask-AI chats in their column) now names the root. New widget CSS (WD-5 to WD-8) can name the root this way, or simply leave it out.
- **The seam with WD-3 (theme engine).** The theme reaches the widget today in two ways, both kept:
    - `ChatbotAssets::generateDynamicCss()` prints `ChatbotTheme::cssVars()` (after `kimaai_chatbot_theme_vars`) as one rule on `:is(#kimaai-chatbot, [data-kimaai-chatbot]).kimaai-chatbot` in the document, and every root carries `data-kimaai-mode`, `data-kimaai-style` and `data-kimaai-color-preset` (`themeAttributes()`);
    - `config.theme.tokens` (JS, empty by default) as the inline style of `.kimaai-chatbot-app-root`, inside the shadow root.
    - Custom properties set on the root (the shadow host) inherit into the shadow tree, and a document rule on the host beats the stylesheet's own `:host(...)` fallbacks, so the theme's values always win over the defaults. **WD-3 writes its look as custom properties on the chat root** (the same inline rule from PHP for the first paint, or a `style` attribute on the root) and keeps what is not a value (mode, style) as data attributes on the root; the widget's rules for them are adapted to `:host([data-kimaai-...])`. It must not declare the same properties again on `.kimaai-chatbot-shadow-root` or deeper in the widget's CSS, which would hide the root's values. Auto mode keyed on `prefers-color-scheme` works the same way (`@media` rules are adapted too).
- **What crosses from the page.** Only inherited properties do. `.kimaai-chatbot-shadow-root` starts from `all: initial` and takes back only the site's font (`font-family: inherit`), the visibility (a site that hides the root keeps it hidden) and a line height of 1.5 (the prototype's); `all` leaves custom properties and the writing direction alone. So Twenty Twenty-Five's weight 300, its line height and letter spacing no longer reach the widget: the panel shows the widget's own weights and is about 20 px taller at 1440 px (before and after screenshots).
- **The font.** The site's font flows in through the root; form controls take it with `font: inherit` (zero specificity), so the message field is no longer monospace, also in the admin's preview frame. `@font-face` stays in the document's copy (it does not work in a shadow root); Persian still gets Yekan (`:lang(fa)`, the root carries the page's `lang` and `dir`). Links the widget does not colour itself (the search answer's sources) take the widget's link colour instead of the theme's. System and Geist under Advanced are WD-3 and WD-9: a font is a value on the root like the colours, and Geist's `@font-face` must be printed in the document, only when chosen.
- **The site's forms stay in the light DOM.** `LightDomSlot` (`src/chatbot/components/ui/LightDomSlot.jsx`) renders its content through a portal into a `<div slot>` child of the chat root and shows it in the widget through a named `<slot>`; without a shadow root (admin, preview, Storybook) it renders in place. Contact Form 7, Gravity Forms and WooCommerce product HTML use it, so the theme's and the plugins' CSS reach them, CF7's `init`, Gravity Forms' inline scripts (`document.getElementById`) and WooCommerce's click handler delegated to the document see them, and the widget's own rules for them apply from the document's copy. The meeting booking stays in the root: Calendly and Cal.com draw an iframe into the element they are given.
- **Checked in a shadow root:**
    - portals: the widget has none; `ChatDialog` (CSAT, Ask-AI) renders in place, inside its root;
    - focus: `document.activeElement` is the host inside a root, so `ChatDialog` (Tab trap, focus back on close) and the search answer's retry focus read the root's own `activeElement` (`activeElementOf`); Escape and Tab arrive through the document (keyboard events are composed);
    - outside clicks and delegation: the Ask-AI listener on the document handles the page's triggers; no handler depends on a click inside a root, whose target the document sees as the host;
    - `@wordpress/components`: not used in the widget;
    - right to left and dark mode: the root's `dir` (from the root's computed direction) and the mode attribute on the host; `.rtl` rules also match `[dir='rtl']`;
    - scripts that query the widget: `visibleSection.js` (the page's headings for content awareness) no longer finds the widget's own headings at all; the admin assistant's targets are in the admin's DOM; the e2e selectors pass through shadow roots (Playwright locators and text matching pierce them, `toBeFocused` reads the deep active element, axe-core includes open shadow roots, and every `page.evaluate` on widget nodes reads the root itself: its custom properties, its position in the page).
- **`!important`:** 47 → 6. Removed the 41 that only fought theme CSS (launcher, header icon and close button, consent button, message colours, feedback buttons in both modes, form buttons, quick action colours, popover text in both modes, consent highlight, avatar size, the message field, the send button); the computed styles of the states above were identical with and without them. Kept: the quick actions' line height and padding and their margins, which fight the root's own `button { line-height: 0; margin: 0 }`; the popover's quick action margin, which fights those; and the product card's margin, which fights WooCommerce's CSS in the light DOM.
- **The admin assistant stays in the light DOM:** it lives in the admin's React tree in wp-admin, where no visitor theme's CSS reaches, and its look comes from the admin's stylesheet (`.kimaai-admin-assistant-shell` rules in `src/admin/index.css`, the admin's dark mode on `body`), which a shadow root would cut off. The Appearance page's live preview stays in its frame (already isolated; checked unchanged); WD-9 can mount it with `attachWidgetRoot` too, so the widget's CSS is written once.
- **Tests:** Jest for the adapting, the mount (page copy, fetch fallback, one read per page, direction and language), `LightDomSlot`, `activeElementOf` and `ChatDialog` in a shadow root. Playwright `chatbot-shadow-root.spec.ts`: the hostile-CSS fixture (an mu-plugin printing broad `*`, `body`, `p`, `button`/`input`/`textarea`, `svg`, `img`, `ul`, `a` rules with `!important` and a line height of 3 when the URL asks for it) compares the computed styles of 15 parts of the widget with and without it, on Twenty Twenty-Five and the classic e2e theme; every mount in an open shadow root with one stylesheet request; the message field in the body's font; the three light-DOM renderables with the site's CSS and scripts (CF7 submits, Gravity Forms' script finds its form, the delegated add to cart fires). Run on the Mac with the repo's Playwright setup: the new spec passes; against the base commit's build the hostile-CSS tests fail at the launcher with 13 leaked properties (yellow, dashed, monospace, uppercase). Every `chatbot-*` spec and the white-label, free-build and lead specs ran against this branch (154 tests): two needed axe's path into the shadow root (`chatbot-ask-ai.spec.ts`, `chatbot-lead-capture.spec.ts`, whose axe context named a node inside the root); the rest passed unchanged, apart from two admin tests that failed once and passed on the next run (`admin-leads` target size, `admin-settings` a dropped fetch). The new spec is in the `chatbot-widget` group of `ci/test-map.mjs`. Screenshots: `before-*` and `after-*` in the WD-4 shots folder.
- **Left:**
    - the widget's sizes in `rem` still follow the page's root font size (a theme with `html { font-size: 62.5% }` shrinks it); WD-5 and WD-6 should size in `px` or from the root;
    - the chat root itself is still the page's element: a theme's `div` rules reach its box (a margin around an inline chat), and a `transform` on it would make the floating layer move with it. Not defended on purpose, so a site can still hide or place the root;
    - checked in Chromium only (the Playwright Firefox and WebKit builds on the Mac do not match the installed Playwright); adoptable stylesheets need Firefox 101 or Safari 16.4, older browsers get the `<style>` element;
    - no Storybook story for the mount: Storybook injects the CSS as `<style>` tags, so there is no page stylesheet to adopt; the Playground screenshots and the Playwright spec cover it.

## WD-3 and WD-4 together (integration check)

Checked 2026-11-15 on `track/WD-widget-design` after both merges, in WordPress Playground (WordPress latest, PHP 8.3, no networking, Twenty Twenty-Five, chat history answered in the browser with invented content). Shots in the integration shots folder (`shots-wd34/`), compared with WD-3's `after2/`, which were taken before the shadow root.

**The theme path now.** WD-4's notes describe the path before WD-3: `ChatbotTheme::cssVars()` and `config.theme.tokens` no longer carry the theme. `ChatbotAssets::generateDynamicCss()` prints the engine's `--kimaai-w-*` (after `kimaai_chatbot_theme_vars`) in the document on `:is(#kimaai-chatbot, [data-kimaai-chatbot]).kimaai-chatbot`, for Auto the dark set under `@media (prefers-color-scheme: dark)`; `themeAttributes()` puts `data-kimaai-mode`, `-style`, `-density`, `-font` and, for a carried-over style, `data-kimaai-legacy-style` on every root. The variables inherit through the shadow host into the widget. `config.theme.tokens` is still read by `PanelMountShell` as an inline style inside the shadow root, but PHP sends none and the defaults are empty strings, so it declares nothing.

**What was checked:**

- Every mount (floating, inline shortcode, Ask-AI modal, search answer) in an open shadow root, for a new site (Calm, Light), a new site on Auto with a light and with a dark visitor, and the carried-over sites (Classic light, dark, System with a dark visitor, Minimalist light and dark, Glossy, Neon light and dark, custom colours Pro and free, sun yellow, Classic and new site at 390 px): on `.kimaai-chatbot-shadow-root` and on a node inside it, every `--kimaai-w-*` equals `ChatbotLook::derive()` for the site's plan and the visitor's scheme, and equals the host's value. The root attributes equal `ChatbotLook::attributes()`. 58 mount checks, no difference.
- The colours against WD-3's `after2/`: no colour that covers 0.3 % of one screenshot is missing from the other, in any scenario. The pixels that differ are WD-4's layout (line height 1.5, the widget's own weights, the message field no longer monospace, the panel about 20 px taller) and two invented posts on the home page.
- After `toShadowCss` (on the built `chatbot.css`), every rule keyed on `data-kimaai-mode`, `data-kimaai-style` or `data-kimaai-legacy-style` on a chat root is a `:host(...)` rule; only the admin preview's `.kimaai-chatbot-preview-inner` rules stay as they are (the preview is not in a shadow root). A Jest test now keeps the palette's root rules on the host.
- Nothing in the widget's CSS declares `--kimaai-w-*` or the palette's `--kimaai-chatbot-*` colours below the host (only the Ask-AI dialog's `--kimaai-chatbot-height`). `all: initial` on `.kimaai-chatbot-shadow-root` leaves them: they read the same there as on the host.
- `kimaai_chatbot_theme_vars` setting an old name (`--kimaai-chatbot-header-background-override`, `--kimaai-chatbot-primary`) still wins inside the shadow root: the document's rule on the host beats the adopted stylesheet's `:host(...)` rules.
- The Appearance page's preview follows the engine: Calm light, then Bold dark and Minimal light on `#1f7a4d`; its inline variables equal `ChatbotLook::derive()` and the header and panel colours match. It stays in the light DOM of its frame, as WD-4 left it.
- The e2e specs `chatbot-shadow-root`, `chatbot-settings`, `chatbot-a11y`, `chatbot-sources`, `chatbot-code-blocks`, `chatbot-ask-ai` and `chatbot-lead-capture` on the Mac with the repo's Playwright config: 49 passed, none flaky. That includes WD-3's spec changes, which WD-3 could not run.

**Fixed:** the shadow mount's comment named `ChatbotTheme::cssVars()`, which WD-3 removed.

**Found, not changed (before WD-3 and WD-4):** the Ask-AI dialog's title uses `--color-kimaai-chatbot-900` (30 % brand on near-black), which no dark mode rule changes, so in dark mode it is dark on dark. It was so before the theme engine; the Ask-AI restyle should take the engine's text colour.

**Not checked here:** a classic theme, right to left and Firefox or Safari for the seam (the variables do not depend on the theme or direction, and WD-4 covered those for the mount); the Geist font flag, which no CSS reads yet.

## WD-9: The Appearance page (build notes)

Built 2026-11-15 on `wd/look`. Looked at in WordPress Playground (WordPress latest, PHP 8.3, no networking, the e2e mu-plugins, invented sample content) at 1440 px with the WordPress menu expanded: free and Pro, light and dark admin, left to right and Persian right to left; before and after screenshots in the WD-9 shots folder (`before-*` on the base commit, `after-*`, `after2-*`).

**The page.** `tab=chatbot-appearance` is unchanged, so old links, the admin assistant's targets and the search keep working; only the sections and some labels moved. Its cards, in the approved order:

- **Theme:** the brand colour (picker, hex, up to six colours of the active theme's palette, the KimaAI default), the four styles as radio cards drawn in that colour (`STYLES` of the engine: header, answers, radius and depth), the colour mode Light, Dark or Auto, and the contrast report.
- **Launcher:** show on every page, position, the distances from the edges, and the chat icon (WD-5 owns the icon setting; only its `section` changed here).
- **Header and name:** icon in the header, name, the line under the name (`chatTitle`), the avatar next to answers.
- **Welcome and messages:** welcome text (`greeting`), placeholder, the AI notice, the copy button, the visitor avatar only where a site set one (decision 7: a condition on its own value), the note under the chat (`disclaimer`), the "Powered by" link.
- **Voice:** left out. The `voice` feature is not in the registry on this branch (WD-10 adds it hidden), and a hidden feature shows nothing in the admin (FS). The live preview's Voice state follows the same rule (below).
- **Attention popover:** as before.
- **Advanced**, closed (`panel`, `initialOpen: false`): corners, density, font, and the colours of single parts.

**One setting in two cards.** The look is one stored object (`appearance.look`), but its parts sit on the Theme card and under Advanced. A schema field may now name `views`: the same setting drawn again in another section with other props (`buildMenu`, `schemaIndex.js`). The view has the field's settings path and no label, so saving, Reset, unsaved changes and the search treat it as one setting. `ChatbotLookField` (`src/admin/components/Fields/`) draws `part="theme"` or `part="advanced"`; it replaces the stand-in `ChatbotThemeField`, which is removed. It sends every part colour, an unset one as empty, as the stand-in did.

**The contrast report** (`src/admin/chatbot/lookReport.js`), from `deriveLook()` for the colour modes the widget shows (Auto: both):

- the lowest contrast of the derived text colours;
- each use of the brand colour the engine moved, in plain words with the colours (buttons and visitor messages, the thin edge on a fill that melts into the panel, links and icons, the launcher in dark mode);
- white or near-black text on the brand: "Header text set to near-black for readability" (Bold), and the same for the text on buttons and visitor messages;
- the site's own colours of single parts that fail their rule, in red with the ratio and what it needs. They stay allowed (decision 9).

The report reads the look as the site shows it (`lookForPlan`), so a changed part colour on a free site is not reported.

**Colours of single parts** (Advanced): a Light and a Dark tab; for each of the 14 parts the colour as the site shows it ("Auto · #…" when derived), its contrast badge (the engine's check for that part), "Auto" to hand it back to the brand colour and, for a colour the carry-over brought and that was changed since, "Reset". Pro: the pickers are disabled on a free site; carried colours keep showing there while unchanged (WD-3), a changed one says "Not shown without Pro".

**The live preview.**

- **Mount:** the preview's frame now loads `chatbot.css` with the id the front end prints, and the widget renders through `attachWidgetRoot` into a shadow root on a `#kimaai-chatbot.kimaai-chatbot` root that carries the engine's variables and flags, as on a site. The rules that fit the widget into the card go into the shadow root as a second adopted sheet after the widget's (`setShadowCss` in `ChatbotPreview.jsx`). `.kimaai-chatbot-preview-mode` is on the shadow container, so `FloatingMountShell` still positions the widget in the frame.
- **Shadow mount, per document:** `shadowMount.js` cached the stylesheet and the constructed sheet once per page. The admin's preview frame is a document of its own (a new one after each page change in the app), and a constructed sheet cannot be adopted in another document, so the cache is now per document. The front end has one document and behaves as before.
- **Switches:** Desktop or Mobile, the site's Light or Dark, and what it shows: Closed (the launcher, with the attention popover when it is on), Welcome, Answer (a visitor's question answered with a short sample; `previewMessages` in the preview transport) and Voice. Voice is a still drawing of the planned listening state in the look's colours (`VoicePreview.jsx`), shown only once `voice` is in the registry and not hidden. Under the frame, what visitors see of the colour mode.
- The phone frame's message list is 280 px high (was 320): with the shadow root's line height the open panel no longer fitted, and its header was cut off.

**Free and Pro.** The distances from the edges are free (the field's Pro flag is gone; the front end never gated them). The field's `defaultValue` is 24 px, as the schema's default (it said 50 px). Colours of single parts stay Pro, the rest of the theme is free.

**Also:**

- Home's "Make it look like your site" step counts a changed brand colour, style or colour mode; since WD-3 only the version 2 theme counted, which nothing edits now.
- The admin gets the active theme's palette (`kimaaiAdmin.themePalette`, `ChatbotLook::themePalette()`): hex colours only, without the near-white and near-black ones a theme uses for its page and text, six at most.
- Changed strings (section titles, field labels, the report) fall back to English until the translations are updated; the POT is not regenerated on this branch.

**Tests.** Jest: the field (both parts, free and Pro, the palette, arrow keys), the report, the preview (shadow mount, states, answer conversation), the live preview's switches and the voice rule, `views`, the per-document stylesheet, Home's look step. PHPUnit: `AppearanceSchemaTest` (sections, the look's views, free distances, the visitor avatar condition, the palette); the admin schema fixture is written again. Playwright, run on the Mac: `chatbot-settings.spec.ts` (36 passed; the offset test now runs on a free install, two new tests for the page: the report, the shadow-mounted preview with the Answer state, the saved look; the part colours with a failing badge), `admin-settings`, `home`, `chatbot-lead-capture`, `chatbot-shadow-root` (22 passed). Storybook: "Admin/Chatbot" Appearance, dark and free render with the dump of the new schema, the preview's widget in its shadow root.

**Left, and for the other items:**

- The **font** setting is stored and flagged on the root (`data-kimaai-font`), but no widget CSS reads it yet and Geist's `@font-face` is not printed (WD-3 and WD-4 each left it to the other). It belongs in the widget's stylesheet, which WD-9 does not own.
- **New settings from the prototype** are not added: the launcher's shape and label, the welcome heading, the avatar as mark or initial. They need the shell to render them (WD-5); the page takes them in their cards once they exist. The default "Talk to our AI agent:" of the line under the name is unchanged (the research's "AI assistant" needs a migration of stored defaults).
- The fit rules of the preview name today's `.kimaai-chatbot-container` and `.kimaai-chatbot-body`; if WD-5 renames them, the rules in `LivePreview.jsx` follow.
- `.kimaai-chatbot-preview-inner` in `chatbotColorPalette.css` and `index.scss` matches nothing since the preview mounts as on a site; left in place to keep the parallel merges clean.
- The Storybook mocks still set `window.kimaaiAdmin.chatbotTheme` (WD-3's note).

## WD-8: Ask AI and the search answer (build notes)

Built 2026-11-15 on `wd/askai`, from the prototype's "Ask AI and search answer" stories. Code: `src/chatbot/components/askAi/*`, `src/chatbot/components/searchAnswer/SearchAnswerBox.jsx`, the styles in `src/chatbot/styles/_ask-ai.scss` (the old Ask-AI and search answer rules left `index.scss` in whole blocks), the buttons in the theme's search forms in `ChatbotAssets` and a production story, "Chatbot/Ask AI and search answer".

**The Ask AI dialog is a command palette.**

- The top bar holds the search field (the search icon, the field, an Esc hint, Close). Below it the results: "Ask AI: …" first, with "Answered from this site’s pages, with sources", then "Pages", each with its icon and its path (none for plain links like `/?p=12`). The footer has the key hints and the site's note under the chat (`disclaimer`), if any.
- Asking turns the same dialog into the chat. The bar then holds "Back to results", and the panel mount fills the dialog at one height (640 px, at most 80 % of the screen). "Back to results" keeps the query.
- **The two tabs (Search, Ask AI) are gone:** the prototype has none, and the dialog now has one view at a time. The keyboard model stays: focus opens in the field (or on "Back to results" when the search answer's "Continue in chat" opens the chat), the arrow keys move through the results (the active one scrolls into view), Enter picks, Tab stays in the dialog, Esc closes it and returns focus to the trigger.
- "N pages found" is for screen readers only; searching, nothing found and a failed search are on screen too.
- The chat keeps its own look (WD-6); the dialog only takes away the panel mount's border, corners and shadow.
- **The dark title** (`--color-kimaai-chatbot-900`, dark on dark, found in the WD-3 and WD-4 check) is fixed: the dialog's name is now visually hidden as in the prototype (the field and the bar say what the dialog is) and takes the engine's text colour.
- Colours, radii and flags come from the engine on the root: `--kimaai-w-*`, with Glass a glow of the brand colour, Minimal no shadow, dark shadows for Dark and for Auto with a dark visitor, and Compact 14 px. Sizes are in px.
- Phones (440 px and less) get the whole screen inside the safe areas. Touch screens and phones get no key hints.
- Reduced motion stops the dialog's rise. In forced colours the active result keeps an outline.

**The search answer is a card in the theme's column.**

- The card has a glow of the brand colour in its corner (none for Minimal) and "AI answer" in the link colour, with "Based on N pages" once answered. It spans the column and keeps a margin of 1.5 times the theme's text size above and below.
- Its states:
    - **before the answer:** a line saying what it does, and "Generate AI answer";
    - **writing:** three shimmering lines;
    - **the answer:** text, sources, "Continue in chat →", thumbs;
    - **a long answer:** collapsed to 168 px under "Show more", with `aria-expanded` and `aria-controls`;
    - **no answer:** an empty reply says the pages do not answer the search and keeps "Continue in chat". There are no sources, count or thumbs then, as the reply carries the search results as sources;
    - **error:** the reason with an icon, and "Try again".
- The sources are `SourceList` (WD-7) and the thumbs `ChatMessageFeedback` (WD-6): the card only places them.
- A theme's focus outline on the root no longer draws a second ring around the whole card. Twenty Twenty-Five drew one when "Try again" took the focus, because a shadow host counts as focused while a control inside it is.

**The Ask AI button in the theme's search forms** now goes right after the form's search button, in its row, with the dialog's sparkles before its label, in the theme's own button look. Before, it went at the end of the form, which put it on its own line in Search blocks and in classic forms whose fields sit in a `div`. A form without a search button still gets it at its end. In a Search block on a phone, the field takes its own row and the two buttons start the next one.

**Checked in Playground.** WordPress latest, PHP 8.3, no networking. The chat and answer routes were answered in the browser and the site search was WordPress's own, on invented posts of a made-up outdoor shop. Shots are in the WD-8 shots folder: `before-*` on the base commit, `after-*`, and `sb-*` for the Storybook stories, production and prototype, at 1440 and 390 px.

- Twenty Twenty-Five and a classic theme (Georgia, square black buttons), light and dark, left to right and Persian, 1440 and 390 px, the four styles.
- Every state of the card and the dialog, and the trigger in a Search block and in a classic form.
- Two sites carried over from 1.5.13 settings: Neon dark, and custom colours with overrides. Both read well; the Neon site's dialog is no longer dark on dark.
- Jest: the dialog (11 tests) and the card (13). PHPUnit: the trigger's place in the classic form, the Search block and a form without a button.
- Playwright on the Mac: `chatbot-ask-ai`, `chatbot-search-answer` and `chatbot-shadow-root`, with axe (WCAG 2.2 AA) on the open dialog and the card.

**Left:**

- The font flags (System, Geist) are not read by these two roots either. Whoever adds them for the widget's roots should cover `.kimaai-chatbot-ask-ai` and `.kimaai-search-answer` too.
- Inside the dialog the chat shows its own header (avatar, name) under the dialog's bar. Hiding it would also hide its ⋯ menu (WD-5), so it stays.
- In narrow columns between 440 and about 600 px, the Search block's buttons can wrap, and the first one keeps core's start margin.
- Checked in Chromium only.

## WD-7: Renderables (build notes)

Built 2026-11-15 on `wd/rend`. Every renderable the chatbot shows in a conversation is now the prototype's card (`Cards.jsx`, `.kwd-card` in `widget.css`): a 1 px border in the engine's border colour, the panel's background, the radius of a message × 0.8, padding 14 px × the density, a head with a 32 px tinted icon, a title and a line under it.

**One card, one partial.** `src/chatbot/components/Renderables/RenderableCard.jsx` holds the head (`CardHead`) and the in-card problem line (`CardError`, an alert); the styles are in `src/chatbot/styles/_renderables.scss` (block `kimaai-rcard`). The old blocks of the lead form, the booking, the sources, the ticket and the product HTML are deleted from `index.scss`. Sizes are in px, so a theme with `html { font-size: 62.5% }` does not shrink the cards (checked on the classic theme).

- **Colours:** local tokens `--kimaai-rc-*` read the engine's `--kimaai-w-*` (bg, raised, hover, border, border-strong, text, muted, accent, accent-edge, on-accent, accent-text, accent-soft, on-accent-soft, input-bg, input-text, danger, danger-soft, success, success-soft, r-bubble, r-control), with the admin's `--kimaai-ui-*` as the fallback. So the same components take the site's look on the front end and in the Appearance preview, and the admin's look where no chat root sets the engine's variables: the admin assistant, the conversation views in wp-admin (Leads, Chat history) and Storybook.
- **Flags:** density compact (`:host([data-kimaai-density='compact'])` after the shadow adaptation) multiplies the spacing by 0.78; the style and the Corners setting arrive through the engine's radii; dark (`data-kimaai-mode='dark'`, or `system` with a dark visitor) sets `color-scheme: dark` on the cards, so checkboxes, scrollbars and the site's own form fields inside them draw dark.
- **Carried-over sites** (Bold with `data-kimaai-legacy-style`): the cards read the engine's variables, which hold the carried colours of single parts (panel, text, border, field), so a Neon or custom-coloured site keeps its colours in the cards; the shapes are Bold's, as the carry-over rule says for restyled components. Before WD-7 the ticket card was a light box in dark mode (the old `--kimaai-ui-*` colours); it now follows the site's dark colours.

**Each renderable:**

| Renderable                              | Now                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Lead form                               | Head "Leave your details" / "We will get back to you." (two new strings), fields in a row where they fit (email on its own row, name and phone side by side, as the prototype), email and phone left to right on right-to-left sites, consent and marketing as the prototype's checks, Send then a ghost Not now. A failed send shows the server's reason in the card (alert); success is a card with a check. Send stays disabled until the required fields and the consent are there, as before (the specs rely on it).                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Meeting booking                         | Head with the provider note; Show calendar. Open, the provider's calendar fills the card to its edges. When the provider's script does not load: the reason and "Open the booking page" (the fallback link). Booked: a success card. The prototype's own day and time picker is not built: the calendar is Calendly's or Cal.com's.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Products                                | The widget's own cards in a scrolling row (image, name, the short description on one line, the price, an action), drawn from the payload's `items`, as the research proposes ("product cards should move to data"). The action keeps what WooCommerce's own button did (lead decision, 2026-11-15): a product that can be added in one click (WooCommerce's `supports('ajax_add_to_cart')`, purchasable, in stock: a simple product) gets Add to cart in WooCommerce's words, through WooCommerce's AJAX endpoint when the shop adds without reloading (the result in the card: "Added to your cart" with View cart, or the reason with a link to the product) or else through its add to cart URL; its name then links to its page. A variable product links to its page with WooCommerce's label ("Select options"); a product out of stock gets View. WooCommerce's HTML stays as the fallback for a payload without data (light DOM, theme styles, its add to cart). |
| Ticket                                  | Success card with a ticket (or mail) icon, the reference in a raised row in monospace, left to right, View your ticket as a small secondary button. "Reference" without the colon is a new string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Sources                                 | Cited pages as the prototype's numbered chips (a chip is named by its page; the breadcrumb is its tooltip), related pages as small cards under a "Related pages" label. The search answer box (WD-8) uses the same component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Contact Form 7, Gravity Forms           | A card around the form, headed by the form's title (CF7's `title`, Gravity Forms' `form.title` and description, which Gravity Forms leaves out of its HTML). The form itself stays in the light DOM through `LightDomSlot`, untouched: it keeps the theme's styles and its scripts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Secret input, choices, workflow (admin) | Same card; choices are the prototype's option rows with a radio circle, and the chosen one is marked (`aria-pressed`) after its command is sent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Doc, notice, shortcut cards (admin)     | Same card in the admin's colours: the notice by severity (info, warning, error, success, each with its icon), the doc with Read more (now translatable, without the arrow character), the shortcut as a card that is a link with a chevron.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

**Against the rules around the cards.** The chat root's `button { line-height: 0; margin: 0 }` is keyed on the root's id, so the cards' buttons take their line height back the same way. Inside an answer, `.kimaai-chatbot-message .message-box a` (and the admin assistant's link rule in `src/admin/index.css`) colours and underlines every link; the card's button-like links (View, View your ticket, chips, the shortcut card) win over it with one rule that reads their colour from `--kimaai-rc-fg`. A card under an answer takes the answer's full width (the answer is as wide as its text otherwise).

**Woo data.** `price.display` of a product on sale holds the old price and WooCommerce's screen reader sentences ("Original price was: …"). `WooCommerceProductHelpersTrait::buildProductData()` adds `price.current`, the price HTML without `<del>` and `.screen-reader-text`, which the card shows; `display` is unchanged for the AI tools. The renderable's items come from the new `buildProductCardData()`: the product's data plus `cart` from `buildCartData()` (`one_click`, WooCommerce's `add_to_cart_url()` and `add_to_cart_text()`, `ajax_url` from `WC_AJAX::get_endpoint('add_to_cart')` when the shop's "AJAX add to cart" option is on, `redirect_to_cart` from "Redirect to the cart page after successful addition", `cart_url`). The AI tools get no cart data. After an add, the widget tells the page as WooCommerce's script does: `added_to_cart` on the body with the cart fragments, so mini carts update (it replaces the fragments itself when WooCommerce's script is not on the page), and it goes to the cart when the shop redirects after an add. PHPUnit for a simple, a variable and an out-of-stock product, the shop without AJAX, and the tool output without cart data.

**Checked in Playground** (WordPress latest, PHP 8.3, no networking, chat history answered in the browser with invented content for a made-up outdoor shop, every other origin refused; Calendly's script answered by a stub or blocked). Shots in the WD-7 shots folder: `before/` on the base commit, `after/` with this branch, `states/` the interactions, `admin/` and `admin-before/` the admin assistant, `storybook/` the stories, `m-*.png` contact sheets of them.

- Twenty Twenty-Five and a classic theme (Georgia, `html { font-size: 62.5% }`, square black uppercase buttons, yellow inputs), Calm, Bold, Glass, Minimal, compact with sharp corners, sun yellow on Bold, light and dark, Persian right to left at 390 px and Bold dark at 1440 px, and four carried-over sites (Classic light, Neon dark, Minimalist light, custom colours with a navy header).
- States: an invalid email (the server's reason in the card), success, the calendar open (stub), the calendar blocked (reason and the booking page link), booked from the history, keyboard focus moving through the form with a visible ring, Contact Form 7 submitted through its own script (the thank-you appears in the card), Gravity Forms' inline script finding its form, WooCommerce's delegated add to cart on the HTML fallback. In Calm light and dark, Bold, Glass dark and Persian at 390 px.
- Add to cart (shots in `cart/`), with WooCommerce faked by an mu-plugin as in the e2e suite (its `?wc-ajax=add_to_cart` answering with the cart fragments or an error, a mini cart in the page): Calm light and dark, Bold on `#1F7A4D`, the classic theme and Persian at 390 px; a simple product added (the card says so, View cart, the page's mini cart updated), one refused (the reason and Open the product), a variable product with Select options and one out of stock with View. axe: no violations in those five after the add and the refusal (a link in a problem line inside an answer took the answer's link colour in dark mode, 3.9:1; it now takes the line's danger colour).
- axe (WCAG 2.0 to 2.2 A and AA) on the open widget with every renderable, before and after the interactions: no violations in those five.
- The admin assistant in wp-admin (enabled through `kimaai_settings_ui_config`), light and dark: notice, choices after a choice, secret input, workflow, doc, shortcut.
- Compared with the prototype stories "Renderables: lead form and booking", "choices and products", "site form and ticket" at 1440 px: the card, head, fields, buttons, products and ticket match; the prototype's booking day and time picker and its sub lines with invented promises ("calls back within a working day") are not built.

**Tests:** Jest for the card around Contact Form 7 and Gravity Forms (named by the title, the form inside), the product cards from data (only safe links, `current` before `display`, no HTML next to them; Add to cart through the AJAX endpoint with View cart, the page told and its mini cart replaced; a refusal; the add to cart URL without AJAX; Select options and View), the chips with the breadcrumb as tooltip, the chosen option; the existing tests pass with the new markup. PHPUnit for `price.current` and the cart data. Storybook "Chatbot/Renderables/Widget renderables (shared card)" with the engine's variables (style, mode, brand, density, corners as controls) and its dark Bold variant. Playwright: `chatbot-sources.spec.ts` (the breadcrumb is the chip's tooltip) and `chatbot-handoff.spec.ts` (the reference is `.kimaai-rcard__ref-value`, no longer `strong`) updated; `chatbot-shadow-root.spec.ts` has a new test: the widget's product cards add to the cart through a faked WooCommerce AJAX endpoint and refresh the page's mini cart, and a refusal shows the reason (the spec's 5 tests pass). Run on the Mac with the repo's Playwright config: every `chatbot-*` spec (but the paid one), `lead-privacy` and `admin-leads`, 96 tests: 75 passed in the first run with four workers and one skipped; the 20 that failed did so on timeouts and refused connections while a second Playground ran, 15 of them passed again with two workers and the last 5 with one, so all pass.

**Left, for others:**

- WD-6: the cards sit inside the answer's bubble because `RenderableHost` is rendered in `.message-box` (`MessageItem.jsx`); the prototype puts them after the bubble, and shows no copy and rating row under an answer that is a card. The cards look right in both places.
- The chat root's `button { line-height: 0; margin: 0 }` and `p { margin: 0 }` (the root block of `index.scss`) also reach the site's own forms in the light DOM through the document's copy of the stylesheet: Contact Form 7's submit button is squashed to one line height of 0 (before WD-7 too). The rule should leave `.kimaai-chatbot-light-dom` alone; WD-7 does not touch it, because only the shell's root rules can.

## WD-5: Shell (build notes)

Built 2026-11-15 on `wd/shell`. The prototype's shell ("Widget design/Widget": launcher, popover, welcome, header menu) in the production widget, on the theme engine's `--kimaai-w-*` and its flags.

**What it is now.**

- **Launcher** (`FloatingMountShell.jsx`): a 58 px circle in `--kimaai-w-brand` with the KimaAI mark (`src/assets/icons/KimaMark.jsx`, in the registry as `KimaMark`), or the site's picture (today's icons, a custom URL) on the brand colour, as the prototype's "Carried over: today's icon". It stays while the chat is open and shows a chevron that closes it ("Close chat", `aria-expanded`). A red dot while the attention popover waits. Its side and the distances reach the launcher, the popover and the window as `--kimaai-chatbot-offset-bottom` and `--kimaai-chatbot-offset-side` (physical left or right, also right to left, as before).
- **Icon setting** (`chatbot.php`): the default is `KimaMark` for new sites; the first row is the mark and Custom, today's nine pictures sit under "More icons" (`more: true` on an option; `IconPickerField` shows them behind a disclosure, open when one of them is chosen). An existing site keeps the icon it stored: every install that ever ran a schema upgrade has `icon` stored, and the upgrade fills only missing keys (PHPUnit `ChatbotIconSettingTest`).
- **Attention popover** (`FloatingAttentionPopover.jsx`): one card with the avatar, the name, the AI notice as the line under it, dismiss, the message and the first two quick actions as chips (the prototype shows two).
- **Window** (`ChatbotPanel.jsx`): a `<section>` named after the chatbot; floating 408 × min(700 px, the screen minus the launcher), 72 px above the launcher; the larger window 720 px wide. It rises from the launcher (360 ms) and sinks back on close (180 ms: `FloatingMountShell` keeps it mounted with `is-closing`, then unmounts); with `prefers-reduced-motion` both are off and it closes at once. Opened by the visitor, focus goes to the message field (on a touch screen to the window, so the keyboard does not cover half the screen unasked); Escape closes it, focus returns to the launcher. The launcher closes through the header's path, so the rating at the end is still asked for. Inline (block, shortcode, Ask AI) the window fills its column at `--kimaai-chatbot-height` (default now 512 px, not 32 rem), no motion, no focus on load.
- **Phones** (≤ 440 px, the research's "from 440 px down"): the floating window takes the whole screen, without border or corners, inside the safe areas (`env(safe-area-inset-*)`: the header's top padding, the window's sides and bottom). `usePhoneViewport` sets the window's height and top from `visualViewport`, so the on-screen keyboard pushes the message field up instead of covering it.
- **Header** (`ChatbotHeader.jsx`, `ChatbotMenu.jsx`): avatar, name (`.chat-name`), the line under it with a dot (`.chat-title`, the stored chat title), the ⋯ menu and close. The menu holds New conversation, Talk to a person (only with the handoff on and consent given) and Larger window (hidden on phones); it is a real menu: focus on the first item, arrow keys, Home and End, Escape back to its button, Tab or a click outside (read through the composed path, so it works in the shadow root) closes it. Voice and Download transcript wait for WD-10 and a transcript feature.
- **Welcome** (`ChatbotWelcome.jsx`, rendered by `ConversationScreen` while the conversation is empty): a large avatar, the greeting (the research's "welcome text", Markdown as before) and the quick actions as full-width rows with an icon by type and a chevron (mirrored right to left). It shows at once; the rows come with the history. Under required consent a row points to the consent, as the quick actions did. Once a message is sent the welcome makes room for the conversation (prototype); the greeting is no longer a message bubble.
- **Avatar** (`ChatbotAvatar.jsx`): a spark on the accent where the site uses the mark (the prototype's avatar), else the site's picture on the soft accent.
- **Shared primitives:** `ChatButton` variants on the engine (primary = accent with its edge, secondary = neutral border, ghost = link colour, icon = 36 px targets with a `currentcolor` hover), `ChatNotice` as one card tinted by status (danger and success from the engine), `ChatDialog` with the engine's surface and text, its title included (the base rule with `--color-kimaai-chatbot-900` is deleted from `index.scss`, so the CSAT and Ask-AI titles are no longer dark on dark in dark mode, noted in "WD-3 and WD-4 together") and, inside the chat window, a sheet from the bottom (the research's "Rating at the end"). Their rules keep `:where()` and fall back to the brand tokens where the engine's variables are missing (the admin assistant). The JSX is unchanged.

**Styles and carried-over sites.** Everything is in `styles/_shell.scss`; the shell's old rules (ChatButton, ChatNotice, launcher, container, header, preview positions, ChatDialog base, attention popover, the Persian font on the container, the inline container, and the launcher, outline button and popover parts of the dark mixin) are deleted from `index.scss` in whole blocks. Style flags are read on the chat root (`:is(#kimaai-chatbot, [data-kimaai-chatbot])[data-kimaai-…]`, which `toShadowCss` turns into `:host(…)`) and on `.kimaai-chatbot-preview-inner` for the admin's preview. Calm and Minimal have a hairline under a neutral header, Bold the brand header with a soft highlight, Glass a frosted window with the brand's glow; Minimal no shadow; dark mode deeper shadows. Density scales the shell's spacing (`--kimaai-chatbot-space`, 14 px text); the System and Geist font flags set the family (Geist's `@font-face` is not loaded by WD-5), Persian keeps Yekan.

A carried-over site is Bold (WD-3). The research's rule is that no site changes its look on its own, so **its legacy style keeps the window's and the popover's corners and depth**: Minimalist 8 px and no shadow, Glossy 18 px with its shadow and sheen, Neon 16 px with the brand's neon glow (`--kimaai-chatbot-shell-radius`, `-shadow`, `-overlay` on the root). Classic carries no legacy flag and takes Bold's 20 px. The colours are the carried ones. What does change, by design: the launcher (brand circle with their picture, instead of a pale 72 px circle), the window (408 px, above the launcher, instead of 500 px over it), the header (name first, the title under it, a menu instead of the full-screen button) and the welcome instead of the greeting bubble.

**Checked in Playground** (WordPress latest, PHP 8.3, no networking, a fake chat provider, invented sample content; the base commit's build next to this one; shots in the WD-5 shots folder, `before-*` on the base, the rest after):

- new sites in Calm, Bold, Glass and Minimal with `#5250e6`, `#1f7a4d`, `#e4572e` and `#f5c518`, light, dark and Auto with a dark visitor; launcher on the right and the left; the popover light and dark; the menu;
- 390 px: closed, welcome, answer, the menu (no Larger window), the popover across the width;
- a classic theme (Georgia, square black buttons): Calm, Bold dark, Minimal at 390 px;
- Persian right to left: welcome on the left, Bold dark, Glass at 390 px, the popover on a classic theme, the menu;
- the chat block inline, 1440 and 390 px;
- carried-over Classic and Neon (no look stored, today's icon): closed, welcome, answer, Neon dark, 390 px, the popover, before and after;
- the Appearance page with the icon setting and "More icons".

Compared with the prototype stories at 1440 and 390 px (`proto-*` shots): the same launcher, popover, header, menu and welcome rows. Differences: the composer and messages are WD-6's. The new settings were shot too (`set-*`: a label launcher, a rounded square, the initial, a heading, Geist and System, Persian with a label).

**Tests.** Jest: `FloatingMountShell.test.jsx` (the launcher with the mark or a picture, the named window and focus, the welcome and its rows, Escape and the launcher closing with focus back, the closing motion and reduced motion, the menu's keys, items, the larger window and New conversation, the handoff item, axe on the open widget), the popover's card and two chips, "More icons" in `IconPickerField`, the mark in the registry. PHPUnit: `ChatbotIconSettingTest`. The `chatbot-*` e2e specs ran on the Mac (see the report).

**Specs changed.** `pages/chatbot-widget.page.ts` (`expectGreeting` reads the welcome; `open()` waits for the window's rise, which axe otherwise measures half faded), `chatbot-rtl.spec.ts` (the header's close button: the launcher is called "Close chat" too while open), `chatbot-settings.spec.ts` (the AI avatar tests read an answer from the history, as the welcome has no bot message; the popover's quick action is read as a button), `chatbot-shadow-root.spec.ts` (the CF7 button keeps the site's look).

**The site's forms in the light DOM.** The chat root's own resets (`button { line-height: 0; margin: 0 }`, `textarea` and `p` margins) reached Contact Form 7 and Gravity Forms in `.kimaai-chatbot-light-dom` through the document's copy of the stylesheet and squashed CF7's submit button (before WD-5 too). They now skip `.kimaai-chatbot-light-dom` and everything in it (`:where(:not(.kimaai-chatbot-light-dom *))`, no added weight); `chatbot-shadow-root.spec.ts` checks that a site rule for the CF7 button's line height and margin wins.

**Settings added for the shell** (lead's request from WD-9; `chatbot.php` under `appearance`, all free, defaults that keep every site as it was; passed to the widget in `ChatbotAssets` and to the admin's preview in `ChatbotPreview`):

- `launcherShape`: `circle` (default), `square` (18 px corners) or `label` (the mark with `launcherLabel`, or the chatbot's name when the label is empty); section `general`. While the chat is open the launcher is the round close button.
- `launcherLabel`: text, translatable, shown with `label`; section `general`.
- `avatar`: `icon` (default: the chat icon, so a site's picture stays in the header), `mark` (the spark on the accent) or `initial` (the first letter of the name); in the header, the welcome and the popover; section `branding`.
- `welcomeHeading`: text, translatable, empty by default (the research: "starts empty on existing sites"); above the greeting, which then turns into the muted line under it; section `messages`.
- **Font:** `data-kimaai-font` `system` and `geist` set the family on every mount's root inside its shadow root (`.kimaai-chatbot-shadow-root`: the floating and inline chat, the Ask-AI dialog, the search answer) and on the app root in the admin's preview; Persian keeps Yekan on all of them. For Geist, `ChatbotAssets::generateDynamicCss()` prints its two `@font-face` rules (Latin, Latin Extended, the admin's files in `assets/fonts/geist`) in the document, only when the look's font is Geist (PHPUnit).

The WPML admin texts (`npm run i18n`) and the POT are not regenerated here, per the parallel rules: `launcherLabel` and `welcomeHeading` are `translate: true` and need it at the next i18n run.

**Left, and questions.**

- **The line under the name:** the research maps the old default "Talk to our AI agent:" to "AI assistant". Not done: WD-3 kept `chatTitle` as it is (its migration test asserts it), and the default is the Appearance page's. Until then a site with the old default shows it, colon included, under the name.
- **Distances on phones:** the prototype's settings note says the launcher keeps 18 px on phones; the widget keeps the site's distances on phones too, as today, so a launcher moved above a cookie bar or a bottom menu stays there.
- **The admin's preview:** the classes `.kimaai-chatbot-container` and `.kimaai-chatbot-body` are kept. A preview frame narrower than 441 px shows the phone layout (the window on the whole frame) also under "Desktop".
- **Downgrade:** a site created on this version stores `KimaMark`, which 1.5.x does not know; its widget fails to render there (React error #130). Existing sites keep their stored icon and are not affected.
- The composer's field is named only by its placeholder (axe `label` when the placeholder is empty): WD-6.

## WD-6: Conversation and composer (build notes)

Built 2026-11-15 on `wd/conv`. Looked at in WordPress Playground (WordPress latest, PHP 8.3, no networking, Pro forced through the e2e option, the chat routes answered in the browser with invented content for a made-up outdoor shop) and next to the prototype's stories in Storybook. Shots in the WD-6 shots folder: `before/` on the base commit, `after/` with this item, `prototype/` the stories at 1440 and 390 px.

**What changed in the conversation** (`src/chatbot/components/conversation/`, the components named in the ownership table, `styles/_conversation.scss`):

- **Messages.** The visitor's message is the brand fill (its edge where the fill would melt into the panel, none in Minimal). Answers are plain text beside a 26 px avatar in Calm and Minimal and tinted bubbles in Bold and Glass, as the styles say (`data-kimaai-style`). Markdown: paragraphs, headings, lists, links in the link colour, inline code, code blocks (language, copy, scrolling lines) and, new, **tables** (GitHub style, in `MarkdownMessage`, scrolling in their own box that the keyboard can reach). Density compact: 14 px and spacing × 0.78. A message rises 6 px when it arrives; it does not fade, so its contrast holds from the first frame (axe measured a half-faded bubble).
- **Times.** The history now says when each row was stored (`createdAt`, UTC, from `FormatsAssistantHistoryMessages`). The conversation shows a divider with the time (the day too, when not today, in the page's language) where it starts and where 30 minutes or more passed between two messages. A message just sent has no time until the history returns.
- **Thinking and streaming.** While the answer is on its way: a polite status in words, "Looking for an answer…", with a spinner and a shimmer that stop with reduced motion. The prototype's "Searching example-shop.test ✓, Reading 3 pages…" needs steps the server does not send; saying "searching the site" on a site without a knowledge base would not be true, so the line says what is certain. While the text streams: a caret after the last words, and no sources, copy or feedback until it ends.
- **Stop.** Send becomes Stop (a square) while an answer is on its way. Stop aborts the request (`AbortController`, a `signal` in both transports): a streamed answer keeps the text that arrived, one stopped before any text is dropped, and no error shows. The server may still finish and store the answer; the next history load shows it. The field stays open while the answer arrives, so the next question can be typed; Enter does not send until the answer has ended.
- **Errors.** A failed answer is a card (`role="alert"`) with the reason, Try again (sends the same question again in place of the failed attempt, `retryMessage`; focus goes to the field) and Talk to a person (when handoff is on).
- **Sources.** The `sources` renderable shows as chips under the answer, numbered for the cited sources, and "Related pages" after them (`AnswerSources`). A chip opens the source inside the panel (`SourceView`, a dialog over the conversation: breadcrumb, title, the passage the answer used, the other sources of the answer, Open the page, the address; Esc and Back return focus to the chip). The "matching words marked" of the prototype need the matched words, which the sources do not carry; the passage is shown unmarked. `SourceList` (WD-7's renderable) stays in the registry and in the search answer box.
- **Cards.** An answer's renderables (WD-7's cards) come after its text, not inside the bubble, and an answer with a card has no copy or rating row, as in the prototype.
- **Copy and feedback.** One action row under a finished answer: Copy (an icon, "Copied" said through a status), Helpful and Not helpful. Not helpful opens a card with reasons as chips (Not correct, Didn’t answer my question, Too long, Something else), "Tell us more (optional)" and Send; the reason and the comment are stored together as the rating's comment ("Not correct: …"), so the API and the stored rows stay as they are. The rating locks after the thanks, as before. Outside the action row (the search answer card) the same buttons take the engine's colours too.
- **Consent.** A card above the field with the site's text and "Accept and start"; the field and the suggestions are shown but wait (disabled, the suggestions `aria-disabled`); a click on a suggestion points to the card (a ring, focus on the button). The AI notice stays in the footer before consent too.
- **Handoff.** "Talk to a person" is a quiet button under the chat once there is an answer (it was a row from the start), and in the error card. `requestHumanAction()` is exported from `HandoffButton.jsx` for the header menu (WD-5).
- **Rating at the end (CSAT).** A sheet from the bottom of the panel: grab handle, "How was this chat?", five stars (the pressed one is the rating, the stars up to it are filled, each named "Rate n out of 5"), "What could we do better? (optional)", Not now and Send rating. It is `ChatDialog` (WD-5's primitive, unchanged) with its own class.
- **Quick actions.** Before the first message: full-width rows with an icon (by the action's type) and a chevron that turns in right to left. After an answer: chips.
- **Composer.** One rounded field that grows with the text up to 140 px (one line to start), Send in the brand colour (off while empty), Stop while answering, the keyboard hint for screen readers, a visible label for screen readers (the placeholder), and the limit the server applies (5,000 characters, `maxlength`, with a count once 90 % is reached; 500 for comments). **Voice-ready:** an empty actions area before Send (`.kimaai-chatbot-composer__actions`, the `actions` prop of `Composer` and `ComposerInput`) where WD-10 puts dictation and Voice. The footer (AI notice with its spark, the site's note, the credit) is quiet and centred under the field.
- **The admin assistant** uses the same conversation in wp-admin and keeps its look: the new rules name the chat root (`:is(#kimaai-chatbot, [data-kimaai-chatbot])`, a `:host` rule in the shadow root) or the admin preview's frame (`.kimaai-chatbot-preview-inner`), which the admin assistant has neither of; the markup keeps the class names its CSS reads. It keeps "Start new session" in its composer; the widget's composer has no clear button: "New conversation" belongs in the header menu (WD-5). Stop works there too (both transports).
- **Old rules.** The old rules of these components in `index.scss` stay: the admin assistant and the attention popover still read them. The new rules win by the root's weight; where an old rule has `!important` (the quick action margins, padding and line height, which the popover still needs), the new rule has it too, in the conversation only.

**Carried-over sites.** They are Bold, so their answers are tinted bubbles and the visitor's messages the brand fill, as before; with `data-kimaai-legacy-style` the messages keep today's shape (12 px corners, the corner at the avatar square). The colours come from the carried parts through the engine. The layout around them is the new one (actions in one row, chips for sources, the new composer), as the redesign intends. Checked with a version 2 theme stored without a look and migration `Version2026111510` run, in Playground: Minimalist light and Neon dark came out Bold with the legacy flag and show the shapes above. An untouched Classic theme (default preset, no colours of its own) came out as Calm in this set-up, on the base commit as on this branch, so its widget took the new default look; that is WD-3's mapping (or the way the script stored the options), not this item's, and is worth a look in WD-11. The 1.5.13 storage was not tried again here: this item does not change the carry-over.

**Accessibility.** A finished answer is announced once by a polite status ("Answer ready."), not word by word; the answer's text is not repeated in the live region, so it is on the page once (the search answer box does the same). Thinking is a polite status, errors an alert. Focus: the source view and the rating sheet take focus and give it back; Not helpful focuses its first reason; Try again focuses the field. Every control has a name; targets are 32 to 46 px; the focus ring is 2 px in the link colour; forced colours keep the field's, the chips' and the visitor message's borders. Text on the engine's raised surface uses the text colour, not the secondary grey, which the engine checks only on the panel (axe found the code block's language at 4.1:1).

**Two things to know about the shadow root's copy of the rules** (WD-4 reads them back through the CSSOM): a shorthand with a variable next to one of its own longhands is lost there (the thinking line's gradient vanished), so such rules use longhands; and the conversation's scroller is positioned, because visually hidden texts (absolutely positioned) otherwise stretched the panel's scroll height and a dialog's focus scrolled the whole panel.

**Storybook.** The chatbot stories' frame (`.storybook/preview.jsx`) now carries the engine's variables and flags for a new site's look, so the production components show the new design there. "Chatbot/Components": Chat Message (thinking, streaming, error with Try again and Talk to a person, sources with a table and a code block), Chat Input (Stop, waiting for consent), Quick Actions Bar (starters, chips); the App-based stories (streaming, error, consent, feedback, CSAT) show the rest.

**Tests.** Jest: `ConversationScreen` (starters and consent, sources and the source view with focus, the action row only after streaming, thinking, the error card, handoff, time dividers, the announcement), `ComposerInput` (Stop, consent, the count, the actions area, growing), `Composer`, `ChatMessageFeedback` (reasons), `ChatCsatModal` (stars), `GDPRConsentBox`, `useConversationController` (Stop, Try again), tables in `MarkdownMessage`; tests of WD-8's search answer box follow the new button names. PHPUnit: the history's times. Playwright, updated by the new names and flows: `chatbot-feedback`, `chatbot-sources` (the chips, the source view, its links and axe in it), `chatbot-streaming` (new: Stop keeps what arrived), `chatbot-search-answer` (button name), and the page object (`Accept and start`).

## WD-10: Voice entry points (build notes)

Built 2026-11-15 on `track/WD-widget-design`, from the prototype's "Widget design/Voice mode" stories. Placeholders for VC: nothing reaches the microphone, plays audio or sends a request.

- **The feature.** `voice` is in the registry as hidden, tier Pro (research, "Free and Pro": speech costs per minute). `ChatbotAssets` tells the widget `voiceEnabled` (`Features::isEnabled('voice')`), which the config already read as `features.voice.enabled`. Hidden, the widget renders none of it; with `KIMAAI_FEATURES_PREVIEW` (the e2e and WP-CLI setups) or the `kimaai_feature_status` filter it shows. The plan is not checked yet: VC decides whether a free site sees voice.
- **One way in.** `ChatbotShell` provides `VoiceContext` (`src/chatbot/components/voice/`) only while voice is on and the preset is not the admin assistant; the entry points read it and render nothing without it, so the admin assistant, the search answer and the Ask-AI dialog's chat stay as they are.
- **Entry points:**
    - the empty message field: the dictation microphone and the Voice pill take Send's place (prototype: "empty: dictation and Voice; with text: Send; while answering: Stop"); they wait (disabled) while consent is required;
    - an answer's action row: Read aloud after Copy (only on a finished answer without a card, as Copy);
    - the header's ⋯ menu: "Voice conversation" (not while consent is required);
    - each opens the voice screen in the panel: the header says "Kima · Voice", the conversation makes room, focus goes to the screen's heading. It says "Voice is coming soon. Until then, type your question." with Type instead, which returns to the conversation and its field. The intro's three promises about the microphone and the audio are left out of this screen, since nothing works yet (VC decides their wording with the consent research).
- **The screens for VC** (`VoiceMode`): intro (with the three points, Start, Type instead, the privacy link), connecting, listening, thinking, speaking (the caption and the transcript), microphone off, blocked (Try again) and not available, each with its state in words, the orb in the brand colour, Transcript, Mute, End and Type. The end of a voice conversation is drawn in the conversation: a "Voice conversation" divider before the first spoken turn and "Spoken" under each (a message's `spoken` flag, which VC sets). The prototype's "· 1 min" needs a duration VC will have. The admin preview's Voice state (WD-9) shows once the feature is not hidden, as before.
- **Styles** in `styles/_voice.scss`, on the engine's `--kimaai-w-*`, named by the chat root (a `:host` rule in the shadow root) and the Storybook frame. Reduced motion stops the orb, the rings and the dot; forced colours keep the round controls' borders. The End control is the prototype's red with a white icon (3.9:1, an icon needs 3:1).
- **Tests.** Jest (`VoiceEntryPoints.test.jsx`): hidden or not told, nothing renders and Send stays; on, the field shows dictation and Voice, then Send with text; each of the three entry points and Read aloud open the screen, which says voice is coming, with no `getUserMedia` call and no request; Type instead returns focus to the field; consent keeps them waiting; the spoken turns; axe on the screen; the states of `VoiceMode`. `ComposerInput.test.jsx` follows the new place of the actions. PHPUnit: `voice` is hidden and Pro. Storybook: "Chatbot/Voice mode", every state, the entry points, the screen as it opens today, the end, dark and right to left.
- **Storybook frame.** The chatbot stories' frame (`.storybook/preview.jsx`) was 34 px high, so the floating window of every App-based story ("Frontend preset" and the rest) was placed above it, off the canvas, since WD-5. The frame is now as high as the screen.

## WD-11: Real WordPress pass (build notes)

Checked 2026-11-15 on `track/WD-widget-design` after WD-3 to WD-10, in WordPress Playground (WordPress latest, PHP 8.3, no networking, the e2e mu-plugins, every other origin refused, chat and answer routes answered in the browser with invented content for a made-up outdoor shop; switches for theme, colours, direction, plan and voice read from cookies by a scratch mu-plugin). Shots in the WD-11 shots folder: `after/` (89 front-end shots), `carry/` and `carry2/` (sites carried over), `askai/`, `auto/`, `longnote/`, `admin*/` (the Appearance page), `sb-voice/` and `proto/` (Storybook), and `sheet-*.png` contact sheets of them.

**What was looked at.**

- **Themes:** Twenty Twenty-Five and a classic theme with its own opinions (Georgia, `html { font-size: 62.5% }`, square black uppercase buttons, yellow fields). **No page builder theme:** none can be installed without network (Elementor, Astra and the like are downloads), so that case is not checked.
- **Every surface, new site (Calm, Light, `#5250e6`):** launcher, attention popover, window, header and menu, welcome, conversation with sources and the source view, thinking, Stop, the error card with Try again and Talk to a person, Not helpful with reasons, consent, the handoff card, the rating sheet, every renderable (lead form, booking, products, ticket), the voice entry points and screen with `voice` previewed, Ask AI (results and chat) and the search answer.
- **Styles and colours:** Calm, Bold, Glass and Minimal on `#5250e6`, sun yellow `#f5c518`, near-black `#111111` and `#1f7a4d`, each light and dark (32 shots); compact with sharp corners; the launcher on the left.
- **Colour modes:** Light, Dark, and Match the site (below) on a light and a dark site, each with a light and a dark visitor.
- **Persian right to left** (welcome, conversation, Bold dark, menu, classic theme, voice screen) and **390 px** phones (closed, popover, welcome, conversation, menu, consent, rating, source view, error, renderables, voice, Glass dark, the classic theme, Persian).
- **Free** (conversation and welcome) and Pro.
- **Carried-over sites, through the real path:** the options a 1.5.13 site stores (the schema's defaults stored whole by 1.5.13's own config, its version 2 theme and its six colour fields) and the options a `development` site stores, without a look, then a page request that runs the schema upgrade: Classic light, dark and System, Minimalist, Glossy, Neon light and dark, custom colours with a navy header and coral visitor messages on Pro and on free, and from `development` Neon dark, System and custom colours on free. Every one came out Bold in its colours, kept its icon, "Talk to our AI agent:" and its greeting, and got no welcome heading.
- **The Appearance page:** the live preview in every state (Closed, Welcome, Answer, Voice), desktop and phone, light and dark admin, right to left, the card at 1280, 1440 and 1920 px, free and Pro.
- **Prototype stories** at 1440 px next to the production widget ("Widget design/Widget" conversation, Minimal, Bold; "Voice mode").

**Known items:**

1. **Classic coming out as Calm (WD-6):** not a carry-over fault. WD-6's script stored an untouched Classic theme as `theme: {}`, which PHP decodes to an empty array, which is falsy, so the script kept the new site's look it had built from the defaults. Stored as 1.5.13 and `development` store it, every site becomes Bold (checked in Playground through the schema upgrade, and in PHPUnit: `testAnUntouchedSiteBecomesBoldAndKeepsItsTexts`).
2. **The line under the name:** the default is now "AI assistant" for new sites. Existing sites keep theirs: 1.5.13 and `development` store the schema's defaults whole on their first request (`maybeUpgradeOnSchemaChange`), so every existing site has "Talk to our AI agent:" (in the language it was stored in) stored and keeps it, colon included. No migration is needed.
3. **The welcome heading:** new sites get "Hi, how can I help?" (the prototype has a heading); the greeting under it is now "Type your question below to get started." for new sites, so the two do not greet twice. The key is new, so `LookCarryOver::upgradeOptions()` stores it empty for an existing site, in the same place it writes the look (schema upgrade, migration 2026111510, import of an older export): its welcome stays as it was.
4. **Talk to a person under the chat:** the prototype has no such row (the menu, the error card and the handoff card), so it is gone; its styles too. `chatbot-handoff.spec.ts` asks through the menu now (`talkToAPerson()` in the page object).
5. **Dead code:** `QuickActionsBar`'s `variant="starters"` and its icon and chevron, their rules and the right-to-left chevron selector, and its Storybook variant are removed. **`.kimaai-chatbot-preview-inner` is not dead:** the Storybook frames of the chatbot stories carry it (`.storybook/preview.jsx`, the Renderables and primitives stories), so the rules that name it style the production components there; kept. No other old title rule was found: a scan of every class in the widget's stylesheets against the code found only `kimaai-button-timer` (index.scss, from the clear-history button before this track) unused; left, as it predates the track.
6. **The preview's Desktop:** a card narrower than 480 px draws the mock site at 480 px and scales it down, so the widget sees a desktop viewport and shows its desktop layout (the window above the launcher), as on a site; the phone stays at its own width.
7. **Schema fixture:** `tests/storybook/admin/chatbotSchema.json`'s appearance is dumped again (WD-5's shell settings, the new defaults, Match the site). Storybook builds (below).
8. **e2e,** on the Mac with the repo's Playwright config and two workers: every `chatbot-*` spec (but the paid one), `lead-privacy`, `admin-settings` and `home`, 112 tests: 109 passed and one skipped in the first run; the two hostile-CSS tests of `chatbot-shadow-root.spec.ts` failed, because with `voice` previewed (the e2e setup) the empty field shows the voice entry points in Send's place. The spec now reads whichever the field shows; the spec's 5 tests pass. No test was flaky. The specs changed in this item: `chatbot-handoff` (the menu), `chatbot-settings` (Match the site), `chatbot-shadow-root`, and the page object.

**Fixed besides:**

- **The Ask AI dialog under the launcher.** The dialog's root and the floating widget's root both stack at 99999 and the floating one comes later in the page, so on a phone the launcher sat on the dialog's Send button, and on a desktop it stayed bright over the backdrop. The dialog's root now stacks at 100000.
- **The preview cut off the notes under the field** (owner, on his site). The preview fixed the conversation's height (240 px, 280 px on the phone), so a long AI notice, a long note under the chat or the credit ran out of the window. The conversation now takes what the header, the field and the notes leave; checked in every state, desktop and phone, with a four-line note and the credit. The front end had no such clipping (checked with the same note at 1440 and 390 px).
- **Match the site (owner).** Auto followed each visitor's system setting, which put a dark widget on sites that have no dark mode. It is now "Match the site" (stored as `auto`): `siteScheme.js` reads the page the widget sits on (the first background of `body`, then `html`, that is not transparent; without one, the page's text colour, then the root's `color-scheme`; dark when white text would read better on it) and puts `data-kimaai-scheme="light|dark"` on every chat root in that mode: the floating widget, inline chats, the Ask AI dialog and the search answer. It looks again when a class, style or data attribute of `html` or `body` changes (a theme's dark switch), when the system setting changes (a theme that follows it changes its background), on `load`, and once more after a transition would be over. The printed dark colours and the stylesheet's dark rules read the attribute instead of `@media (prefers-color-scheme: dark)`, at the same weight as before (`:where()`), and the shadow root's adaptation keeps such a `:where()` on the host. Before the script runs the widget is light. The Appearance page names the option "Match the site" with "light or dark, following your site's own colours", and the preview's note says what visitors see. A carried-over site that had System now follows its site: light on a light site with a dark-mode visitor, its carried dark colours on a dark site.
- **Storybook frame** (WD-10's commit): the App-based chatbot stories rendered off the canvas since WD-5.

**The answer avatar** (owner, after the pass): new sites get the prototype's spark beside answers, a new option "Spark" (`mark`) of the answer avatar setting and its default; it is drawn on the brand's accent, as the header's avatar. Every existing site stores its own value (None by default in 1.5.13 and `development`) and keeps answers without an avatar (PHPUnit `testANewSiteGetsTheSparkBesideAnswersAndAnExistingSiteKeepsNone`).

**What looked right and was left.** Source chips with long titles take a line each (they wrap as the prototype's do). The popover's two chips wrap under each other when the first is long. Product pictures given as `data:` URLs are not shown (only http, https and relative URLs are, by design). Persian without translations shows the English texts with their punctuation turned, as expected until the strings are translated.

**Tests.** Jest: `siteScheme.test.js` (a light page, a dark page, a transparent body over a dark `html`, light text without a background colour, nothing set, and a theme toggling a `.dark` class with roots in Match the site and in Light), the shadow adaptation of a `:where()` condition, the preview's scale and its notes, the conversation without the handoff row. PHPUnit: the carry-over of an untouched 1.5.13 site through the schema upgrade (Bold, its stored line under the name, no heading, a heading set later stays), a new site's texts, Auto's dark colours on the attribute and never in a `prefers-color-scheme` block. `npm run check` passes for every commit. Storybook builds (`storybook build` to a scratch folder); the Appearance stories show the new schema and Match the site. The POT is generated again with the strings of WD-10 and WD-11.

**Left:**

- A page builder theme (no network in Playground).
- Firefox and Safari: checked in Chromium only.
- Match the site reads the page once the script runs; until then (the first paint) the widget is light, so on a dark site with Match the site a closed launcher can show its light colours for a moment. A server-side hint (the theme's `theme.json` background, for block themes) could set it earlier.
- The old `kimaai-button-timer` rule.
