@wix/agent-skills 1.24.0 → 1.25.0

package/README.md

@@ -58,6 +58,7 @@ npx skills add wix/skills -g
 | [wix-app](skills/wix-app/SKILL.md)       | Build Wix app extensions         | Adding any extension — dashboard pages, site widgets, backend events, service plugins, embedded scripts, data collections, and more |
 | [wix-design-system](skills/wix-design-system/SKILL.md) | Wix Design System reference      | Looking up WDS component props, examples, icons                                                                                     |
 | [wix-manage](skills/wix-manage/SKILL.md) | Wix business solution management | REST API operations for configuring and managing Wix business solutions                                                             |
+| [wix-headless-kit](skills/wix-headless-kit/SKILL.md) | Build and release a Wix Headless site on shipped, verified per-solution code | Building a new headless site for a business from a brief — store, bookings, blog, events, restaurants, members, donations and more — fast, with the integration code already written |
 | [wix-headless](skills/wix-headless/SKILL.md) | Connect Wix business services to a headless frontend (SDK + Wix CLI), and optionally build & host the site | Setting up a Wix Headless backend or adding Wix business features (Stores, Bookings, CMS, Blog, Events, Forms, Members, Restaurants, Portfolio, Pricing Plans) — install apps, seed content, and produce an SDK-integration guide; for managed projects also scaffold a new site (create) or wire an existing design (connect), then build and release. Works across managed, self-managed, and stripe project types |
 | [wix-vibe-headless](skills/wix-vibe-headless/SKILL.md) | Connect an existing front end to Wix over client-only REST | Wiring a vibe-coded / HTML / Vite app to a live Wix site (storefront, bookings, blog, events, portfolio, restaurants, CMS, pricing plans) from the browser with a public `WIX_CLIENT_ID` — no SDK, no backend |
 | [wix-docs](skills/wix-docs/SKILL.md) | Look up the Wix API/SDK docs (shared fallback) | Confirming an exact Wix endpoint, method schema, field, or enum before writing code — `curl` doc-search + the `.md`-twin trick, or the Wix MCP tools. Referenced by the other skills as their docs-lookup fallback |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
   },
   "files": [
     "skills/**",
+    "!skills/wix-headless-cold-start/**",
     "README.md",
     "LICENSE"
   ],

package/skills/wix-app/SKILL.md

