@wix/agent-skills 1.23.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.23.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/EDITOR_REACT_COMPONENT.md

@@ -1,13 +1,11 @@
 # Wix Editor React Component Builder
 
 Build Editor React Components for Harmony/Studio2 Wix CLI apps only. First
-determine **create vs edit**; for edits, inspect the existing component and
-never re-scaffold.
+determine **create vs edit**; for edits, inspect the existing component.
 
 ## File Contract
 
-Use the Wix CLI scaffold as the source of truth. Do not replace it with a custom
-layout or a hand-written manifest. Preserve these file responsibilities:
+Keep the Wix CLI scaffold and file roles:
 
 | File | Ownership | Purpose |
 | --- | --- | --- |
@@ -16,37 +14,55 @@ layout or a hand-written manifest. Preserve these file responsibilities:
 | `<component-name>.module.css` | Edit | Scoped component styles |
 | `component.tsx` | Keep generated | Wire component and `defaultProps` with `withDefaults` |
 | `component.preview.tsx` | Edit narrowly | Sync preview adapter, one crucial data field, root class |
-| `<component-name>.generated.ts` | NEVER edit | Generated manifest — do not edit |
+| `<component-name>.generated.ts` | NEVER edit | Generated manifest |
 | `<component-name>.extension.ts` | Edit narrowly | Supported partial manifest overrides |
 
-Supplementary files (constants, hooks, sub-components) are allowed; keep scaffold
-roles intact.
+Supplementary files are allowed; keep scaffold roles intact.
 
 ## Workflow
 
-1. **Scaffold only when creating.** If the component folder does not exist, run
-   inside the Wix app project (the folder with `wix.config.json`):
+1. **Scaffold only when creating.** Run in the Wix app (`wix.config.json`).
+   Check the current directory, then this workspace; never search the OS:
 
    ```bash
-   npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description"}'
+   npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A meaningful description of component's intent and functionality"}'
    ```
 
-   Creates `src/extensions/site/components/<component-name>/` and registers the
-   extension in `src/extensions.ts`. Do not rerun for an existing component.
+   Never rerun the scaffold for an existing component.
+   Write a meaningful `description` in 1-2 plain sentences (max 300 chars): what
+   the user sees, when to use it, and capabilities that affect that choice.
+   Don't repeat the component name or add implementation details.
 
-2. **Run the dependency preflight.** Verify that all component creation and
-   accessibility-review dependencies are installed:
+2. **Run the dependency preflight.** Check required packages:
 
    ```bash
-   node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','typescript','@types/eslint-plugin-jsx-a11y','jsdom','axe-core'];const missing=ps.filter(p=>!(require.resolve.paths(p)||[]).some(d=>fs.existsSync(path.join(d,p,'package.json'))));if(missing.length){console.error('Missing dependencies: '+missing.join(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y jsdom axe-core; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-dev @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y jsdom axe-core; fi; }
+   deps=(@wix/react-component-schema @wix/react-component-utils @wix/editor-react-types)
+   dev=(@babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y jsdom axe-core)
+
+   node - "${deps[@]}" "${dev[@]}" <<'JS' || {
+   const fs = require('fs'), path = require('path');
+   const missing = process.argv.slice(2)
+     .map(p => p.replace(/@<7$/, ''))
+     .filter(p => !require.resolve.paths(p)?.some(d => fs.existsSync(path.join(d, p, 'package.json'))));
+   if (missing.length) {
+     console.error(`Missing dependencies: ${missing.join(', ')}`);
+     process.exit(1);
+   }
+   JS
+     d="$PWD"
+     while [[ "$d" != / && ! -f "$d/yarn.lock" ]]; do d="$(dirname "$d")"; done
+     if [[ -f "$d/yarn.lock" ]]; then install=(yarn add); else install=(npm install); fi
+     "${install[@]}" "${deps[@]}" && "${install[@]}" -D "${dev[@]}"
+   }
    ```
 
-3. **Plan the contract and structure.** Identify props, semantic root, named
-   parts, and design states; read routed references below before writing code.
+3. **Plan.** Identify props, root, parts, and states; read routed references.
+   Use the scaffold and references before package declarations; probe an API
+   only when undocumented or a typecheck fails.
 
-4. **Implement the editable sources.** Preserve the scaffold contract: props in
-   the props file, logic in TSX, styles in the CSS Module. Do not edit
-   `*.generated.ts`.
+4. **Implement.** Keep props, logic, and styles in their scaffolded editable
+   files. Format edited source files with the app's configured formatter before
+   checking formatting. Never edit or format `*.generated.ts`.
 
 5. **Run the accessibility review.** Once the JSX is complete, run from the
    same folder (`<SKILL_ROOT>` is the directory containing the active `SKILL.md`):
