<!-- markdownlint-disable MD024 -->

# UI refactor (UI-1): duplication map and commit order

Status: research for track UI, read-only analysis of `track/DS-design-system` at `92d63de0` (2026-11-13). Every path is relative to the plugin root `/Users/nabi/Desktop/netz/kimaai-dev/wp-content/plugins/kimaai`. Line numbers are from that commit. Nothing was edited or built.

## Summary

- **Modals.** The code has 7 direct `Modal` imports: 6 call sites plus `KimaModal` itself. Four more modal bodies are hosted by DataViews `RenderModal`. There are 2 custom overlays (`ChatCsatModal`, the `ShowLogFile` full screen) and 3 `window.confirm` calls. `KimaModal` should win in the admin. A small `ConfirmDialog` on top of it would replace five near-identical confirm dialogs. The chatbot needs its own WordPress-free `ChatDialog`.
- **Buttons.** `KimaButton` is a pass-through over the WordPress `Button`, with one behaviour change: `iconPosition` defaults to `'right'`. Direct `Button` is imported in 22 files. The frontend chatbot bundle is not free of WordPress components today: it declares `window.wp.components` and ships `KimaButton`, the WordPress `Icon`, `AdminAssistantShell` (Button and Notice) and the admin `TextareaWithButton`/`TextareaField`. The chatbot needs a native `ChatButton` and a lint boundary.
- **Copy.** `useCopyToClipboard` is the engine and `CopyButton` the admin primitive. `McpApp` has its own `CopyButton` (no fallback, no error state). `SettingsJsonModal` has a hand-built one. The chatbot footer correctly uses the hook with a raw button.
- **Colour fields.** `ColorField` wins. `SingleColorPalette` and `MultipleColorPalette` have no first-party config use. Their names are public registry keys, though.
- **Repeatables.** All 8 repeatable pages use `view: 'table'`, so `RepeatableTable` wins. `RepeatableField` and the card view are unreachable from first-party config.
- **Aliases.** `ChatInput`, `MessageItem` and `ChatMessageRenderables` are one-line wrappers. `MessageItem` points backwards to the old `ChatMessage`.
- **Logo and KimaIcon.** They are not duplicates. `KimaIcon` mixes a persisted name→asset registry with interface icons and drags `@wordpress/components` into the frontend.
- **Dead code.** `KimaAIPro.php` is unreferenced and would fatal if loaded. `build/flow*` is a local leftover from an unmerged branch, but release ZIPs would ship it. Removing the legacy colour fields needs a settings migration. New dead code found: the `chatbot-admin` webpack entry, `ListPanel.jsx`, `FetchDeletePanel.jsx`, `CustomSelectField`, and `JsonBlock` (which pulls highlight.js and its CSS into the frontend bundle). `@base-ui/react` is gone from `package.json` but stays in the lock file as a transitive dependency of `@wordpress/ui`.

---

## 0. Ground rules found in the code

- **Entry points** (`webpack.config.js` 7-11): `admin`, `chatbot` (frontend), `chatbot-admin`. Both chatbot entries mount the same `App`. The admin assistant actually mounts inside the admin bundle (`src/admin/components/AdminAssistantRail.jsx` 1-29).
- **The frontend bundle depends on wp-components.** `build/chatbot/index.asset.php` lists `wp-components` and `wp-primitives`, and `app/ChatBot/ChatbotAssets.php` 158-180 enqueues them on the public site. What pulls them in:
    - `src/global/components/KimaButton.jsx` 2, through `ChatCsatModal`, `ChatMessageFeedback`, `GDPRConsentBox`, `QuickActionsBar` and `TextareaWithButton`.
    - The WordPress `Icon` in `ChatMessageFooter.jsx` 2, `FloatingAttentionPopover.jsx` 4, `ChatbotHeader.jsx` 2 and `src/admin/components/KimaIcon.jsx` 1.
    - `src/chatbot/components/Chatbot.jsx` 1 imports `AdminAssistantShell` statically (Button and Notice, `AdminAssistantShell.jsx` 4). Its class names are present in `build/chatbot/index.js`.
    - `src/chatbot/components/conversation/Composer.jsx` 1 imports the admin `TextareaWithButton`, which uses `TextareaField` (WordPress `TextareaControl`) and `FieldWrapper` (`Notice`, `ExternalLink`).
- **Barrel side effect.** `ChatMessage.jsx` 2 imports `MarkdownMessage` from the `@global/components` barrel. That barrel also exports `JsonBlock`, which imports `highlight.js/styles/github.css`. Result: `build/chatbot/index.js` contains highlight.js (`registerLanguage` ×3) and `build/chatbot.css` contains 45 `hljs` rules. `JsonBlock` has no users.
- **Not in the frontend bundle** (only reachable from `createWpAdminAssistantConfig`): `AdminSessionsScreen`, `AdminHomeScreen`, `AdminHelpScreen`, `ChoiceCard`, `SecureSecretInput`, `WorkflowCta`.
- **Recommendation for every family:** decide the boundary "nothing under `src/chatbot` imports `@wordpress/components`, `@wordpress/icons`, `@admin/*` or the `@global/components` barrel". Enforce it with an ESLint `no-restricted-imports` override for `src/chatbot/**` in `.eslintrc.js` (no such override exists today). It is simpler than a rule based on bundle reachability and it is lintable.

---

## 1. Modals

### Map

| # | File | Lines | Mechanism | Purpose | Bundle |
| - | ---- | ----- | --------- | ------- | ------ |
| 1 | `src/admin/components/atoms/KimaModal.jsx` | 1-45 (WordPress `Modal` at 22-41) | Wrapper: `title`, `description`, `onClose`, `size` sm/md/lg, `footer`, `footerLeading`, `isDismissible`, `shouldCloseOnClickOutside`; passes the no-op `__experimentalHideHeader` | Primitive | admin |
| 2 | `src/admin/components/Fields/RepeatableTable.jsx` | import 5, use 322-354 | `KimaModal` | Add/edit entry, footer Delete/Cancel/Save use raw WordPress `Button` 329, 336, 339 | admin |
| 3 | `src/admin/components/ChatbotHistory.jsx` | import 5, use 248-273 | WordPress `Modal` | Confirm deleting sessions (Notice error 251-255, Cancel 259, Delete 262) | admin |
| 4 | `src/admin/components/ChatbotConversationPanel.jsx` | import 3, use 265-281 | WordPress `Modal` with `className="!w-[96vw] !max-w-[96vw]"` | Full-screen transcript, opened by `Button` 145 | admin |
| 5 | `src/admin/components/ExportSettings/SettingsJsonModal.jsx` | import 1, use 34-68 | WordPress `Modal` wrapper with its own notice, toolbar and copy footer | JSON viewer | admin |
| 5a | `src/admin/components/ExportSettings/SettingsImportExport.jsx` | 284-327 (export), 329-385 (import) | uses #5 | | admin |
| 6 | `src/admin/components/Embedding/ListPanel.jsx` | import 3, use 306-310 | WordPress `Modal` | Vector details. **The file is dead (no importers)** | none |
| 7 | `src/chatbot/components/screens/admin/AdminSessionsScreen.jsx` | import 1, Delete 313-331, Revert 335-358 | WordPress `Modal` ×2 | Confirm dialogs, Cancel and primary destructive buttons | admin assistant only |
| 8 | `src/admin/components/Embedding/Sync/SyncPanel.jsx` | 283-292 `SyncModal` (`modalSize: 'fill'`), 301 `DeleteModal` | DataViews `RenderModal` (DataViews owns the frame) | Bodies in `Sync/SyncModal.jsx` and `Sync/DeleteModal.jsx` (footer `KimaButton` 202-203) | admin |
| 9 | `src/admin/feedback/pages/Csat.jsx` | `RenderModal` 172-205 | DataViews | Delete confirmation body, Cancel 185, red primary 188 | admin |
| 10 | `src/admin/feedback/pages/MessageFeedback.jsx` | `RenderModal` 223-256 | DataViews | Same confirmation body as #9 (copy-paste) | admin |
| 11 | `src/chatbot/components/ChatCsatModal.jsx` | 61-112 (overlay 62-74 `role="button"`, dialog 76 `role="dialog" aria-modal`) | Custom overlay, styles `src/chatbot/index.scss` 512-640 | CSAT survey | **frontend** |
| 12 | `src/chatbot/components/FloatingAttentionPopover.jsx` | 53 `role="dialog"` | Popover (not modal) | Launcher prompt | **frontend** |
| 13 | `src/admin/components/ShowLogFile.jsx` | 122-137 (`fixed inset-0 !z-[999999]`) | Custom full-screen overlay, no Esc handler in this block despite the hint text | Log viewer | admin |
| 14 | `src/admin/components/ShowLogFile.jsx` | 41, 50, 59 | `window.confirm` ×3 | Delete one, clear all, delete all | admin |
| 15 | `src/admin/Layout.jsx` | 92-98 | Raw `<button>` backdrop | Assistant rail scrim | admin |

CSS hooks: `src/admin/index.css` 1236-1262 (`.kimaai-modal*`) and `src/global/wpAdmin.css` 42, 288-310, 378 (`.components-modal__*` brand overrides).

### Recommendation