@@ -43,7 +43,8 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
   - [ ] **Compile as you go:** ran `npx tsc --noEmit` after the first file that imports `@wix/patterns`, not only at Step 5. Patterns' state and filter APIs are the most common source of errors, and finding twenty of them in one batch after the page is written costs far more than finding two early.
   - [ ] **🛑 Component Selection Gate (MANDATORY, dashboard UI only):** For every UI element on a Dashboard Page, resolved it against `@wix/patterns` BEFORE reaching for `@wix/design-system` — and never hand-rolled a component either library already provides. See [Component Selection Order](#component-selection-order).
   - [ ] Invoked `wix-design-system` skill ONLY before editing the first `.tsx`/`.jsx` file that imports `@wix/design-system`. Skip for backend-only or data-only extensions.
-  - [ ] WDS: imported `@wix/design-system/styles.global.css` in the main component entry file (`page.tsx`, modal `.tsx`, etc.) — not child/tab/helper files.
+  - [ ] WDS: the design-system stylesheets are imported in exactly one place per app — `BusinessManagerTheme.tsx` for a dashboard surface (see the next item), or the main component entry file for a site/editor extension. Never in child, tab or helper files, and never twice.
+  - [ ] **🛑 Business Manager theme (every dashboard surface — page, modal AND plugin):** wrote `BusinessManagerTheme.tsx` once (both stylesheets, including `themes/odeditor.global.css`, plus `WixDesignSystemProvider` → `WixDesignSystemIconThemeProvider` → `IconThemeProvider theme="odeditor"` → `WixDesignSystemDefaultPropsProvider`), and wrapped **each** extension's root in it — above `WixPatternsProvider` and above `CustomModalLayout`. Every extension is a separate iframe that inherits none of the redesign, so theming the page does nothing for a modal it opens or a plugin in a slot; each one needs its own wrapper. Also: every icon from `@wix/wix-ui-icons-common/lazy`, and `--wds-*` tokens or `skin`/`size` props rather than hardcoded colours, font sizes or inline `style` ([BUSINESS_MANAGER_TOKENS.md](references/BUSINESS_MANAGER_TOKENS.md) — note the theme rebases the `SP*` spacing unit from 6px to 4px). `tsc`, `wix build` and `wix preview` all pass on an unthemed surface — only looking at it catches this. See [BUSINESS_MANAGER_THEME.md](references/BUSINESS_MANAGER_THEME.md).
 - [ ] **Step 4c (dashboard page UI only):** Re-opened and read the page file(s) just written — not recalled intent — and confirmed against the actual code: no `SummaryBar` unless the request asked for one, a routed drill-in (`navigateToEntityPage`) for every row and no `SidePanel` used as one, every declared filter name also appearing inside `fetchData`, and — for Cases A/B/D — the entry file both passes and guards `location`. See [UX Completeness Self-Audit](#step-4c-ux-completeness-self-audit).
 - [ ] **Step 5:** Ran validation (see [Validation](#validation))
   - [ ] Dependencies installed
@@ -209,6 +210,8 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 | Wix Stores Versioning (V1/V3) | [STORES_VERSIONING.md](references/STORES_VERSIONING.md) |
 | Official Documentation Links | [DOCUMENTATION.md](references/DOCUMENTATION.md) |
 | Wix Patterns Dashboard Pages | [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) |
+| Business Manager theme — the wrapper every dashboard page, modal and plugin needs | [BUSINESS_MANAGER_THEME.md](references/BUSINESS_MANAGER_THEME.md) |
+| Business Manager tokens — `--wds-*` replacements, the rebased spacing unit, per-component adjustments | [BUSINESS_MANAGER_TOKENS.md](references/BUSINESS_MANAGER_TOKENS.md) |
 | Dashboard UX Success Model (what a good dashboard contains) | [UX_SUCCESS_MODEL.md](references/dashboard-page/UX_SUCCESS_MODEL.md) |
 | Draft template — start here for any dashboard page (Cases A/B/C/D) | [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md) |
 | Draft template — collection page for Cases A/B/D | [DRAFT_TEMPLATE_COLLECTION.md](references/dashboard-page/DRAFT_TEMPLATE_COLLECTION.md) |

package/skills/wix-app/references/BUSINESS_MANAGER_THEME.md

@@ -0,0 +1,108 @@
+# Business Manager theme — one wrapper, every dashboard surface
+
+Business Manager (the Wix site dashboard) was redesigned with the Harmony theme. **A dashboard extension runs in its own iframe and inherits none of it.** `WixDesignSystemProvider` alone gives the pre-redesign look — classic icons, pre-redesign button sizes and skins — rendered inside redesigned platform chrome.
+
+**No automated check catches this.** `tsc`, `wix build` and `wix preview` all pass on an unthemed surface — every import resolves and every component renders. The failure is purely visual, so wire it from the start.
+
+Verified against `@wix/design-system` 1.330.0 and `@wix/wix-ui-icons-common` 3.189.28 — both providers are root exports, `IconTheme` is typed `'default' | 'odeditor'`, and `themes/odeditor.global.css`, `lazy`, `lazy/system` and `core` all ship.
+
+## 1. Both packages, together
+
+```bash
+npm install @wix/design-system@latest @wix/wix-ui-icons-common@latest
+```
+
+The redesigned styles and matching icon set ship as a pair — update them together. An older `@wix/design-system` leaves a surface half-migrated however the providers are wired, since refinements ship continuously during the rollout.
+
+## 2. The wrapper — write this file once per app
+
+```tsx
+// src/extensions/dashboard/BusinessManagerTheme.tsx
+import type { FC, ReactNode } from 'react';
+import { i18n } from '@wix/essentials';
+import {
+  WixDesignSystemProvider,
+  WixDesignSystemIconThemeProvider,
+  WixDesignSystemDefaultPropsProvider,
+  type WixDesignSystemDefaultProps,
+} from '@wix/design-system';
+import { IconThemeProvider } from '@wix/wix-ui-icons-common/core';
+import '@wix/design-system/styles.global.css';
+import '@wix/design-system/themes/odeditor.global.css';
+
+const BUSINESS_MANAGER_DEFAULTS: WixDesignSystemDefaultProps = {
+  Button: { size: 'small', skin: 'dark' },
+  IconButton: { size: 'small', skin: 'dark', priority: 'tertiary' },
+  TextButton: { size: 'small', skin: 'standard' },
+  Input: { size: 'small' },
+};
+
+export const BusinessManagerTheme: FC<{ children: ReactNode; locale?: string }> = ({
+  children,
+  locale = i18n.getLocale(),
+}) => (
+  <WixDesignSystemProvider locale={locale}>
+    <WixDesignSystemIconThemeProvider>
+      <IconThemeProvider theme="odeditor">
+        <WixDesignSystemDefaultPropsProvider defaults={BUSINESS_MANAGER_DEFAULTS}>
+          {children}
+        </WixDesignSystemDefaultPropsProvider>
+      </IconThemeProvider>
+    </WixDesignSystemIconThemeProvider>
+  </WixDesignSystemProvider>
+);
+```
+
+Duplicating these four providers per entry file is how one surface silently drifts out of the theme. Each piece earns its place:
+
+| Piece | Without it |
+| --- | --- |
+| `themes/odeditor.global.css` | `--wds-*` tokens keep pre-redesign values, so every component renders the old palette |
+| `WixDesignSystemIconThemeProvider` + `IconThemeProvider` | Icons stay classic — heavier strokes, wrong sizes beside redesigned components |
+| `WixDesignSystemDefaultPropsProvider` | Buttons and inputs render pre-redesign unless every call site passes `size`/`skin` by hand |
+
+**Order is outermost-first and fixed**, and `WixPatternsProvider` goes *inside* the wrapper: the defaults provider must sit above the components it supplies defaults to, and the WDS leaf UI inside a patterns shell is exactly that.
+
+A prop on a component still wins over the provider, so a one-off `size="medium"` is fine. **A nested `WixDesignSystemDefaultPropsProvider` replaces these defaults rather than merging**, so don't add a second for one subtree. And don't pass `features={{ newColorsBranding: true }}` — it predates the theme and is not a substitute.
+
+## 3. Where the wrapper goes
+
+**Write the file once per app; use it once per extension.** Every dashboard extension — page, modal, plugin — is a separate iframe, so each needs its own wrapper at its own root, in the file that owns the providers, never in a child, tab or helper file:
+
+| Surface | File | Section |
+| --- | --- | --- |
+| Page, Cases A/B/D (router-wired) | `{feature}.tsx` | [DRAFT_TEMPLATE_ROUTER.md § 1](dashboard-page/DRAFT_TEMPLATE_ROUTER.md#1-entry--location-is-manual-in-a-wix-cli-app-and-only-because-the-router-needs-it) |
+| Page, Case C (settings only) | `{feature}.tsx` | [DRAFT_TEMPLATE.md § 1](dashboard-page/DRAFT_TEMPLATE.md#1-entry--case-c-only-router-free-no-location-plumbing) |
+| Page with dynamic parameters | `withProviders.tsx` | [DYNAMIC_PARAMETERS.md](dashboard-page/DYNAMIC_PARAMETERS.md#provider-wrapper-implementation) |
+| Modal | the generated `<modal>.tsx` | [DASHBOARD_MODAL.md](DASHBOARD_MODAL.md#theme) |
+| Plugin | the generated plugin component | [DASHBOARD_PLUGIN.md](DASHBOARD_PLUGIN.md#theme) |
+
+Each surface's own doc shows the wrapper already in place. Copy that file as-is rather than re-adding providers by hand. A plugin is the least forgiving of the three: it renders inside a redesigned first-party page, so an unthemed one is surrounded by the very styling it is missing.
+
+## 4. Import icons from the lazy entry point
+
+Icons imported from the package root render classic **regardless of the providers above them**. Only the lazy entry point resolves through `IconThemeProvider`:
+
+```diff
+- import { Add, Confirm } from '@wix/wix-ui-icons-common';
++ import { Add, Confirm } from '@wix/wix-ui-icons-common/lazy';
+```
+
+Use `lazy` for every icon on a dashboard surface. Outside Business Manager it keeps rendering the current set, so this is the default import, not a Business-Manager-only one. An `iconKey` in a builder file names an icon for the platform rather than importing one — leave those alone.
+
+Two things worth knowing before you convert everything:
+
+- **`/lazy/system` is not where app icons live.** The `system` entry holds WDS's own internal component decorations (`CheckboxChecked`, `DropDownArrow`, …) — about 80 glyphs. Ordinary icons like `Add` and `Confirm` are in `/lazy` itself, so importing them from `/lazy/system` fails `tsc` with "no exported member".
+- **A lazy icon is a network fetch.** `core/icon.js` fetches the glyph JSON from the CDN at render time and suspends, falling back to an empty state on failure. That is fine in the dashboard, but a unit test asserting icon markup synchronously will see the fallback. If you need the redesign glyphs statically inlined with no provider and no fetch, `@wix/wix-ui-icons-common/odeditor` is a real entry point — `lazy` is still the default here because one import keeps tracking the right set both inside and outside Business Manager.
+
+## 5. Tokens and component adjustments
+
+Everything you style yourself — which `--wds-*` token replaces a hardcoded value, which `skin`/`size` prop replaces an inline `style`, the spacing unit the theme rebases, and the per-component adjustments the wrapper can't make for you — is in [BUSINESS_MANAGER_TOKENS.md](BUSINESS_MANAGER_TOKENS.md). Read it before styling anything by hand.
+
+## 6. Verify
+
+- The entry file wraps the page in `BusinessManagerTheme`, and that file imports both stylesheets and nests all four providers in order.
+- Every icon comes from `@wix/wix-ui-icons-common/lazy` (not the package root, and not `/lazy/system`).
+- `grep -rn "style={{" src/` and `grep -rn "#[0-9A-Fa-f]\{3,6\}" src/` return nothing for the page's own files, or only lines carrying a justification comment.
+- In devtools, a component's colours resolve from `--wds-*` properties. A literal means that element is still custom-styled.
+- Hover, focus, disabled, selected, error, warning and success all render — a token gap usually surfaces in a state, not at rest.

package/skills/wix-app/references/BUSINESS_MANAGER_TOKENS.md

@@ -0,0 +1,81 @@
+# Business Manager tokens — what to use instead of a hardcoded value
+
+Companion to [BUSINESS_MANAGER_THEME.md](BUSINESS_MANAGER_THEME.md), which sets the theme up. This file covers what you style yourself once it is wired.
+
+A hardcoded colour or font size keeps its old value while the themed components around it change — the most visible way a surface looks half migrated. Everything below was resolved against the installed `@wix/design-system` 1.330.0 `themes/odeditor.global.css` and component typings, not from a design-side migration note.
+
+## 1. Tokens, not hardcoded values
+
+Use a `--wds-*` custom property, or the component's own `skin`/`size` prop.
+
+The middle column is the value each token actually resolves to under the theme.
+
+| Use case | Resolves to | Token |
+| --- | --- | --- |
+| Primary action fill | `#2F5DFF` | `--wds-color-fill-standard-primary` |
+| Dark secondary fill | `#F0EFEF` | `--wds-color-fill-dark-secondary` |
+| Dark secondary, hover | `#E8E7E7` | `--wds-color-fill-dark-secondary-hover` |
+| Warning / success surface | yellow / green tones | `--wds-color-fill-warning-secondary`, `--wds-color-fill-success-secondary` |
+| Primary text | `#151414` | `--wds-color-text-standard-primary` |
+| Interactive / link | `#2F5DFF` | `--wds-color-text-primary` |
+| Destructive text | `#DF3336` | `--wds-color-text-destructive` |
+| Standard border | `#767574` | `--wds-color-border-dark-primary` |
+| Subtle border | `#DEDEDE` | `--wds-color-border-dark-secondary` |
+| Heading / body font | Madefor Display / Text | `--wds-font-family-display`, `--wds-font-family-default` |
+| Heading 1 size / line height | `32px` / **`40px`** | `--wds-font-size-heading-1`, `--wds-font-line-height-heading-1` |
+| Heading 1 weight | `500` | `--wds-font-weight-heading-1` |
+
+Two traps in that table, both of which produce a declaration the browser silently drops:
+
+- **`--wds-font-line-height-heading-1` resolves to 40px, not 32px.** If you are replacing a hardcoded `line-height: 32px`, the token changes your layout — that is the theme working, not a mistake, but know it before you swap.
+- **`--wds-font-letter-spacing-heading-1` is unitless** (`-0.50`), so `letter-spacing: var(--wds-font-letter-spacing-heading-1)` is invalid CSS. WDS itself emits it with a fallback; if you need it, wrap it: `calc(var(--wds-font-letter-spacing-heading-1) * 1px)`.
+
+**For a token not in the table, do not derive the name — look it up.** Grep the installed stylesheet, which is the only authority:
+
+```bash
+grep -oE '\-\-wds-color-fill-[a-z0-9-]+' node_modules/@wix/design-system/themes/odeditor.global.css | sort -u
+```
+
+Guessing from a Figma layer name invents tokens that do not exist (`-light` variants, for instance, are not a thing — the scale is `-primary`/`-secondary`/`-tertiary` with `-hover`/`-active`/`-disabled`), and `var()` on a missing name with no fallback makes the whole declaration invalid. You get no colour at all, and nothing in the build tells you.
+
+**On a WDS component the prop is the target, not the token:**
+
+```tsx
+// ❌ unchanged by a theme switch
+<Button style={{ background: '#2F5DFF' }}>Save</Button>
+<Badge style={{ background: '#F4B8B9' }}>Error</Badge>
+<Text style={{ color: '#DF3336' }}>Invalid email</Text>
+<Box style={{ background: '#F7F8FA', borderColor: '#DEDEDE' }}>
+
+// ✅
+<Button skin="standard">Save</Button>
+<Badge skin="danger">Error</Badge>
+<Text skin="error">Invalid email</Text>
+<Box backgroundColor="D75" border="1px solid" borderColor="D60">
+```
+
+A container that genuinely isn't a WDS component takes the tokens in its own CSS: `background: var(--wds-color-fill-standard-tertiary);`.
+
+**Tokens are CSS custom properties**, so a colour copied into a JavaScript object — a chart palette, a canvas value — does not follow the theme.
+
+**🛑 The theme rebases the spacing unit, from 6px to 4px.** `--wds-space-100` is `6px` under the default theme and `4px` under `odeditor`, and the `SP*` scale is defined against it (`SP2` is `calc(var(--wds-space-100) * 2)`). So the moment you import the theme stylesheet, `SP2` resolves to 8px rather than 12px, and numeric spacing (`<Box gap={2}>`) rebases with it. This is the one change that lands silently on every surface.
+
+Keep expressing spacing in `SP*` or numeric units — **because** they follow the theme — and never convert them to the pixel values in [WDS_LAYOUT.md](dashboard-page/WDS_LAYOUT.md#base-unit)'s table, which are the 6px-base figures and are wrong on a themed surface. Use that table for the 12-column grid and layout rhythm, not as a px conversion chart.
+
+No matching token? Ship it with a `// TODO: migrate when <token> exists` comment rather than bare. If you can't say in one sentence why it can't be a token, it should be one.
+
+## 2. Adjustments the wrapper doesn't cover
+
+| Component | Adjustment | Prop |
+| --- | --- | --- |
+| Tabs | Small, no divider | `size="small" showDivider={false}` — `showDivider` defaults on, so pass it |
+| Panel / modal headers | Smallest close/help button | `closeButtonProps={{ size: 'small' }}`, `helpButtonProps={{ size: 'small' }}` — `CloseButton` sizes are `small \| medium \| large` |
+| Modal headers / footers | Dividers off | `showHeaderDivider={false} showFooterDivider={false}` — **both default to `'auto'`**, which shows them once content scrolls, so doing nothing ships the dividers the redesign removes |
+| Slider | Horizontal spacing 12px, not 8px | Per call site |
+
+Two rows from the design-side migration note have **no API to land on at 1.330.0**, so don't go looking: a modal footer's secondary slot is `secondaryButtonProps?: Omit<ButtonProps, …>` and renders a `Button`, so "secondary becomes a text button at M size" needs a hand-built footer rather than a prop (and `CustomModalLayout` has no footer-skin prop at all — the only `light` skin is `footnoteSkin`, which styles the footnote); and `AngleInput` exposes no `size`, so "medium / 38px" is not reachable. Raise those with **#wix-design-system** rather than improvising.
+
+**Several adjustments the providers already make for you** — don't redo them by hand: a nested icon button is Dark / Tertiary from the wrapper's `IconButton` default, and `WixDesignSystemIconThemeProvider` already supplies the Accordion caret. `Accordion`, `CloseButton`, `Tooltip`, `Popover`, `Thumbnail`, `SidePanel` and ~20 more are all legal keys of `WixDesignSystemDefaultProps`, so anything you find yourself repeating per call site probably belongs in `BUSINESS_MANAGER_DEFAULTS` instead.
+
+Two genuine author decisions remain: a **standalone** text button uses the standard (blue) skin while one beside a primary or secondary button uses Dark; and empty states are **typography only**, no legacy illustrations (on a collection page the empty state comes from the patterns shell — [DRAFT_TEMPLATE_COLLECTION.md](dashboard-page/DRAFT_TEMPLATE_COLLECTION.md)).
+

package/skills/wix-app/references/DASHBOARD_MODAL.md

@@ -28,6 +28,47 @@ wix generate --params '{"extensionType":"DASHBOARD_MODAL","title":"<title>","fol
 
 The CLI generates the folder, the modal `.tsx`, the config file, the builder file, the UUID, and the `src/extensions.ts` registration. After scaffolding, implement the modal UI in the generated `.tsx`.
 
+## Theme
+
+A modal opens as **its own iframe, separate from the page that opened it** — so theming the page does nothing for it. A themed page opening an unthemed modal is a common and very visible split: the dialog arrives in the pre-redesign look on top of a redesigned page.
+
+Wrap the generated `<modal>.tsx` in the app's `BusinessManagerTheme`, at the root, above `CustomModalLayout`:
+
+```tsx
+import type { FC } from 'react';
+import { CustomModalLayout } from '@wix/design-system';
+import { BusinessManagerTheme } from '../../BusinessManagerTheme';
+import modalConfig from './<modal>.config';
+
+const Modal: FC = () => (
+  <BusinessManagerTheme>
+    <CustomModalLayout
+      title={modalConfig.title}
+      showHeaderDivider={false}
+      showFooterDivider={false}
+      closeButtonProps={{ size: 'small' }}
+      /* … */
+    />
+  </BusinessManagerTheme>
+);
+```
+
+The wrapper file is written once per app and reused by every extension — [BUSINESS_MANAGER_THEME.md § 2](BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app). Icons come from `@wix/wix-ui-icons-common/lazy`, and anything you style yourself uses `--wds-*` tokens or a `skin`/`size` prop — [BUSINESS_MANAGER_TOKENS.md](BUSINESS_MANAGER_TOKENS.md).
+
+**The redesign changes modal chrome specifically**, and the wrapper cannot make these for you:
+
+| Part | Redesign | How |
+| --- | --- | --- |
+| Header / footer dividers | Removed | `showHeaderDivider={false} showFooterDivider={false}`. **Both default to `'auto'`**, which shows them once content scrolls — so doing nothing ships the dividers the redesign removes |
+| Close / help button | Smallest size | `closeButtonProps={{ size: 'small' }}`, `helpButtonProps={{ size: 'small' }}` — `CloseButton` sizes are `small \| medium \| large` |
+| Destructive confirm | Token, not a red literal | `skin="destructive"` on the confirm `Button` |
+
+A confirm dialog's footer is a primary `Button` plus a cancel, and because the cancel sits beside a primary it takes the **Dark** skin rather than the wrapper's `standard` default.
+
+**One thing the design note asks for that has no API at 1.330.0:** "the footer's secondary action is a `TextButton` at M size". `CustomModalLayout`'s slot is `secondaryButtonProps?: Omit<ButtonProps, …>` and renders a `Button`; there is no footer-skin prop either (the only `light` skin is `footnoteSkin`, which styles the footnote). Achieving it means hand-building the footer — so take it to **#wix-design-system** rather than improvising, and if you do hand-build it, the cancel needs both `skin="dark"` and `size="medium"` against the wrapper's `TextButton` default of `small`.
+
+**Nothing renders a modal until something opens it**, so an unthemed dialog survives more than the usual checks: it is invisible to `tsc` and `wix build`, and also to a careful look at the page in `wix preview`, because it isn't on screen yet. Trigger the dialog before calling it done — that is the only step that shows it.
+
 ## Quick Reference
 
 | Task | Method | Example |

package/skills/wix-app/references/DASHBOARD_PAGE.md

@@ -14,6 +14,8 @@ Do this first because a bare filtered table answers "what are all the records" a
 
 The order, what each library owns, and how to look a name up are stated once: [SKILL.md → Component Selection Order](../SKILL.md#component-selection-order).
 
+**Theme:** the page's iframe inherits none of the Business Manager redesign. Wrap the entry file in the app's `BusinessManagerTheme`, import icons from `@wix/wix-ui-icons-common/lazy`, and style with `--wds-*` tokens or `skin`/`size` props — [BUSINESS_MANAGER_THEME.md](BUSINESS_MANAGER_THEME.md), [BUSINESS_MANAGER_TOKENS.md](BUSINESS_MANAGER_TOKENS.md).
+
 ## Scaffold
 
 Use `wix generate --params` with all required fields:

package/skills/wix-app/references/DASHBOARD_PLUGIN.md

@@ -29,13 +29,28 @@ For the complete list of available slot IDs, see [Slots Reference](dashboard-plu
 - **Wix Dashboard SDK** (`@wix/dashboard`) — Interact with the dashboard page's data passed to the slot
 - **Wix Design System** (`@wix/design-system`) — Native-looking React components matching Wix's own dashboard UI
 
+## Theme
+
+A plugin is its own iframe, so **it inherits nothing from the host page it sits in** — not even though that page is a redesigned first-party Wix app. This makes a plugin the least forgiving dashboard surface: an unthemed one renders classic icons and pre-redesign buttons directly beside the redesigned Stores/Bookings/Blog UI framing it.
+
+Wrap the plugin component in the app's `BusinessManagerTheme` (the example below does), import icons from `@wix/wix-ui-icons-common/lazy`, and style with `--wds-*` tokens or `skin`/`size` props — never a hardcoded colour or an inline `style` override ([BUSINESS_MANAGER_TOKENS.md](BUSINESS_MANAGER_TOKENS.md)). The wrapper file itself is written once per app: [BUSINESS_MANAGER_THEME.md § 2](BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app).
+
+Two things to get right in a slot specifically:
+
+- **Match the host's density, don't fight it.** The wrapper's defaults (`Button` small/dark, `IconButton` small/dark/tertiary) are what the surrounding page uses. Overriding them per call site is how a plugin starts looking like a different product.
+- **A nested icon button inside your own card or list row is Dark / Tertiary.** The wrapper's `IconButton` default already gives you this — don't re-specify `skin="standard"` on it.
+
+A plugin has no page of its own, so looking at it means navigating to the host app's page that carries the slot — the Blog posts or Bookings staff screen itself.
+
 ## Interacting with Dashboard Data
 
 Use `observeState()` from the Dashboard SDK to receive data from the host dashboard page:
 
-```typescript
+```tsx
 import { dashboard } from "@wix/dashboard";
-import { useEffect, useState } from "react";
+import { useEffect, useState, type FC } from "react";
+import { Card, Text } from "@wix/design-system";
+import { BusinessManagerTheme } from "../../BusinessManagerTheme";
 
 const Plugin: FC = () => {
   const [params, setParams] = useState<Record<string, unknown>>({});
@@ -47,13 +62,13 @@ const Plugin: FC = () => {
   }, []);
 
   return (
-    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
+    <BusinessManagerTheme>
       <Card>
         <Card.Content size="medium">
           <Text>Received data: {JSON.stringify(params)}</Text>
         </Card.Content>
       </Card>
-    </WixDesignSystemProvider>
+    </BusinessManagerTheme>
   );
 };
 ```

package/skills/wix-app/references/dashboard-page/DRAFT_TEMPLATE.md

@@ -59,21 +59,22 @@ Case C has one page and no rows to open, so it needs no router and no manual `lo
 import type { FC } from 'react';
 import { withDashboard } from '@wix/patterns';
 import { WixPatternsProvider } from '@wix/patterns/provider';
-import { WixDesignSystemProvider } from '@wix/design-system';
-import '@wix/design-system/styles.global.css';
+import { BusinessManagerTheme } from '../../BusinessManagerTheme'; // BUSINESS_MANAGER_THEME.md § 2
 import { {Feature}SettingsPage } from './{Feature}SettingsPage'; // DRAFT_TEMPLATE_SETTINGS.md
 
 const Page: FC = () => (
-  <WixDesignSystemProvider>
+  <BusinessManagerTheme>
     <WixPatternsProvider>
       <{Feature}SettingsPage />
     </WixPatternsProvider>
-  </WixDesignSystemProvider>
+  </BusinessManagerTheme>
 );
 
 export default withDashboard(Page);
 ```
 
+`BusinessManagerTheme` is the app's own wrapper around the design-system providers, the `odeditor` theme stylesheet and the Business Manager default props — [BUSINESS_MANAGER_THEME.md § 2](../BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app) has the file to write once per app. **Business Manager passes none of the redesign through the extension's iframe**, so a bare `WixDesignSystemProvider` here renders the pre-redesign look while `tsc`, `wix build` and `wix preview` all pass. `WixPatternsProvider` nests inside it, never above.
+
 Cases A, B and D differ — they need `location` supplied manually for `PatternsReactRouter`. See [DRAFT_TEMPLATE_ROUTER.md](DRAFT_TEMPLATE_ROUTER.md) rather than adding that plumbing here; it's dead code without a router underneath it.
 
 ## 2. Collection page — Case A, B, D

package/skills/wix-app/references/dashboard-page/DRAFT_TEMPLATE_ROUTER.md

@@ -1,19 +1,18 @@
 # Draft Template — Cases A, B and D (router-wired)
 
-**Applies to [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md)'s Cases A, B and D.** All three need `PatternsReactRouter`, because in all three a row opens a page of its own — a panel is not the drill-in ([UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md)). Case A's detail route is read-only (§4); B and D route to a full `EntityPage`. The collection and settings components live in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md); this file covers only what a router adds — the entry file, the app shell, and the detail/entity page.
+**Applies to [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md)'s Cases A, B and D.** All three need `PatternsReactRouter`, because in all three a row opens a page of its own — a panel is not the drill-in ([UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md)). Case A's detail route is read-only (§4); B and D route to a full `EntityPage`. This file covers only what a router adds.
 
 Every snippet below is copied from the installed `dist/docs/*.md` this session read, not from memory.
 
 ## 1. Entry — `location` is manual in a Wix CLI app, and only because the router needs it
 
-`PatternsReactRouter` reads the page location through `container.usePageLocation()`, which only `withDashboard`'s `location` prop feeds — nothing supplies it automatically in a Wix CLI app the way Yoshi BM flow does:
+`PatternsReactRouter` reads the page location through `container.usePageLocation()`, which only `withDashboard`'s `location` prop feeds — nothing supplies it automatically in a Wix CLI app:
 
 ```tsx
 // {feature}.tsx — Case A, B or D
 import { useEffect, useState, type FC } from 'react';
 import { dashboard } from '@wix/dashboard';
-import { WixDesignSystemProvider } from '@wix/design-system';
-import '@wix/design-system/styles.global.css';
+import { BusinessManagerTheme } from '../../BusinessManagerTheme';
 import { {Feature}App } from './{Feature}App';
 
 type PageLocation = Parameters<Parameters<typeof dashboard.observeState>[0]>[1]['pageLocation'];
@@ -29,16 +28,18 @@ const Page: FC = () => {
   }, []);
 
   return (
-    <WixDesignSystemProvider>
+    <BusinessManagerTheme>
       {location ? <{Feature}App location={location} /> : null}
-    </WixDesignSystemProvider>
+    </BusinessManagerTheme>
   );
 };
 
 export default Page;
 ```
 
-**Skipping this is a runtime-only failure.** Per `PatternsReactRouter`'s own docs: "Nothing catches this before runtime — type checking and bundling both pass, because neither renders the page." `tsc` and `wix build` will not catch a missing `location` — only opening the page in a browser will. This is exactly why [Step 5's Preview](../../SKILL.md#validation) is not optional for Case B/D.
+`BusinessManagerTheme` belongs here, not in `{Feature}App.tsx` — its default props must apply above `WixPatternsProvider`. Write it once per app: [BUSINESS_MANAGER_THEME.md](../BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app).
+
+**Skipping either the theme or `location` is a runtime-only failure.** Per `PatternsReactRouter`'s own docs: "Nothing catches this before runtime — type checking and bundling both pass, because neither renders the page." Only a browser catches a missing `location` or an unthemed page, which is why [Step 5's Preview](../../SKILL.md#validation) is not optional.
 
 ## 2. App shell — provider, router, routes
 

package/skills/wix-app/references/dashboard-page/DYNAMIC_PARAMETERS.md

@@ -136,49 +136,35 @@ This dashboard page manages dynamic parameters for an embedded script. The param
 - Display the preview alongside the settings form using Layout and Cell components
 - The preview should react to parameter changes in real-time
 
-## Example Implementation
+## Files to Generate
 
-See the generated site-popup example for a complete reference implementation:
-- src/extensions/dashboard/withProviders.tsx - Provider wrapper with WDS
-- src/extensions/dashboard/pages/page.tsx - Dashboard page with parameter management (wrapped with withProviders)
-- src/extensions/dashboard/components/site-popup-settings.tsx - Settings form component
-- src/extensions/dashboard/types.ts - Type definitions
+When dynamic parameters are present, generate all of these — the two wrapper files are not optional:
 
-Key implementation patterns from the example:
-1. withProviders.tsx wraps the component with WixDesignSystemProvider
-2. page.tsx exports the component wrapped: export default withProviders(MyComponent)
-3. Parameters are saved as individual string fields, not as JSON
-4. Parameters are loaded with proper type conversion (string to boolean, string to number, etc.)
-5. Use embeddedScripts directly from '@wix/app-management'
+| File | Role |
+| --- | --- |
+| `dashboard/BusinessManagerTheme.tsx` | Theme wrapper — [BUSINESS_MANAGER_THEME.md § 2](../BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app) |
+| `dashboard/withProviders.tsx` | Provider wrapper (below) |
+| `dashboard/pages/page.tsx` | The page, exported wrapped in `withProviders` |
+| `dashboard/types.ts` | Parameter type definitions |
+| Component files | Settings forms, previews |
 
-## File Generation Requirements
-
-When dynamic parameters are present, you MUST generate these files:
-1. src/extensions/dashboard/withProviders.tsx - Provider wrapper (REQUIRED for WDS)
-2. src/extensions/dashboard/pages/page.tsx - The main dashboard page component
-3. src/extensions/dashboard/types.ts - Type definitions for the parameters (if needed)
-4. Any additional component files (settings forms, previews, etc.)
-
-The withProviders.tsx is NOT optional - it must always be generated when there are dynamic parameters.
+Parameters are saved as individual string fields, never as one JSON string, and converted back to their real types on load. Use `embeddedScripts` directly from `@wix/app-management`.
 
 ## Provider Wrapper Implementation
 
-You MUST generate the following file: src/extensions/dashboard/withProviders.tsx
-
-This file is REQUIRED to wrap dashboard components with the Wix Design System provider.
+Generate `src/extensions/dashboard/withProviders.tsx`:
 
 ```typescript
 import React from 'react';
-import { WixDesignSystemProvider } from '@wix/design-system';
 import { i18n } from '@wix/essentials';
+import { BusinessManagerTheme } from './BusinessManagerTheme';
 
 export default function withProviders<P extends {} = {}>(Component: React.FC<P>) {
   return function DashboardProviders(props: P) {
-    const locale = i18n.getLocale();
     return (
-      <WixDesignSystemProvider locale={locale} features={{ newColorsBranding: true }}>
+      <BusinessManagerTheme locale={i18n.getLocale()}>
         <Component {...props} />
-      </WixDesignSystemProvider>
+      </BusinessManagerTheme>
     );
   };
 }
@@ -187,16 +173,16 @@ export default function withProviders<P extends {} = {}>(Component: React.FC<P>)
 export { withProviders };
 ```
 
-This file must be included in your generated files output.
+Business Manager passes none of the redesign through the extension's iframe, so a wrapper holding `WixDesignSystemProvider` alone renders the pre-redesign look while compiling and previewing cleanly. `features={{ newColorsBranding: true }}` predates the theme and does not substitute for it.
 
 ## Using Provider Wrapper
 
 In your dashboard page component (page.tsx):
-1. Import the withProviders wrapper: `import withProviders from '../../withProviders';`
+1. `import withProviders from '../../withProviders';`
 2. Import embeddedScripts from '@wix/app-management'
-3. DO NOT wrap your component with WixDesignSystemProvider - the provider wrapper does this
-4. Export the component wrapped with withProviders: `export default withProviders(MyComponent);`
-5. Your component should only contain the Page component and its content, not providers
+3. Add no design-system providers in the page — `withProviders` owns them
+4. Export wrapped: `export default withProviders(MyComponent);`
+5. The component holds the Page and its content, not providers
 
 Example structure:
 ```typescript
@@ -204,8 +190,7 @@ import { useEffect, useState, type FC } from 'react';
 import { dashboard } from '@wix/dashboard';
 import { embeddedScripts } from '@wix/app-management';
 import { Page, Card, Button, ... } from '@wix/design-system';
-import '@wix/design-system/styles.global.css';
-import withProviders from '../../withProviders';
+import withProviders from '../../withProviders'; // owns the stylesheets and providers
 
 const MyDashboardPage: FC = () => {
   const [options, setOptions] = useState<MyScriptOptions>(defaultOptions);
@@ -253,9 +238,7 @@ export default withProviders(MyDashboardPage);
 ## Critical Notes
 
 - Only implement UI for parameters that are relevant to your specific use case - ignore parameters that don't apply
-- ALWAYS generate withProviders.tsx when there are dynamic parameters
-- ALWAYS wrap the dashboard page export with withProviders()
-- DO NOT use WixDesignSystemProvider directly in the dashboard page component - use withProviders instead
+- ALWAYS generate `BusinessManagerTheme.tsx` and `withProviders.tsx`, and wrap the page export with `withProviders()` — no design-system providers in the page itself
 - ALWAYS use embeddedScripts directly from '@wix/app-management'
 - ALWAYS convert parameter values to strings when saving (embeddedScripts.embedScript must receive all string values in the parameters object)
 - ALWAYS convert string parameters back to proper types when loading (e.g., 'true' -> true for booleans, string to number for numbers)

package/skills/wix-headless/SKILL.md

@@ -9,7 +9,6 @@ allowed-tools:
   - Bash(npm install *)
   - Bash(npm run *)
   - Bash(node *)
-  - Bash(bash *)
   - Bash(cd *)
   - Bash(ls *)
   - Bash(mkdir *)

package/skills/wix-headless/references/CAPABILITIES.md

@@ -67,7 +67,7 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 
 ### bookings — appointments and classes
 - **Intent:** book / appointment / schedule / class / session / reserve a slot — a **service or appointment with a provider** (a stylist, trainer, tutor, clinic, studio).
-- **Not bookings — route to `restaurants` instead:** a **table at a restaurant** is a Table Reservations concern, not a bookable service; and a **special dining occasion guests reserve** — a wine tasting, cheese pairing, chef's table, or tasting-menu evening at a restaurant — is a **restaurants → Table Reservations *experience*** (see the restaurants entry), **not** a bookings service. Reach for `bookings` only when what's booked is a standalone service/class with a provider, never a seat at a restaurant.
+- **Not bookings — route to `restaurants` instead:** a **table at a restaurant** is a Table Reservations concern, not a bookable service; and a **special dining occasion guests reserve** — a chef's table, cheese pairing, or tasting-menu evening at a restaurant — is a **restaurants → Table Reservations *experience*** (see the restaurants entry), **not** a bookings service. Reach for `bookings` only when what's booked is a standalone service/class with a provider, never a seat at a restaurant.
 - **Not bookings — route to `rentals` instead:** when the **customer chooses how long** they want something, and what's booked is a **thing rather than a person** — a room by the hour, a desk for three days, a van for the weekend. The tell is a duration *range* the customer picks within. A 60-minute haircut is `bookings`; a meeting room booked for 1–8 hours is `rentals`.
 - **Required site features:** a list of services; a page per service; a way to pick a time and book it.
 - **Implementation checklist:** show each service's name, duration, and price; show the staff or provider; show the available time slots; a book action; a confirmation after booking.
@@ -85,8 +85,8 @@ The verticals the skill operates end-to-end today: **stores · blog · cms · fo
 - **Implementation checklist:** show each plan's name, price, and billing cycle; list what each plan includes (the perks); a clear "choose plan" action; highlight a recommended tier where it makes sense.
 
 ### restaurants — menus and food
-- **Intent:** menu / restaurant / cafe / food / dish list / order food / dine-in / **reserve a table** / a **special dining occasion guests reserve** (wine tasting, cheese pairing, chef's table, tasting-menu evening).
-- **Required site features:** a menu organized into sections; each item with a name, description, and price. **Add-ons, each on demand (separate apps/features; see `SETUP.md`):** online ordering, table reservations, and — **when the brief names special dining occasions** — **experiences** (a reservation that *is* a curated occasion at the restaurant, e.g. a wine-and-cheese pairing), which ride on the Table Reservations app.
+- **Intent:** menu / restaurant / cafe / food / dish list / order food / dine-in / **reserve a table** / a **special dining occasion guests reserve** (chef's table, cheese pairing, tasting-menu evening).
+- **Required site features:** a menu organized into sections; each item with a name, description, and price. **Add-ons, each on demand (separate apps/features; see `SETUP.md`):** online ordering, table reservations, and — **when the brief names special dining occasions** — **experiences** (a reservation that *is* a curated occasion at the restaurant, e.g. a chef's table), which ride on the Table Reservations app.
 - **Experiences vs bookings — decide here:** an **experience** is a **reservation that is itself a special dining occasion at the restaurant** — it books seats at the restaurant's own location and carries its own name, per-guest price, schedule, and booking form. Use it for pairing sessions, tastings, and chef's tables. Use the separate **`bookings`** vertical only for a **service/appointment/class with a provider** that isn't a seat at the restaurant. For anything a restaurant hosts and seats, prefer an experience.
 - **Implementation checklist:** show the menu grouped into sections in order; each item's name, description, price, and labels (vegan, spicy…) and modifiers / variants where they exist; an order action if online ordering is wired; a reserve-a-table action if reservations are wired; **if experiences are wired, list each experience with its name, description, per-guest price, and schedule, and a reserve-seats action.**
 

package/skills/wix-headless/references/DISCOVERY.md

@@ -52,7 +52,7 @@ For each capability, build its `intent.<cap>` block — the inputs the seed step
 | bookings | `{ serviceCount, servicesNamed: [] }` | `serviceCount: 2`, brand-derived service names |
 | rentals | `{ unitType, serviceCount, resourceCount, servicesNamed: [] }` | `unitType: "HOUR"` (`"DAY"` if the brief rents by the day), `serviceCount: 2`, `resourceCount: 2`, brand-derived item names |
 | pricing-plans | `{ planCount, tiersNamed: [] }` | `planCount: 2` (e.g. Basic / Pro), monthly billing |
-| restaurants | `{ menuName, sections: [{ name, itemCount }], ordering?, reservations?, experiences?: [{ name }] }` | one menu, 2 sections, `itemCount: 3` each; add-ons only when the brief names them. **`experiences[]`** = special dining occasions guests reserve (wine/cheese pairing, chef's table) — a restaurant *reservation that is an experience*, **not** the `bookings` vertical (see `CAPABILITIES.md`). |
+| restaurants | `{ menuName, sections: [{ name, itemCount }], ordering?, reservations?, experiences?: [{ name }] }` | one menu, 2 sections, `itemCount: 3` each; add-ons only when the brief names them. **`experiences[]`** = special dining occasions guests reserve (chef's table, tasting menu) — a restaurant *reservation that is an experience*, **not** the `bookings` vertical (see `CAPABILITIES.md`). |
 | portfolio | `{ collections: [{ name }], projectCount }` | one brand-derived collection, `projectCount: 3` |
 
 Counts are deliberately small (the seed shows the shape, not a full catalog).

package/skills/wix-headless/references/SDK_HANDOFF.md

@@ -48,7 +48,7 @@ Before implementing a capability, Read the local recipe linked in its row.
 | restaurants — online ordering (add-on; only when the Orders app is in the run) | add `@wix/ecom` + `@wix/redirects` to the row above | `how-to-code-restaurant-orders.md` — ordering cart/checkout on top of the menu display. |
 | portfolio | `@wix/portfolio` (+ `media` from `@wix/sdk` to resolve image strings; **no** `@wix/ecom`/`@wix/redirects` — display-only) | `how-to-code-portfolio.md` — Portfolio v1 display-only read. |
 | restaurants — table reservations (add-on; only when the Table Reservations app is in the run) | `@wix/table-reservations` (a **distinct** package from `@wix/restaurants`; **no ecom/redirects** — a reservation is a hold, not a purchase) | `how-to-code-restaurant-reservations.md` — book-a-table hold→reserve. |
-| restaurants — experiences (add-on; special dining occasions guests reserve — wine/cheese pairing, chef's table) | `@wix/table-reservations` (same package; the **`experiences`** namespace + `timeSlots`/`reservations`) | `how-to-code-restaurant-reservations.md` — "Booking an experience" (query experiences → scheduled slots → reserve with `experienceId`). |
+| restaurants — experiences (add-on; special dining occasions guests reserve — chef's table, tasting menu) | `@wix/table-reservations` (same package; the **`experiences`** namespace + `timeSlots`/`reservations`) | `how-to-code-restaurant-reservations.md` — "Booking an experience" (query experiences → scheduled slots → reserve with `experienceId`). |
 
 > **Cross-cutting packages** (`CAPABILITIES.md` § "Cross-cutting capabilities"): these aren't per-vertical rows but get added to the package list when the run used them. If **coupons** were seeded, add `@wix/marketing`. The eCommerce checkout packages (`@wix/ecom`, `@wix/redirects`) are already folded into the stores row above — include them once when any purchase-flow vertical is present.