@@ -55,42 +71,36 @@ roles intact.
    node <SKILL_ROOT>/scripts/scan-a11y-review.cjs src/extensions/site/components/<component-name>
    ```
 
-   Then follow [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md):
-   fix confirmed findings, rerun after each fix pass (at most two), and report
-   what remains.
+   Follow [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md); fix and
+   rerun at most twice, then report remaining findings.
 
-6. **Configure the editor extension when required.** For a new component or a
-   requested sizing, installation, or manifest change, apply
+6. **Configure the editor extension.** For creation or a requested sizing,
+   installation, or manifest change, apply
    [`editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md)
-   to `<component-name>.extension.ts`. Otherwise leave the file unchanged.
-   Synchronize `requiredDataFields` and `rootClassName` in
-   `component.preview.tsx`.
+   to the extension; otherwise leave it unchanged. Synchronize preview
+   `requiredDataFields` and `rootClassName`.
 
-7. **Generate and validate.** Run:
+7. **Generate and validate.** Batch implementation edits, then build and
+   generate the manifest once:
 
    ```bash
    npx wix build && npx wix generate manifest
-   npx tsc --noEmit
    ```
 
-   Run relevant tests and lint when available. Inspect the regenerated manifest;
-   never repair it by hand. On failure, diagnose with
+   Run `npx tsc --noEmit`, relevant tests/lint, and the accessibility review.
+   If later edits affect a check, rerun that
+   check. Inspect the manifest when generated; never hand-repair it. Diagnose
+   failures with
    [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 
-8. **Report the result.** Summarize edited files and checks. Call out any
-   unresolved conflict, missing dependency, unsupported CLI version, or check
-   that could not run.
+   For creation/layout changes, complete the routed overflow resize review.
 
-## Reference Policy
+8. **Report.** Summarize files, checks, blockers, and checks that could not run.
 
-- Read **only** matching required + triggered optional rows; optional triggers
-  become required when they match.
-- References refine the active step; they do not restart workflow or expand scope.
-- Never re-scaffold an existing component or edit `*.generated.ts`.
+## Reference Policy
 
-`SKILL.md` is the only reference router; reference files are self-contained
-leaves. For existing components, preserve out-of-scope public props, styling,
-extension configuration, and supporting files.
+Read only matched references. Preserve unrelated behavior. `SKILL.md` routes;
+references are leaves.
 
 ### Required References
 
@@ -102,6 +112,7 @@ extension configuration, and supporting files.
 | Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
 | Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
 | Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
+| Creating or changing layout/content | [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
 | Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
 | Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
 
@@ -109,7 +120,7 @@ extension configuration, and supporting files.
 
 | Trigger | Read |
 | --- | --- |
-| Interactive/selectable part or custom state | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Interactive/selectable part, custom state, or open/collapse toggle | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
 | Creating interactive components or changing interactions/callbacks | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
 | Browser APIs, effects, or time-dependent output | [`SSR.md`](editor-react-component/SSR.md) |
 | Non-established CSS feature or DOM API, or user asks for one by name | [`BROWSER-SUPPORT.md`](editor-react-component/BROWSER-SUPPORT.md) |
@@ -135,14 +146,17 @@ extension configuration, and supporting files.
   top-level props).
 - Native design states: pair selectors with injected modifiers; keep non-input
   `:focus-visible` standalone unless editable focus is requested; toggle custom
-  state classes from data.
+  state classes from data, each with a matching `:global()` rule.
+- Open/collapse components: expose a props-only `isOpen: ElementState<boolean>`
+  root state and sync internal state from it.
 - Single-visible-body arrays: `name` per item, `ActiveItemIndex<'prop'>`, render
   all bodies, hide inactive accessibly.
 - Autoplay/loop: play/pause control, honor reduced motion, suppress autoplay in
   editor design mode.
-- `component.preview.tsx`: preserve this outer-to-inner composition, inline or
-  through component variables:
+- Resizable layout: keep required content usable at 320px. Reflow visible
+  groups inside their page and cap track minima with
+  `minmax(min(100%, <minimum>), 1fr)`. Follow [`OVERFLOW.md`](editor-react-component/OVERFLOW.md).
+- Preview composition, inline or through variables:
   `withDefaults(withFallbackPlaceholder(PreviewOrComponent, options), defaultProps)`.
-  Keep `withDefaults` outermost, wrap the preview adapter when present, use one
-  crucial `requiredDataFields` entry, and match `rootClassName` to the root
-  global class.
+  Keep `withDefaults` outermost; use one crucial data field and match the root
+  class.

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