- **Winner (admin): `KimaModal`.**
    - Rename `onClose` to `onRequestClose`, or keep `onClose` and accept both, so migrating sites is a straight rename.
    - Add size `'fill'` (needed by #4; #5 maps to `'lg'`).
    - Drop `__experimentalHideHeader`.
    - Wire `description` to `aria-describedby`.
- **New atom `ConfirmDialog`** on `KimaModal`: `title`, `message`, `children` (for example a warning Notice), `confirmLabel`, `isDestructive`, `isBusy`, `error`, `onConfirm`, `onClose`, with `shouldCloseOnClickOutside={!isBusy}`.
    - Replaces #3 and #7 (both dialogs), optionally #14.
    - For DataViews (#9, #10, `DeleteModal`) add `ConfirmBody` (the same content without the frame), because DataViews renders the modal itself.
- **#5 `SettingsJsonModal`** becomes a `KimaModal` with `size="lg"`. Its footer uses `CopyButton` (see family 3) and its `footerLeft`/`footerRight` map to `footerLeading`/`footer`.
- **#4** becomes `KimaModal size="fill"`.
- **#6** is deleted with dead code (family 10).
- **Chatbot:** new `src/chatbot/components/ui/ChatDialog.jsx`, native and free of WordPress components, owning:
    - `role="dialog"`, `aria-modal`, and `aria-labelledby` pointing at the title (missing today in #11);
    - Esc to close (missing);
    - focus moved into the dialog and returned on close (missing);
    - a scrim as a plain `div` with a click handler (the current `role="button"` overlay at 62-74 is an a11y smell).

  `ChatCsatModal` uses it. With the strict boundary, `AdminSessionsScreen` #7 moves to `ChatDialog` instead of `KimaModal`.
- **#13** keep, but add an Esc listener and `role="dialog"`. Not worth a primitive.

### Risks

- `AdminSessionsScreen.test.jsx` 94 and 143-157 query `getByRole('dialog', {name: 'Delete session' | 'Revert session'})`. Any replacement must keep the accessible name.
- `ShowLogFile.test.jsx` 67-143 stubs `window.confirm` and asserts the three messages. Moving #14 to `ConfirmDialog` means rewriting that test (do it, or leave #14 out).
- `KimaModal` defaults `shouldCloseOnClickOutside=false`. #3, #4 and #7 currently close on outside click, so pass it explicitly.
- e2e `tests/e2e/pages/ai-services.page.ts` 36-44 uses `getByRole('dialog')` and then the `Add` button (RepeatableTable modal).

### Tests that cover it

- Jest: `tests/js/admin/components/Fields/RepeatableTable.test.jsx` (dialog ×5), `tests/js/admin/components/RepeatablePage.test.jsx` (dialog ×3), `tests/js/chatbot/components/AdminSessionsScreen.test.jsx` (6 tests), `tests/js/admin/components/ShowLogFile.test.jsx`.
- No tests for `ChatbotHistory`, `ChatbotConversationPanel`, `SettingsImportExport` or `ChatCsatModal`.
- Storybook: no `KimaModal` or CSAT story. `tests/storybook/chatbot/Chatbot.stories.jsx` 75 and `AdminChatbot.stories.jsx` 40 only set `csatOpen: false`. Add `Admin/Primitives` stories for `KimaModal`/`ConfirmDialog` and a `ChatDialog` CSAT story.
- e2e: `ai-services.page.ts` 35-44, `admin-settings.spec.ts` 172 (sessions).

---

## 2. Buttons

### Primitives

| Component | File | Lines | What it really is | Users |
| --------- | ---- | ----- | ----------------- | ----- |
| `KimaButton` | `src/global/components/KimaButton.jsx` | 1-24 | `forwardRef` pass-through to the WordPress `Button`; adds `text` and **defaults `iconPosition='right'`** (WordPress defaults to left) | 19 files (below) |
| `SaveButton` | `src/admin/components/SaveButton.jsx` | 1-36 | Sticky save bar: Save (`data-testid="save-button"`) and "Discord Changes" (`data-testid="discord-changes-button"`) | `FieldRenderer.jsx` 438 and 516, `RepeatablePage.jsx` 199 |
| `TriggerButton` | `src/admin/components/TriggerButton.jsx` | 1-16 | `KimaButton` that fires `doAction('kimaai_trigger_button_click')` (public JS hook) | Registry only (`FieldRenderer.jsx` 11 and 65); no PHP config uses it |
| `SidebarButton` | `src/admin/components/SidebarButton.jsx` | 1-53 | Sidebar toolbar: collapse `Button` 15-27 with the WordPress `Icon` `arrowLeft`, `AdminThemeToggle`, assistant `Button` 34-47 with `KimaIcon` | `src/admin/Layout.jsx` 3 and 67 |

### Direct `Button` from `@wordpress/components`

Import line, then `<Button` lines:

- `src/admin/components/ChatbotConversationPanel.jsx` 3; 145
- `src/admin/components/ChatbotHistory.jsx` 5; 67, 259, 262
- `src/admin/components/Embedding/CollectionsPanel.jsx` 7; 106, 181
- `src/admin/components/Embedding/FetchDeletePanel.jsx` 6; 59, 63 (dead file)
- `src/admin/components/Embedding/HealthPanel.jsx` 4; 115
- `src/admin/components/Embedding/ListPanel.jsx` 3; 198, 201, 256 (dead file)
- `src/admin/components/Embedding/QueryPanel.jsx` 3; 313, 377, 512
- `src/admin/components/Embedding/Sync/SyncModal.jsx` 4; 453, 462, 1129, 1132
- `src/admin/components/ExportSettings/SettingsImportExport.jsx` 2; 319, 367, 371
- `src/admin/components/ExportSettings/SettingsJsonModal.jsx` 1; 58
- `src/admin/components/Fields/RepeatableTable.jsx` 2; 19, 31, 43 (Pager), 191, 194, 207 (row actions), 329, 336, 339 (modal footer)
- `src/admin/components/Fields/TextField.jsx` 2; 50 (password reveal)
- `src/admin/components/SidebarButton.jsx` 1; 15, 34
- `src/admin/feedback/components/AdminNotesSidebar.jsx` 4; 97, 102, 108
- `src/admin/feedback/pages/Csat.jsx` 3; 185, 188
- `src/admin/feedback/pages/MessageFeedback.jsx` 3; 236, 239, 436
- `src/admin/mcp/McpApp.jsx` 3; 19, 190, 219
- `src/chatbot/components/Renderables/ChoiceCard.jsx` 1; 17 (admin assistant only)
- `src/chatbot/components/Renderables/SecureSecretInput.jsx` 1; 46 (admin assistant only)
- `src/chatbot/components/Renderables/WorkflowCta.jsx` 1; 14 (admin assistant only)
- `src/chatbot/components/screens/admin/AdminSessionsScreen.jsx` 1; 237, 240, 279, 290, 298, 317, 320, 344, 347 (admin assistant only)
- `src/chatbot/components/shell/AdminAssistantShell.jsx` 4; 88 (**in the frontend bundle** through `Chatbot.jsx` 1)

### `KimaButton` users (`<KimaButton` lines)

- Admin:
    - `Embedding/Sync/DeleteModal.jsx` 202, 203
    - `ExportSettings/ImportExportBox.jsx` 29
    - `Fields/ColorField.jsx` 68 (swatch), 89
    - `Fields/RepeatableField.jsx` 59, 71, 87, 99
    - `Fields/RepeatableTable.jsx` 235, 253
    - `SaveButton.jsx` 14, 22
    - `ShowLogFile.jsx` 132, 148, 154, 158, 162, 192, 200, 219, 232
    - `TriggerButton.jsx` 13
    - `atoms/CopyButton.jsx` 19
    - `feedback/pages/Overview.jsx` 334
    - `wizard/AlreadyConfiguredWarning.jsx` 24, 36
    - `wizard/RepeatableSingleBlock.jsx` 166
    - `wizard/WizardApp.jsx` 389, 392, 394
    - `wizard/WizardHeader.jsx` 24
- **Frontend chatbot:**
    - `ChatCsatModal.jsx` 81, 107, 109
    - `ChatMessageFeedback.jsx` 84, 94, 123, 125
    - `GDPRConsentBox.jsx` 74
    - `QuickActionsBar.jsx` 24
    - `src/admin/components/Fields/TextareaWithButton.jsx` 109 (used only by `Composer.jsx` 42, so it is frontend too)

### Raw `<button>`

| Bundle | File:line | Purpose | Recommendation |
| ------ | --------- | ------- | -------------- |
| **Frontend** | `src/chatbot/components/ChatMessageFooter.jsx` 42 | Copy message (WordPress `Icon` `copy`) | `ChatButton` icon variant with Lucide `Copy` |
| **Frontend** | `src/chatbot/components/FloatingAttentionPopover.jsx` 54 | Dismiss (`aria-label="Dismiss"` is **not translated**) | `ChatButton` with Lucide `X` and `__()` |
| **Frontend** | `src/chatbot/components/shell/ChatbotHeader.jsx` 27, 39 | Full screen, close (e2e uses class `close-button`, `chatbot-widget.page.ts`) | `ChatButton` with Lucide `Maximize2` and `X`; keep the class names |
| **Frontend** | `src/chatbot/components/shell/ChatbotShell.jsx` 65 | Screen tabs | `ChatTabs` (shared with the next row) |
| **Frontend** | `src/chatbot/components/shell/FloatingMountShell.jsx` 54 | Launcher (`.kimaai-chatbot-trigger`, **no `type` and no `aria-label`**) | `ChatButton`, add `type="button"` and a label; keep the class (e2e ×11) |
| Frontend (admin-only code, statically bundled) | `src/chatbot/components/shell/AdminAssistantShell.jsx` 104 | Assistant tabs (`role="tab"`) | `ChatTabs` |
| Admin assistant | `src/chatbot/components/screens/admin/AdminHelpScreen.jsx` 6 | Article tile | Keep raw (card-as-button) or a `ChatTile` |
| Admin assistant | `src/chatbot/components/screens/admin/AdminHomeScreen.jsx` 5 | Home tile | Same |
| Admin | `src/admin/components/Header.jsx` 25 | Page tabs | New `Tabs` atom (DS-6 lists tabs; no atom exists) |
| Admin | `src/admin/components/ChatbotHistory.jsx` 82, 104 | DataViews cell links | `KimaButton variant="link"` |
| Admin | `src/admin/components/Fields/DateTimePickerField.jsx` 107, 127 | "Now", "Clear" (**untranslated**; classes `kimaai-btn kimaai-btn-ghost` have no CSS anywhere) | `KimaButton variant="tertiary"` with `__()` |
| Admin | `src/admin/components/AdminThemeToggle.jsx` 42 | Animated sun/moon toggle | Keep raw (bespoke SVG); move focus ring to tokens |
| Admin | `src/admin/Layout.jsx` 92 | Scrim | Keep raw |

### Recommendation

- **Admin winner: `KimaButton`.** Replace all direct `Button` imports in `src/admin/**`.
- **Frontend winner: new `src/chatbot/components/ui/ChatButton.jsx`.** Native `<button type="button">` with variants `primary | secondary | ghost | icon`, `isBusy`, `aria-*` passthrough, an `icon` prop taking a Lucide component, and existing class names passed through. Apply it to every chatbot site above, including the admin-assistant ones, if the strict boundary is accepted.
- **`Chatbot.jsx`:** stop importing `AdminAssistantShell` statically. Pass the shell through config, for example `config.ui.shell.component` set by `createWpAdminAssistantConfig`, or a shell registry the way screens already work. That removes the shell (and `Notice`) from the frontend bundle.
- **Composer:** move `TextareaWithButton` (only user: `Composer.jsx` 1 and 42) to `src/chatbot/components/conversation/ComposerInput.jsx`. Use a native `<textarea>` plus `ChatButton` (Lucide `Send`/`Trash2`), and remove it from `src/admin/components/Fields/index.js` 11.
- **`SaveButton` becomes `SaveBar`** (same file or `atoms/SaveBar.jsx`). Keep both `data-testid`s.
    - Fix the user-facing typo "Discord Changes" → "Discard changes" (string in `languages/kimaai.pot` 5752). Rename the `discordChanges` prop chain (21 references across `useSettings.js` 434-441, `FieldRenderer.jsx`, `RepeatablePage.jsx`, `SaveButton.jsx`, tests).
    - Optionally drop the "Saved 🙂" emoji in `useSettings.js` 255.
- **`TriggerButton`:** keep. It is a public JS hook, already on `KimaButton`. Mark it as an extension point in a docblock.
- **`SidebarButton` becomes `SidebarToolbar`:** `KimaButton` plus `Icon` (Lucide `PanelLeftClose`/`ArrowLeft`). It keeps `KimaIcon` only for the PNG assistant mark.
- **Lint:** add ESLint `no-restricted-imports`:
    - `src/chatbot/**` bans `@wordpress/components`, `@wordpress/icons` and `@admin/*`;
    - `src/admin/**` bans `Button` from `@wordpress/components` (allow it only in `KimaButton.jsx`).

### Risks

- **Icon position flips.** Turning a direct `Button` with icon and text into `KimaButton` moves the icon to the right because of the default. Examples: `ChatbotConversationPanel.jsx` 145 (`fullscreen`), `RepeatableTable.jsx` 329 (`trash`). Pass `iconPosition="left"`, or decide once to change the default (it affects 19 existing users).
- **Composer styling.** The chatbot SCSS targets the WordPress class in `src/chatbot/index.scss` 1026-1040 (`button.components-button`, send button) and 1089-1095. `ComposerInput` must take over these rules under its own class.
- **Test mocks.**
    - `WizardApp.test.jsx` 18 and `ShowLogFile.test.jsx` mock `@global/components` (`KimaButton`); keep the export path.
    - `RepeatablePage.test.jsx` 13 mocks `SaveButton` through the `@admin/components` barrel; keep the name or update the mock.
    - `SettingsUiShell.test.jsx` 3 and 113 import `SidebarButton` by path.
- **e2e names.** e2e depends on accessible names: "Send", "Start new session", "Query", "Add Term", "Continue", "Test Connection", "I Understand and Accept", plus `getByTestId('save-button')` and `'repeatable-add-item-button'`. `chatbot-a11y.spec.ts` runs axe on the widget, which helps catch regressions from the native buttons.

### Tests that cover it

- Jest:
    - `tests/js/chatbot/components/ChatInput.test.jsx` (5: Send, Waiting for response, consent button)
    - `tests/js/chatbot/components/ChatbotShell.test.jsx` (tabs Help/Chat)
    - `tests/js/admin/components/SettingsUiShell.test.jsx` (7)
    - `tests/js/admin/components/AdminThemeToggle.test.jsx` (6)
    - `tests/js/admin/components/Fields/TextField.test.jsx` (Show/Hide password)
    - `tests/js/admin/components/Embedding/HealthPanel.test.jsx` (Refresh)
    - `tests/js/admin/components/Embedding/SyncPanel.test.jsx`
    - `tests/js/admin/wizard/WizardApp.test.jsx` (4)
    - `tests/js/admin/components/RepeatablePage.test.jsx`
    - `tests/js/admin/components/Fields/RepeatableTable.test.jsx`
    - `tests/js/chatbot/components/AdminSessionsScreen.test.jsx`
    - `tests/js/admin/components/ShowLogFile.test.jsx`
- Storybook:
    - `tests/storybook/admin/Atoms.stories.jsx` 67 (`KimaButtonStory`)
    - `tests/storybook/admin/Primitives.stories.jsx` 4
    - `tests/storybook/chatbot/Chatbot.stories.jsx` 170 (ChatInput), 323 (GDPR), 352 (header), 370 (launcher and popover), 394 (QuickActionsBar)
- e2e: `chatbot-settings.spec.ts` (trigger ×8), `chatbot-widget.page.ts`, `ai-services.page.ts`, `chatbot-settings.page.ts`, `admin-settings.spec.ts` 119-205, `enterprise-kb.spec.ts` 119-202, `setup-wizard.page.ts`, `chatbot-a11y.spec.ts`.

---

## 3. Copy

| Item | File | Lines | Notes |
| ---- | ---- | ----- | ----- |
| `useCopyToClipboard` | `src/global/hooks/useCopyToClipboard.js` | 1-96 | Clipboard API with an `execCommand` fallback (36-49); `status`, `errorMessage`, `isCopied`, `reset`; timeout default 2000. Free of WordPress components, safe for the frontend |
| `CopyButton` (atom) | `src/admin/components/atoms/CopyButton.jsx` | 7-23 | `KimaButton` with the hook (timeout 1200), WordPress icon `copy`; ignores errors (no feedback when copy fails) |
| `CopyButton` used | `src/admin/components/ShowLogFile.jsx` | 6, 152 | |
| Hand-built copy | `src/admin/components/ExportSettings/SettingsJsonModal.jsx` | props 15-19, button 58-61 | State lives in the parent: `SettingsImportExport.jsx` 36-37 (two hooks), handlers 207-221, props 315/317 and 362/364 |
| Local duplicate | `src/admin/mcp/McpApp.jsx` | 8-23, used 130, 168, 235 | `navigator.clipboard` only: no fallback, no error, no cleanup of the timer |
| Chatbot copy | `src/chatbot/components/ChatMessageFooter.jsx` | 1, 7, 23-28, 42-51 | Hook with a raw button (frontend) |

### Recommendation

- **Admin winner: `CopyButton`.** Extend it with `label`, `copiedLabel`, `failedLabel`, `onCopied`/`onError`, `variant` (default `secondary`) and `timeout`. Use the Lucide `Copy` icon.
- **`SettingsJsonModal`:** replace `onCopy`/`copyDisabled`/`copyLabel`/`copyDoneLabel`/`copyDone` with a single `copyValue` prop that renders `<CopyButton value={copyValue} onError={…}>`. Delete both hook instances in `SettingsImportExport.jsx` 36-37 and the handlers 207-221; the error notice moves to `onError`.
- **`McpApp.jsx` 8-23:** delete and import the atom.
- **Chatbot:** keep the hook. The footer button becomes `ChatButton` (family 2). Do not import the admin atom into the chatbot.

### Risks

- Copied-state labels differ today: "Copied" (atom, MCP), "Copied!" (JSON modal, chatbot). Pick one per surface; the strings are translated, so changing them invalidates translations.
- `ShowLogFile.test.jsx` 17 mocks `CopyButton` from `@admin/components/atoms`; keep the export path.

### Tests that cover it

- Jest: `tests/js/global/hooks/useCopyToClipboard.test.js` (3 tests), `ShowLogFile.test.jsx`.
- Storybook: `Atoms.stories.jsx` 62-65 (`CopyButtonStory`).
- No tests for `McpApp`, `SettingsImportExport` or `ChatMessageFooter`. Add a `CopyButton` Jest test (success, failure) when extending it.

---

## 4. Colour fields

| Component | File | Lines | Uses | Registry | PHP config |
| --------- | ---- | ----- | ---- | -------- | ---------- |
| `ColorField` | `src/admin/components/Fields/ColorField.jsx` | 1-101: hex normalise 7-16, text sync 28-55, `KimaButton` swatch 68-73, hidden `<input type=color>` 76-83, `TextField` 86, Reset 89-95 | `ChatbotThemeField.jsx` 102-108, 124-137 | `FieldRenderer.jsx` 35/66 | `app/Admin/config/chatbot.php` 373, 388, 403, 418, 433, 448 (all six are the hidden legacy fields) |
| `SingleColorPalette` | `src/admin/components/Fields/SingleColorPalette.jsx` | 1-22, WordPress `ColorPalette` | `MultipleColorPalette.jsx` 1, 26 | `FieldRenderer.jsx` 28/56 | none |
| `MultipleColorPalette` | `src/admin/components/Fields/MultipleColorPalette.jsx` | 1-40; caps at 4 (8). **Bug:** `{...settings}` then lodash `set` mutates nested state (12-14) | none | `FieldRenderer.jsx` 29/57 | none |
| `ChatbotThemeField` | `src/admin/components/Fields/ChatbotThemeField.jsx` | 1-147: three `SelectControl` 63-88, seed colours 101-109, advanced `PanelBody` 113-140 | – | `FieldRenderer.jsx` 40/76 | `chatbot.php` 576 (props 577-~660) |

### Recommendation

- **Winner: `ColorField`.** It is the only colour input in real use and the building block of `ChatbotThemeField`.
    - Rebuild the swatch so the `<input type="color">` itself is the focusable control, styled as a swatch, instead of a `KimaButton` with an invisible input on top.
    - Translate the label (`` `Select ${title} color` ``, line 72, is not translated).
    - Swap `space-x-2` (RTL-unsafe) for `gap-2`, and use `border-ui-border` and `rounded-ui-button`.
- **`ChatbotThemeField`:** stays as the domain composite. Restyle the helper text (`text-slate-500` → `text-ui-muted`, lines 94 and 118) and decide whether `PanelBody` 113 becomes a design-system disclosure. Logic unchanged.
- **`SingleColorPalette` and `MultipleColorPalette`:** delete the files. For one release, keep the registry keys `SingleColorPalette`/`MultipleColorPalette` as deprecated aliases that log `console.warn` and render `ColorField`. The keys are public through `registerFieldComponent`, the `kimaai.admin.fieldComponents` filter (`src/admin/fieldComponentsRegistry.js` 19-43), and any third-party PHP config. Owner decision: alias or hard removal. The `MultipleColorPalette` mutation bug argues against keeping its implementation.
- After UI-8 removes the legacy fields, `ColorField`'s only first-party user is `ChatbotThemeField`. Keep the `ColorField` registry key anyway (public).

### Risks

- Third-party configs using the palette names.
- `Fields.stories.jsx` 6 and 148-~170 (`SingleColorPaletteStory`) must become a `ColorField` story.
- The colour picker swap changes keyboard and screen-reader behaviour; check it with Storybook a11y.

### Tests that cover it

- No `ColorField` or `ChatbotThemeField` Jest test. Add one: hex validation, reset target, dark seed keys.
- Theme logic: `tests/js/admin/utils/chatbotTheme.test.js`, `tests/js/admin/components/ChatbotPreview.test.jsx`, `tests/js/setup.js` 48-77.
- PHPUnit: `tests/unit/ChatBot/ChatbotThemeTest.php`.
- e2e: `tests/e2e/specs/chatbot-settings.spec.ts` 265-286.

---

## 5. Repeatables

| Component | File | Lines | Role |
| --------- | ---- | ----- | ---- |
| `RepeatableTable` | `src/admin/components/Fields/RepeatableTable.jsx` | Pager 13-53; component 55-358: add/edit/save 105-170, row actions 181-219, counter 221-228, empty state 248-255, table 257-~314, `KimaModal` 322-354 | Table with modal editing. **Used by all 8 repeatable pages** (`saveType: 'repeatable'` with `view: 'table'`): `aiServices.php` 20-21, `embedding.php` 21-22 and 275-276, `chatbot.php` 1942-1943, 2028-2029, 2121-2122, 2246-2247, 2531-2532 |
| `RepeatableField` | `src/admin/components/Fields/RepeatableField.jsx` | 1-113 | Card grid. Reached only when `view !== 'table'` (`RepeatablePage.jsx` 170-182; no first-party page) or through the registry key (`FieldRenderer.jsx` 34/64; no PHP config) |
| `RepeatablePage` | `src/admin/components/RepeatablePage.jsx` | validation 34-63, item actions 65-111, save and persist 113-139, view switch 143-183, premium lock 188-195, `SaveButton` 199 | Page container for both views |
| `RepeatableSingleBlock` | `src/admin/wizard/RepeatableSingleBlock.jsx` | draft seeding 28-68, test gate 75-109, field loop 114-162, test button 164-178 | Wizard: edit one draft entry inline with the test-connection gate (`WizardApp.jsx` 15) |
| Shared helpers | `src/admin/components/Fields/repeatable/` | `RepeatableEntryForm.jsx` 1-120 (own hard-coded map of 7 field components, 11-19; `widthClassFor` 21-28), `useRepeatableHelpers.js`, `validateEntry.js`, `columnFormatters.jsx` | |

Further duplication:

- The field-row renderer exists three times:
    - `FieldRenderer.jsx` 208-290, with its width map at 227-234;
    - `RepeatableEntryForm.jsx` 50-84, with `widthClassFor` at 21-28;
    - `RepeatableSingleBlock.jsx` 114-162.

  The wizard's `FieldsBlock.jsx` is a fourth variant.
- `RepeatableEntryForm` uses a fixed component map. The wizard and `FieldRenderer` use the registry, so a third-party field type renders on settings pages but not inside table entries.
- `RepeatablePage.findFirstError` 34-63 scrolls to `#rf-${id}`, which only `RepeatableField` renders (`RepeatableField.jsx` 40). In table view the scroll does nothing; the modal validates on its own instead.
- The premium lock text in `RepeatablePage.jsx` 189-195 duplicates `FieldRenderer.jsx` 374-380.

### Recommendation

- **Winner: `RepeatableTable`.**
    - Move its row actions and pager to `KimaButton`/`Icon` (dashicon strings → Lucide, family 8).
    - Move the empty state 248-255 to the `EmptyState` atom and the frame to the `Card` atom.
    - Move the modal footer `Button`s 329-339 to `KimaButton` (keep `iconPosition="left"` on Delete).
- **`RepeatableField`:** delete it and the `view !== 'table'` branch in `RepeatablePage` (plus the up/down actions 75-90, only meaningful there). Keep the registry key `RepeatableField` as a deprecated alias for one release, or remove it (owner decision, as in family 4). Simplify `findFirstError` accordingly.
- **`RepeatablePage`:** keep as the page container.
    - Extract `usePersistConnectionState` (123-139) and the item-action builder.
    - Use a shared `PremiumLock` component, also used by `FieldRenderer.renderLockedContent` 363-385.
- **`RepeatableSingleBlock`:** keep it (a different job: a wizard step). Replace its inline field loop 114-162 with a shared `FieldGrid` and use the `useTestConnection` states for the test button.
- **Shared `FieldGrid`:** extract `FieldGrid` (rows, widths, section grouping, registry lookup) into `src/admin/components/Fields/FieldGrid.jsx`, used by `FieldRenderer`, `RepeatableEntryForm` and `RepeatableSingleBlock`. `RepeatableEntryForm` should then resolve components from the registry.

### Risks

- e2e `ai-services.page.ts` 35-44 uses `repeatable-add-item-button` (`RepeatableTable.jsx` 236), the dialog and the `Add` button.
- `enterprise-kb.spec.ts` 119-202 expects "Add Term", "Add Pinned Answer", "Add Case" and "Add Template" from `table.addLabel`.
- Wizard e2e `setup-wizard.page.ts` 226-235 matches the button names "Test Connection" / "Connection Failed" / "Connection Successful!".
- `RepeatablePage.test.jsx` 6-17 mocks both barrels (`@admin/components`, `@admin/components/Fields`); moving or renaming exports means updating the mocks.

### Tests that cover it

- Jest: `RepeatableTable.test.jsx` (8 tests), `RepeatablePage.test.jsx` (3), `WizardApp.test.jsx` (4; mocks `@admin/fieldComponentsRegistry` at 26).
- No story for repeatables. Add `Admin/Fields/RepeatableTable`.
- e2e: as listed under Risks.

---

## 6. Chatbot re-export aliases

| Alias | File | Lines | Target | Importers |
| ----- | ---- | ----- | ------ | --------- |
| `ChatInput` | `src/chatbot/components/ChatInput.jsx` | 1-7 | `conversation/Composer` | src: only the barrel `src/chatbot/components/index.js` 2. Tests: `tests/js/chatbot/components/ChatInput.test.jsx` 3 (renders at 11, 35, 55, 61, 65, 68). Storybook: `tests/storybook/chatbot/Chatbot.stories.jsx` 3 (176, 182, 189) |
| `MessageItem` | `src/chatbot/components/conversation/MessageItem.jsx` | 1-7 | **`ChatMessage`** (the "new" name wraps the old file) | `ConversationScreen.jsx` 1 (18, 40) |
| `ChatMessage` (implementation) | `src/chatbot/components/ChatMessage.jsx` | 1-91; **line 3 imports its own barrel `@chatbot/components`** (circular) | – | `MessageItem.jsx` 1, barrel `index.js` 3, `Chatbot.stories.jsx` 2 (121, 125, 134, 138, 142, 155, 431) |
| `ChatMessageRenderables` | `src/chatbot/components/ChatMessageRenderables.jsx` | 1-7 | `conversation/RenderableHost` | `src/admin/components/ChatbotConversationPanel.jsx` 7 (179) |
| `RenderableHost` | `src/chatbot/components/conversation/RenderableHost.jsx` | 1-33 | – | `ChatMessage.jsx` 4, `ChatMessageRenderables.jsx` 1, `tests/js/chatbot/components/RenderableHost.test.jsx` 2 |

Other barrel users: `PanelMountShell.jsx` 1, `FloatingMountShell.jsx` 1. No chatbot component is exposed on `window`, so these aliases are internal only.

### Recommendation

- Move the `ChatMessage` implementation into `conversation/MessageItem.jsx`, matching `Composer`, `ConversationScreen` and `RenderableHost` in `conversation/`. Replace the barrel import at its line 3 with direct imports.
- Delete `ChatInput.jsx`, `ChatMessage.jsx` and `ChatMessageRenderables.jsx`.
- Update `index.js` 2-3: export `Composer` and `MessageItem`, or drop them from the barrel.
- `ChatbotConversationPanel.jsx` 7 and 179 import `RenderableHost` directly.
- Rename `ChatInput.test.jsx` → `Composer.test.jsx`, and the stories `ChatMessageStory`/`ChatInputStory` → `MessageItemStory`/`ComposerStory`.
- Separate, optional: `ChatbotConversationPanel` has its own `MessageBubble` (~157) duplicating message rendering for admin transcripts. Leave it for UI-7 or later.

### Risks

- Storybook story IDs change (`chatbot-components--chat-input-story`). The published Storybook (`storybook:publish`) links break; acceptable.
- `ChatbotShell.test.jsx` mocks `@chatbot/components/conversation/ConversationScreen` by path; keep that path.

### Tests that cover it

- Jest: `ChatInput.test.jsx` (5), `RenderableHost.test.jsx` (1), `ChatbotShell.test.jsx` (3).
- Storybook: `Chatbot.stories.jsx`; `AdminChatbot.stories.jsx` 202 (`ConversationScreenStory`), 299 (renderables).
- e2e: `chatbot-widget.spec.ts`, `chatbot-session-cookie.spec.ts`, `chatbot-a11y.spec.ts`.

---

## 7. Logo vs KimaIcon

| | `src/admin/components/Logo.jsx` (1-27) | `src/admin/components/KimaIcon.jsx` (1-98) |
| - | -------------------------------------- | ------------------------------------------ |
| What | Brand lockup link: logo image (light/dark from `SETTINGS_UI.logo`) or text, plus `PluginVersion` | Resolver from a **name string** to: PNG `<img>` (names starting `PNG`, 86-89), custom JSX icons from `@assets/icons`, or `@wordpress/icons`, rendered with the WordPress `Icon` (91); exports `kimaIconMap` (96-98) |
| Users | `Sidebar.jsx` 1, 10; `WizardHeader.jsx` 2, 11; `About.jsx` 1, 17 | `SidebarButton.jsx` 45; `Menu.jsx` 2, 14 (`kimaIconMap`); `RadioGroupField.jsx` 2, 19; `WizardApp.jsx` 10, 319; `ChatbotConversationPanel.jsx` 25, 30; `feedback/utils.js` 12, 23; `KpiTiles.jsx` 36; `Csat.jsx` 370, 379; `MessageFeedback.jsx` 125, 129, 150, 206. **Frontend:** `src/chatbot/components/ChatMessageFeedback.jsx` 3, 86, 96 and `src/chatbot/components/ChatbotIcon.jsx` 2, 17 |
| Data | Config only | **Names are persisted data and PHP config:** chatbot `icon`/`aiAvatarIcon`/`userAvatarIcon` options (`chatbot.php` 164-210, 256-292, 330-342, values such as `RobotColorOne`, `close`, `UserIcon`, `PNGMessage`); menu group icons (`aiServices.php` 14 `CpuChip`, `chatbot.php` 32 `RobotWink`, `embedding.php` 17 `Embedding`, `tools.php` 13 `tool`, `integrations.php` 287 `plusCircle`); wizard step icons (`app/Admin/Wizard/config.php` 18, 77, 110) |

### Recommendation

Not a merge.

- **`Logo` stays**, optionally renamed to `BrandLogo` and moved into `atoms`.
- **Split `KimaIcon` into:**
  1. `src/global/icons/registry.js`: a map of name → PNG URL or brand JSX, free of WordPress components. It holds the persisted keys (robots, PNGs, `UserIcon`, `UserCircleIcon`, `PNGMessage`, and for back-compat `close`), and both the admin and `ChatbotIcon` use it.
  2. Interface icons through the Lucide `Icon` atom, with a name→Lucide map for the config-driven names (`tool` → `Wrench`, `plusCircle` → `CirclePlus`, `CpuChip` → `Cpu`, `RobotWink` → `Bot`, `Embedding` → `Layers`, `comment` → `MessageSquare`, `ChartBar` → `ChartColumn`, `Star`, `FaceSmile` → `Smile`, `ThumbsUp`/`ThumbsDown`, `check`, `closeSmall` → `X`, `seen` → `Eye`).
  3. `KimaIcon` becomes a thin component: registry first, Lucide map second, so existing call sites keep working.
- Move `src/admin/components/atoms/Icon.jsx` (no WordPress import) to `src/global/components/Icon.jsx` and re-export it from `atoms`, so the chatbot can use it.

### Risks

- Persisted icon names must keep resolving. Write a Jest test over every key in the registry plus the names found in `app/Admin/config/*.php`.
- `WizardApp.test.jsx` 13-14 mocks `Logo` and `KimaIcon` through the `@admin/components` barrel.
- `SettingsUiShell.test.jsx` 2 and 35-97 renders `Logo` directly and checks `getByRole('img', {name: 'KimaAI'})`.

### Tests that cover it

- Jest: `SettingsUiShell.test.jsx` (Logo ×5), `WizardApp.test.jsx`.
- Storybook: `tests/storybook/design/Foundations.stories.jsx` 259-296 (`LogoAndIcons`, iterates `@assets/icons`).

---

## 8. Icons (candidates for Lucide)

The `Icon` atom (Lucide) is used in `src` only by `EmptyState.jsx` 1/8. `lucide-react` 1.65.0 is imported only in `tests/js/admin/components/atoms/Primitives.test.jsx` 2 and `tests/storybook/admin/Primitives.stories.jsx` 2. All Lucide names below were checked against the installed 1.65.0 exports.

### `@wordpress/icons` imports

| File:import line | Icons | Lucide |
| ---------------- | ----- | ------ |
| `src/admin/components/ChatbotConversationPanel.jsx` 4 | `fullscreen` | `Maximize2` |
| `src/admin/components/ChatbotHistory.jsx` 3 | `seen`, `trash` (DataViews actions 182-209) | `Eye`, `Trash2` |
| `src/admin/components/Embedding/QueryPanel.jsx` 4 | `search`, `external`, `chevronDown`, `chevronUp` | `Search`, `ExternalLink`, `ChevronDown`, `ChevronUp` |
| `src/admin/components/Embedding/Sync/SyncModal.jsx` 5 | `check`, `closeSmall`, `seen`, `trash` | `Check`, `X`, `Eye`, `Trash2` |
| `src/admin/components/Embedding/Sync/SyncPanel.jsx` 5 | `cloudUpload`, `trash` (DataViews actions 279, 289) | `CloudUpload`, `Trash2` |
| `src/admin/components/Embedding/Sync/SyncStatusCell.jsx` 1 | `check`, `closeSmall` | `Check`, `X` |
| `src/admin/components/ExportSettings/SettingsImportExport.jsx` 3 | `download`, `upload`, `caution`, `check` | `Download`, `Upload`, `TriangleAlert`, `Check` |
| `src/admin/components/ExportSettings/SettingsJsonModal.jsx` 2 | `copy` | `Copy` |
| `src/admin/components/Fields/TextareaWithButton.jsx` 5 | `send`, `trash` (frontend composer) | `Send`, `Trash2` |
| `src/admin/components/KimaIcon.jsx` 28-43 | `customPostType`, `postFeaturedImage`, `link`, `help`, `send`, `loop`, `code`, `check`, `close`, `closeSmall`, `seen`, `comment`, `tool`, `plusCircle` | `Files`, `Image`, `Link`, `CircleHelp`, `Send`, `Repeat`, `Code`, `Check`, `X`, `X`, `Eye`, `MessageSquare`, `Wrench`, `CirclePlus` |
| `src/admin/components/ShowLogFile.jsx` 3 | `trash`, `fullscreen`, `download`, `update`, `page`, `close` | `Trash2`, `Maximize2`, `Download`, `RefreshCw`, `FileText`, `X` |
| `src/admin/components/SidebarButton.jsx` 3 | `arrowLeft` | `PanelLeftClose` or `ArrowLeft` |
| `src/admin/components/atoms/CopyButton.jsx` 2 | `copy` | `Copy` |
| `src/admin/feedback/pages/Csat.jsx` 5 | `seen`, `trash` | `Eye`, `Trash2` |
| `src/admin/feedback/pages/MessageFeedback.jsx` 5 | `trash` | `Trash2` |
| **Frontend** `src/chatbot/components/ChatMessageFooter.jsx` 3 | `copy` | `Copy` |
| **Frontend** `src/chatbot/components/FloatingAttentionPopover.jsx` 3 | `close` | `X` |
| **Frontend** `src/chatbot/components/shell/ChatbotHeader.jsx` 3 | `close`, `fullscreen` | `X`, `Maximize2` |

WordPress `Icon` wrapper imports: `QueryPanel.jsx` 3, `SyncModal.jsx` 4, `SyncPanel.jsx` 4, `SyncStatusCell.jsx` 3, `ImportExportBox.jsx` 1/21, `SettingsImportExport.jsx` 2, `SettingsJsonModal.jsx` 1, `TextareaWithButton.jsx` 4, `KimaIcon.jsx` 1, `SidebarButton.jsx` 1; frontend `ChatMessageFooter.jsx` 2, `FloatingAttentionPopover.jsx` 4, `ChatbotHeader.jsx` 2.

### Dashicon strings (WordPress `Button icon="…"`)

| File:line | Dashicon | Lucide |
| --------- | -------- | ------ |
| `RepeatableTable.jsx` 22, 46 | `arrow-left-alt2`, `arrow-right-alt2` | `ChevronLeft`, `ChevronRight` |
| `RepeatableTable.jsx` 191 | `edit` | `Pencil` |
| `RepeatableTable.jsx` 210, 329 | `trash` | `Trash2` |
| `RepeatableTable.jsx` 238, 253 | `plus` | `Plus` |
| `RepeatableField.jsx` 75, 91 | `trash`, `plus` | `Trash2`, `Plus` |
| `RepeatablePage.jsx` 71, 80, 86 | `admin-page`, `arrow-up-alt`, `arrow-down-alt` | `Copy`, `ArrowUp`, `ArrowDown` |
| `RepeatableSingleBlock.jsx` 167 | `redo` | `RotateCw` |
| `src/admin/hooks/useTestConnection.js` 14, 21, 28, 35 | `ellipsis`, `yes`, `no`, `redo` | `LoaderCircle`, `Check`, `X`, `RotateCw` |

### Inline SVG

| File:lines | What | Recommendation |
| ---------- | ---- | -------------- |
| `src/admin/components/Fields/TextField.jsx` 50-56 | Eye through WordPress `SVG`/`Path`; labels "Hide password"/"Show password" are **not translated** | `Eye`/`EyeOff`, add `__()` |
| `src/admin/wizard/AlreadyConfiguredWarning.jsx` 26-28 | Refresh | `RotateCw` |
| `src/admin/wizard/AlreadyConfiguredWarning.jsx` 38-40 | Back arrow | `ArrowLeft` |
| `src/admin/components/AdminThemeToggle.jsx` 51+ | Animated sun/moon | Keep (bespoke) |

### `src/assets/icons` (index at `src/assets/icons/index.js`)

| Icon | Used at | Verdict |
| ---- | ------- | ------- |
| `ThumbsUp`, `ThumbsDown` | Through `KimaIcon`: `feedback/utils.js` 12/23, `MessageFeedback.jsx` 125/129, `ChatbotConversationPanel.jsx` 25/30, **frontend** `ChatMessageFeedback.jsx` 86/96 | Interface → Lucide |
| `ChartBar`, `Star` | `Csat.jsx` 370, 379 | Interface → Lucide (`ChartColumn`, `Star`) |
| `FaceSmile` | `KpiTiles.jsx` 26 | Interface → `Smile` |
| `CpuChip`, `RobotWink`, `Embedding` | Menu group icons through PHP config → `Menu.jsx` 14 | Interface → `Cpu`, `Bot`, `Layers`; keep the names as registry keys |
| `Crown` | `atoms/PluginVersion.jsx` 1/21, `atoms/ProOnlyBadge.jsx` 2/15 | Interface → Lucide `Crown` |
| `WarningIcon` | `AlreadyConfiguredWarning.jsx` 3/19 | Interface → `TriangleAlert` |
| `UserIcon`, `UserCircleIcon` | User avatar options (`chatbot.php` 334, 338) | Content (avatar choice); keep in the registry |
| `RobotColorOne/Two/Three`, all `PNG*` | Avatar and launcher choices, wizard illustrations, assistant mark (`AdminAssistantShell.jsx` 3) | Brand content; keep (as `Foundations.stories.jsx` 289-291 already proposes) |

### Risks

- DataViews action `icon` expects a WordPress icon element or component. Check that Lucide components render at the right size in DataViews toolbars before mass replacing (`SyncPanel`, `ChatbotHistory`, `Csat`, `MessageFeedback`).
- CSS that targets `svg` fills (`fill-emerald-600`, `fill-rose-600` in `MessageFeedback.jsx` 125-150 and `ChatbotConversationPanel.jsx` 25-30) must become stroke/`text-*` classes, because Lucide is stroke-based.

### Tests that cover it

- Jest: `tests/js/admin/components/atoms/Primitives.test.jsx` (Icon `svg`, `img` "Inbox"), `TextField.test.jsx`.
- Storybook: `Primitives.stories.jsx` 62 (Icons card), `Foundations.stories.jsx` 259.

---

## 9. Large files

### 9.1 `src/admin/components/Embedding/Sync/SyncModal.jsx` (1,229 lines)

| Lines | Section |
| ----- | ------- |
| 1-7 | Imports (WordPress `Button`, `Icon`, `Notice`, `Spinner`; `@wordpress/icons`; `apiFetch` directly) |
| 9-34 | Helpers `truncateHeading`, `getSyncBadgeClasses`, `formatOptionalDate` |
| 35-42 | `BULK_ROW_STATES` |
| 43-87 | `BulkSyncStateBadge` (a hand-rolled `StatusBadge`) |
| 88-147 | `BulkStatusCard` |
| 148-206 | `usePostVectorStatus`, raw `apiFetch` to `/kimaai/v1/embeddings/post-status` |
| 207-249 | `SyncModal` state: about 25 `useState`/`useRef` |
| 259-305 | `signalActionPerformed`, `fetchVectordata` (`api.fetchByIds`) |
| 306-329 | Reset effects |
| 330-377 | Bulk detail fetch: **the same post-status endpoint again** through raw `apiFetch` (345) |
| 379-401 | `pushLocalLog`, `updateBulkRuntimeRows` |
| 403-440 | `handleDeleteChunk` |
| 442-524 | `chunkFields` (DataViews columns, `Button` 453 and 462), pagination info |
| 526-566 | Chunk loading effect |
| 568-672 | Background batch polling (`setInterval` 5 s, `api.batchStatus`, `api.logs`) |
| 674-849 | `handleSync`: enqueue for more than 10 ids, otherwise sequential `api.sync` |
| 851-936 | Labels, `bulkRows`, `bulkSummary`, texts |
| 937-1227 | JSX: header and status 938-1014, notices 1004-1014, logs 1015-1054, bulk entity cards 1055-1091, chunk DataViews 1092-1126, footer 1127-1136, vector data aside 1138-1225 |

Proposed split into `Embedding/Sync/syncModal/`:

- **Hooks:**
    - `usePostVectorStatus.js` and a `usePostStatuses(items)` bulk variant; both call a new `api.postStatus()` added to `useEmbedding` (removes the two raw `apiFetch` calls).
    - `useSyncRunner.js`: 674-849 plus polling 568-672, logs, `bulkRuntimeState`.
    - `useChunkVectors.js`: 226-249 state, 403-440, 526-566.
    - `useVectorDetail.js`: 265-311.
- **Components:**
    - `BulkSyncStateBadge` becomes a `StatusBadge` tone mapping, together with `SyncStatusCell.jsx` and `getSyncBadgeClasses` 16-21.
    - `BulkStatusCard.jsx`, `SyncLogList.jsx` (1015-1054), `ChunkTable.jsx` (1092-1126), `VectorDataPanel.jsx` (1138-1225), `SyncModalFooter.jsx` (1127-1136, `KimaButton`).
- **`SyncModal.jsx`** stays as composition, about 150 lines.

**Risks:** no Jest coverage. `SyncPanel.test.jsx` mocks DataViews and never renders the modal. Write characterisation tests for `useSyncRunner` (immediate vs background, error rows) first. e2e: `embedding-auto-sync.spec.ts`.

### 9.2 `src/admin/components/Embedding/QueryPanel.jsx` (551 lines)

| Lines | Section |
| ----- | ------- |
| 10-79 | `normalizeResults` |
| 80-197 | Text utilities: `normalizeQuery` 80, `extractQueryParts` 86, `buildSnippet` 112, `escapeRegExp` 154, `highlightSnippet` 156 |
| 198-237 | `formatNumber`, `getScoreLabel`, `getScoreTone` |
| 238-296 | `MetaBadge`, `MetaRow`, `ScorePill`, `HeadingBreadcrumbs` |
| 297-320 | `SnippetBlock` (`Button` 313) |
| 321-400 | `ResultCard` (`Button` 377) |
| 401-428 | `ResultList` |
| 429-550 | `QueryPanel`: state 432-447, `runQuery` 449-491, JSX 492-549 (`Button` 512) |

Proposed split:

- `Embedding/query/queryResults.js`: pure functions 10-237, unit-testable.
- `Embedding/query/ResultCard.jsx` with `SnippetBlock`, `HeadingBreadcrumbs`, `MetaRow`. `ScorePill` and `MetaBadge` become `StatusBadge` tones.
- `ResultList.jsx`.
- `QueryPanel.jsx`: form and `runQuery`, about 120 lines.

**Risks:** no Jest test. e2e `admin-settings.spec.ts` 205-215 (Query page). Add a Jest test for the pure functions first.

### 9.3 `src/admin/components/FieldRenderer.jsx` (522 lines)

| Lines | Section |
| ----- | ------- |
| 6-47 | Imports, including the `@admin/components` barrel that also exports `FieldRenderer`; `src/admin/components/index.js` 25 carries the comment "should be always the last one" to dodge the cycle |
| 49-87 | `builtInFieldComponents` and `setBaseFieldComponents` (side effect at module load) |
| 89-164 | Props, registry listener 108-112, shared tab state 106-152, `gridFor` 154-164 |
| 166-177 | Repeatable delegation |
| 179-205 | Visible fields (conditions) |
| 207-290 | `renderRows` (width map 227-234, i18n lock 251-259, preview overlay 237-240, 269) |
| 292-343 | `renderSections` (panel vs aside) |
| 345-361 | Custom component |
| 363-385 | `renderLockedContent` |
| 387-479 | `renderContent`: preview layout 388-429, fields and component 431-447, fields and sidebar 448-461, fields only 462-471, component only 472-476 |
| 481-500 | Shared tab header |
| 502-519 | Output, `SaveButton` 438 and 516 |

Proposed split:

- `src/admin/fieldComponents.js`: the built-in map plus `setBaseFieldComponents`. This breaks the barrel cycle.
- `Fields/FieldGrid.jsx`: 207-343, shared with family 5.
- `useVisibleFields.js`: 179-205.
- `layouts/PreviewLayout.jsx`, `ComponentLayout.jsx`, `SidebarLayout.jsx`, `FieldsLayout.jsx`: 387-479.
- `PremiumLock.jsx`: 363-385, shared with `RepeatablePage` 188-195.
- `FieldRenderer.jsx`: routing between those, about 120 lines.

**Risks:** the registry module must still run `setBaseFieldComponents` before any `getFieldComponents()`. The wizard (`FieldsBlock.jsx` 1, `RepeatableSingleBlock.jsx` 2) relies on the base map being set by importing `FieldRenderer`. Import `fieldComponents.js` from `src/admin/index.js` and the wizard entry. No Jest test exists; e2e `admin-settings.spec.ts`, `chatbot-settings.spec.ts` and `enterprise-kb.spec.ts` render most layouts.

### 9.4 `src/chatbot/controllers/useConversationController.js` (625 lines)

| Lines | Section |
| ----- | ------- |
| 6-18 | `TOOL_EVENT_NAME`, `dispatchToolEvent` |
| 20-44 | State, session id ref |
| 46-217 | `fetchChatHistory`: transport call 48-58, quick actions and feedback 60-71, tool-trace replay 77-112, optimistic merge 114-201 (pure logic, heavily commented), append merge 204-211 |
| 219-224 | Init effect |
| 226-488 | `sendMessageStream`: tool status timer 227-269, request 271-297, non-SSE branch 298-366, SSE reader loop 367-474 (meta 399, delta 404, tool 413, error 432, done 446) |
| 490-531 | `sendMessageJson` |
| 533-554 | `sendMessage` |
| 556-586 | `clearHistory` |
| 588-596 | `loadSession` |
| 598-623 | Return |

Proposed split into `src/chatbot/controllers/conversation/`:

- `mergeHistory.js`: pure `mergeOptimistic(prev, next, {preserveOptimistic})` from 114-211. The race-condition tests become plain unit tests.
- `toolTraces.js`: 6-18 and 77-112.
- `streamResponse.js`: SSE and non-SSE response handling 298-474 as an async function taking callbacks (`onMeta`, `onDelta`, `onTool`, `onError`, `onDone`).
- `useToolStatus.js`: 227-269.
- `useConversationController.js`: state and the five actions, about 200 lines.

**Risks:** the strongest safety net in the repo. `tests/js/chatbot/hooks/useChat.test.js` has 21 tests through `useChat` → this controller, including the stale-history races (395-830) and SSE (253-394). Keep the public return shape (598-623) identical.

### 9.5 `src/admin/hooks/useSettings.js` (464 lines)

| Lines | Section |
| ----- | ------- |
| 10-34 | Route helpers `getRouteFromUrl`, `getFallbackMenuItem` |
| 37-41 | `saveTimeouts`: **bug**, a plain `let` re-created every render, so `clearAllTimeouts` never sees earlier timers |
| 43-55 | State |
| 57-93 | `groupSaveKeyMap`/`fieldSaveKeyList` (pure) |
| 95-132 | URL routing and tab handlers |
| 134-195 | `buildCombinedSettings`, `buildSavePayload` (pure, given the maps) |
| 197-234 | `getSettings`, `refreshData`, `refreshSchemaOnly` (`getSettings` has no `catch`, so `loading` stays true on error) |
| 236-269 | `saveSettings` (no `catch`: on error the button stays "Saving…") |
| 271-323 | `menu` from schema (pure) |
| 325-357 | popstate and refresh-event effects |
| 359-412 | Active item and fallback-route effects |
| 414-441 | `uiOnlyGroups`, dirty check, revert, `discordChanges` |
| 443-462 | Return |

Proposed split into `src/admin/hooks/settings/`:

- `schemaIndex.js`: 57-93, `buildMenu` 271-323, `buildCombinedSettings`/`buildSavePayload` 134-195, all pure and unit-testable.
- `useSettingsRoute.js`: 10-34, 95-132, 325-341, 359-412.
- `useSaveStatus.js`: 37-51 and 236-269, with timers in a `useRef` (fixes the bug) and a failure state.
- `useDirtySettings.js`: 414-441, renamed to `discardChanges`.
- `useSettings.js`: composition with the same return shape, about 100 lines.

**Risks:** `tests/js/admin/hooks/useSettings.test.js` (10 tests, 59-300) covers routing, split payloads and `discordChanges`. Rename the prop together with family 2. `AdminAssistantActionBridge` dispatches `kimaai:admin-assistant-refresh-settings` (10), so keep the event name.

---

## 10. Dead code

### 10.1 `premium/app/KimaAIPro.php` (136 lines): safe to delete

- **No references.** Checked across `*.php`, `*.js`, `*.json`, `*.md`, `*.xml`, `*.neon`, `*.txt`, excluding `node_modules`/`vendor`: no references to `KimaAIPro` outside the file itself (only `docs/ROADMAP.md` 43). It is not in `premium/premium-loader.php`, and PHPStan excludes `premium/*` (`phpstan.neon` 13-16).
- **Premium boots elsewhere.** The DI container does the work: `app/Generated/ContainerKimaAI_pro_*.php` `registerIntegration` for `ChatbotPremium` and `EmbeddingQueue`, and `registerCommand` for `KimaAICLI`.
- **It would fatal if loaded.** It references four classes that no longer exist: `KimaAI\Pro\Cli\InternalLink`, `KimaAI\Pro\InternalLinks\LinkShortcode`, `KimaAI\Pro\InternalLinks\LinkController`, `KimaAI\Pro\Cli\Linker`.
- **The Yoast filters are already inactive.** The `yoast_link_count`/`yoast_incoming_link_count` orderby filters (59-107) exist nowhere else, and nothing in `src/` or `app/` uses those orderby values, so the behaviour is already absent.

### 10.2 `build/flow*`: local leftover, but it can ship

- **Files:** `build/flow/` (`index.js` 6.97 MB, `index.js.map` 6.8 MB, `index.asset.php`, `flow.css`), `build/flow.css`, `build/flow-rtl.css`, `build/flow.css.map`, dated 25-27 May 2026.
- **Origin:** branch `feat/classic-chatbot-flow-extract` (commit `0b11cdce`), which is not an ancestor of HEAD.
- **No `flow` entry anywhere:** `webpack.config.js` 7-11 has `admin`, `chatbot` and `chatbot-admin` only; nothing in `app/`, `src/`, `package.json` or `scripts/` refers to it. `/build/` is gitignored (`.gitignore` 3), so this is not a commit, only a local cleanup plus prevention.
- **Why it can ship:**
    - `CleanWebpackPlugin` is deliberately filtered out (`webpack.config.js` 28-30).
    - The release scripts copy the whole `build` directory (`scripts/zip-utils.mjs` 7-18, `scripts/make-premium-zip.mjs` 16-29). Only `*.map` is pruned (`zip-utils.mjs` 24).

  So a ZIP built on this machine would include `build/flow/index.js` and the flow CSS.
- **Recommendation:**
    - Delete `build/flow*` locally.
    - Add a clean step to `package.json` `build`, for example `rm -rf build` before `build:wp`. This is safe because `build:admin-tailwind` runs after `build:wp` in `npm-run-all`; the plugin was removed because of `watch`.
    - Alternatively, prune unknown top-level entries in `pruneExcluded()`.
- Also stale but harmless: `app/Generated/ContainerKimaAI_free_1_5_6.php`, `_free_1_5_7.php`, `_pro_1_5_3.php` (gitignored, and `app/Generated` is excluded from ZIPs).

### 10.3 New finding: the `chatbot-admin` entry is dead

- `webpack.config.js` 10 and `src/chatbot/index.admin.js` 1-20 mount into `#kimaai-chatbot-admin`.
- No PHP prints that element or enqueues `build/chatbot-admin/`. `app/Admin/Assets.php` 174-185 localises `kimaaiAdminChatbot` onto the `kimaai-admin` handle, and the assistant renders through `AdminAssistantRail.jsx` inside the admin bundle.
- **Remove** the entry and `index.admin.js`. Build output `build/chatbot-admin/` and `build/chatbot-admin*.css` disappear.

### 10.4 New finding: unused components

- `src/admin/components/Embedding/ListPanel.jsx` (314 lines, includes Modal #6) and `src/admin/components/Embedding/FetchDeletePanel.jsx`: no importers.
- `src/admin/components/Fields/CustomSelectField.jsx`: exported from `Fields/index.js` only, not in the registry, no users.
- `src/global/components/JsonBlock.jsx`: barrel export only. Its CSS side effect pulls highlight.js into the **frontend** bundle (see 0). Delete it, or stop barrel imports from the chatbot.
- `src/admin/components/atoms/LoadingLines.jsx`: Storybook only (`Atoms.stories.jsx` 5/56). Keep it if it is meant as a primitive.
- `MultipleTextField`, `DateTimePickerField`, `CheckboxField` (as a top-level field), `TriggerButton`: registry only, with no PHP config use. They are public registry keys, so do not delete them in this track.

### 10.5 Legacy per-colour chatbot fields: removal needs a migration

**Fields:** `app/Admin/config/chatbot.php` 369-458: `bodyBgColor`, `bodyTextColor`, `userMessageBgColor`, `userMessageTextColor`, `aiMessageBgColor`, `aiMessageTextColor`. Each is a `ColorField` hidden with `condition: theme = '__hidden_legacy_colors__'`; it was introduced with the theme token system (commit `68a8c7a4`). They are stored raw in `kimaai_options['chatbot']['appearance']`. `Settings::getOption()` (`app/Admin/Settings.php` 984-) returns them without merging defaults.

**Everything that still reads them:**

| Where | Lines | What |
| ----- | ----- | ---- |
| `app/ChatBot/ChatbotTheme.php` | 21 `LEGACY_PRIMARY`, 56-63 `LEGACY_DEFAULTS`, 92 (`jsConfig` exposes `legacyDefaults`) | |
| `app/ChatBot/ChatbotTheme.php` | 189-219 `normalize()`: no `theme` → `fromLegacyAppearance` (194); default theme plus custom legacy → backfill (198-203) | Live upgrade path |
| `app/ChatBot/ChatbotTheme.php` | 225-249 `fromLegacyAppearance()`, 416-426 `shouldPreserveLegacyColors()`, 434-443 `hasCustomLegacyColors()` | |
| `app/ChatBot/ChatbotAssets.php` | 102-122 | Public filter `kimaai_chatbot_theme` takes a legacy-shaped array built **from the theme**, not from the fields. It does not depend on the fields; keep it (possibly `apply_filters_deprecated` later) |
| `src/admin/utils/chatbotTheme.js` | 13-17, 25-39, 42, 75-80, 85-107 | JS mirror of the PHP logic |
| `src/admin/components/ChatbotPreview.jsx` | 11-13 | Passes the whole `appearance` to `resolveChatbotTheme`, so the legacy branch is live in the preview |
| `src/admin/components/Fields/ChatbotThemeField.jsx` | 29, 35 | Theme branch only (not affected) |
| Tests | `tests/unit/ChatBot/ChatbotThemeTest.php` 41-94; `tests/unit/ChatBot/ChatbotAssetsTest.php` 81 (filter); `tests/js/setup.js` 71-77; `tests/js/admin/utils/chatbotTheme.test.js` 12, 38; `tests/js/admin/components/ChatbotPreview.test.jsx` 79-81; e2e `tests/e2e/specs/chatbot-settings.spec.ts` 265-286 (seeds legacy keys and expects the CSS vars) | |
| i18n | `languages/kimaai.pot` 420, 452 and the translations | Regenerate |

**Verdict: needs a migration.** Installs that never re-saved after the theme system was added have no `appearance.theme` and are rendered through `fromLegacyAppearance`. Sites with a default theme object but custom legacy colours are backfilled at runtime. Deleting the fields and the read path would silently reset their branding.

**Plan:**

1. **`app/Database/Migrations/Version2026111401.php`** (or the next free number), registered in `app/Database/Migrator.php` `updates()` (34-43) with `CODE_DB_VERSION` bumped. Pattern: `Version2026111301`.
   - Read `kimaai_options`.
   - If `chatbot.appearance` has any of the six keys:
        - **no `theme`:** write `theme` = legacy mapping when colours are custom, otherwise leave `theme` unset (the default);
        - **`theme` present and the `shouldPreserveLegacyColors` condition true:** merge `colors`, `advanced` and `colorPreset` as `normalize()` does at 198-203.
   - Then `unset` the six keys and `update_option`.
   - The mapping logic must be copied into the migration (or a small `LegacyAppearance` class), because `fromLegacyAppearance` is removed.
2. **Settings import** (`app/Admin/Settings.php` 226-289) sanitises incoming JSON against the schema. `preserveUnknownKeys()` only keeps keys from the *existing* option, so an **old export with legacy colours would lose them on import** once the fields leave the schema. Run the same `LegacyAppearance::upgrade()` on the incoming `chatbot.appearance` before `sanitizeOptionsGeneric()`.
3. **Remove:**
   - `chatbot.php` 369-458;
   - `LEGACY_PRIMARY`, `LEGACY_DEFAULTS`, `fromLegacyAppearance`, `shouldPreserveLegacyColors` and `hasCustomLegacyColors` from `ChatbotTheme`, with `normalize()` simplified;
   - `legacyDefaults` from `jsConfig`;
   - the JS legacy branch in `chatbotTheme.js`.
4. **Tests:**
   - new `tests/unit/Database/LegacyChatbotColoursMigrationTest.php` (pattern: `ReplicateRemovalMigrationTest.php`);
   - move the `ChatbotThemeTest` legacy cases into it;
   - update `setup.js`, `chatbotTheme.test.js` and `ChatbotPreview.test.jsx`;
   - change the e2e test at 265 to seed `theme.advanced` (or seed legacy keys and run the migration).

**Owner decision needed:** an install with no `theme` and legacy keys at their **old defaults** (`#4545f9` …) currently renders those old colours as advanced overrides (`fromLegacyAppearance` 241-246 copies any non-empty value). `testLegacyDefaultsAreNotTreatedAsCustomColors` (`ChatbotThemeTest.php` 80-94) already treats old defaults as "not custom" when a theme object exists. Recommendation: the migration drops default-valued legacy keys, so these sites get the DS-4 brand defaults. That changes their visible colours: mention it in the changelog.

Decision (owner delegated, my recommendation, 2026-11-13): legacy keys still at their old default values are dropped, so those sites get the brand defaults; custom legacy colours become `theme` overrides exactly as `fromLegacyAppearance` and the `normalize()` backfill did. "Custom" means at least one of the six keys differs from its old default; then every set key is mapped, as before. A saved theme with custom colours or advanced overrides wins and the legacy keys are only removed. Implemented as `LegacyAppearance::upgrade()` (`app/ChatBot/LegacyAppearance.php`), run by migration `Version2026111303` and by the settings import.

Found while implementing: `Settings::register()` (every request, `init` 10) prunes keys that left the schema when the schema fingerprint changes, before the migration (admin, cron or CLI only, `init` 20) can read them. `Settings::upgradeOption()` therefore runs `LegacyAppearance::upgradeOptions()` on `kimaai_options` before pruning; the migration stays as the explicit, idempotent step.

### 10.6 `@base-ui`

- Removed from `package.json` in DS-6 (commit `5e327768`). No imports in `src/`, `tests/` or `.storybook`.
- It stays in `package-lock.json` (2163-2210, version 1.9.0) and `node_modules/@base-ui/{react,utils}` as a **transitive** dependency of `@wordpress/ui` (through `@wordpress/dataviews`, `@wordpress/block-editor`, `@wordpress/commands`, `@wordpress/image-cropper`, `@wordpress/media-fields`).
- Nothing to do. Do not add an override.

---

## 11. Further duplicates found (not in the requested families)

Fold these into the commits named.

- **Status badges** (into the buttons/primitives or large-file commits):
    - `src/admin/components/Embedding/HealthPanel.jsx` 26-32 exports its own `StatusBadge`, which shadows the atom's name.
    - `Sync/SyncStatusCell.jsx`, `SyncModal.jsx` 16-21 and 43-87.
    - `QueryPanel.jsx` 222-270 (`getScoreTone`, `ScorePill`).
    - `ChatbotConversationPanel.FeedbackBadge`.

  All should map to the `StatusBadge` tones.
- **Cards:** `src/admin/components/Embedding/Section.jsx` 1-6, `feedback/components/ChartCard.jsx` 2 and `feedback/components/KpiTiles.jsx` 1 use the WordPress `Card`/`CardBody`. The `Card` atom has no `src` users yet.
- **Tabs:** `Header.jsx` 25, `ChatbotShell.jsx` 65 and `AdminAssistantShell.jsx` 104 are three tab implementations. DS-6 planned a tabs primitive that does not exist yet.
- **DataViews delete confirmations:** `Csat.jsx` 172-205 and `MessageFeedback.jsx` 223-256 are near-identical, with hard-coded `!bg-red-600` instead of `isDestructive`. Covered by `ConfirmBody` in family 1.

---

## 12. Recommended commit order (`track/UI-components`, one commit per family)

The roadmap order (UI-2 … UI-8) is kept, with two changes:

- the dead code without data impact moves to the front, so later commits do not migrate files that are about to be deleted (for example `ListPanel`'s Modal);
- the legacy-colour migration stays last, as its own commit.

| # | Commit | Roadmap item | Contents | Gate (must stay green) |
| - | ------ | ------------ | -------- | ---------------------- |
| 1 | `refactor(ui): remove dead code` | UI-8 (part) | `KimaAIPro.php`, `ListPanel.jsx`, `FetchDeletePanel.jsx`, `CustomSelectField`, `JsonBlock` (or the chatbot barrel import), the `chatbot-admin` entry with `index.admin.js`, the build clean step; delete `build/flow*` locally | `npm run build`, Jest all, PHPUnit, e2e smoke |
| 2 | `refactor(chatbot): drop component aliases` | UI-6 | Family 6 | `ChatInput.test` (renamed), `RenderableHost.test`, `ChatbotShell.test`, `Chatbot.stories`, chatbot e2e |
| 3 | `refactor(ui): modals on KimaModal, ConfirmDialog, ChatDialog` | UI-2 | Family 1 | `RepeatableTable.test`, `RepeatablePage.test`, `AdminSessionsScreen.test`, `ShowLogFile.test`, `ai-services` e2e; new `KimaModal`/`ConfirmDialog`/CSAT stories |
| 4 | `refactor(ui): buttons and copy` | UI-3 | Families 2 and 3: `ChatButton`, `ComposerInput`, `SaveBar` (and the "Discard" fix), `SidebarToolbar`, `CopyButton` everywhere, ESLint boundary for `src/chatbot`, `Chatbot.jsx` shell injection | All button-related Jest, `useCopyToClipboard.test`, `Atoms`/`Primitives`/`Chatbot` stories, `chatbot-a11y`, `chatbot-widget`, `chatbot-settings`, `setup-wizard`, `enterprise-kb` e2e; check `build/chatbot/index.asset.php` no longer lists `wp-components` |
| 5 | `refactor(ui): Lucide icons, icon registry, Logo` | (UI-3/UI-6 scope) | Families 7 and 8 | `SettingsUiShell.test`, `WizardApp.test`, `Primitives.test`, `TextField.test`, `Foundations`/`Primitives` stories; new registry key test |
| 6 | `refactor(admin): colour fields` | UI-4 | Family 4 (`ColorField` rebuilt, palettes removed or aliased) | New `ColorField`/`ChatbotThemeField` tests, `chatbotTheme.test`, `ChatbotPreview.test`, `Fields.stories`, `chatbot-settings` e2e |
| 7 | `refactor(admin): repeatables and FieldGrid` | UI-5 | Family 5 | `RepeatableTable.test`, `RepeatablePage.test`, `WizardApp.test`, `ai-services`/`enterprise-kb`/`setup-wizard` e2e |
| 8 | `refactor(ui): split large files` | UI-7 | Section 9 (one sub-commit per file is fine). Write characterisation tests for `SyncModal`, `QueryPanel` and `FieldRenderer` first | `useChat.test` (21), `useSettings.test` (10), `SyncPanel.test`, new pure-function tests, `admin-settings`/`embedding-auto-sync` e2e |
| 9 | `refactor(chatbot): migrate legacy colour fields` | UI-8 (rest) | Section 10.5: migration, import upgrade, removals | New migration PHPUnit test, `ChatbotThemeTest`, `ChatbotAssetsTest`, updated JS tests, `chatbot-settings` e2e 265 |

Changelog and readme entries are needed for:

- commit 4 (the visible "Discard changes" label, and the frontend no longer loading `wp-components`);
- commit 6 (palette field types deprecated, if aliased);
- commit 9 (legacy colours migrated; old default colours switch to the brand defaults, if the owner agrees).

## 13. Decisions (owner delegated, my recommendation, 2026-11-13)

1. **Chatbot boundary: strict.** Nothing under `src/chatbot` imports `@wordpress/components`, `@wordpress/icons`, `@admin/*` or the `@global/components` barrel; an ESLint `no-restricted-imports` override for `src/chatbot/**` enforces it.
2. **Public registry keys** `SingleColorPalette`, `MultipleColorPalette`, `RepeatableField`: kept as deprecated aliases for one release, then removed.
3. **`KimaButton`'s default `iconPosition='right'`:** kept, so no screen changes.
4. **Old default legacy colours:** already done in DS (`ChatbotTheme::fromLegacyAppearance()` and the JS resolver give untouched legacy fields the brand defaults); commit 9 only removes the hidden fields with their migration.
5. **`ShowLogFile`'s `window.confirm` ×3:** moved to `ConfirmDialog`.
