@wix/agent-skills 1.22.0 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/SKILL.md

@@ -28,8 +28,8 @@ Helps build extensions for Wix CLI applications. Covers all extension types: das
     - [ ] **Every filter reaches the query**: declared in the collection hook's `filters` and read inside `fetchData`. Filter UI that never narrows the rows is a defect that looks like a feature.
 
     A filtered table with no drill-in and no working filters is what gets built when nobody states the requirement — the most common way a generated dashboard disappoints. The aggregate is the judgment call; the drill-in and the filters are not.
-  - [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Identified which case in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#which-case-matches-the-request) — A (collection only), B (collection + entity), C (settings only), or D (all three) — matches what Step 2's workflow analysis above just established — then copied and adapted that case's files. Composing the page shell, provider nesting, or router wiring from scratch when a case already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the matching case's files don't cover, not a replacement for starting there.
-  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md), then **probe** `dist/docs/index.json` with `grep`/`python3` — never a whole-file `Read`, which truncates it silently. It is the one file that says, per symbol, where to import it from (`importPath`), whether its props live in the doc or in a `.d.ts` (`bundle`), and which worked examples exist (`examples`). Upgrade `@wix/patterns` if that file is missing. Patterns API facts come only from the published `dist/docs/` (pages), `dist/examples/` (worked calls) and `dist/dts-bundle/` (types) trees — never from `src/`, `dist/esm/`, or any other path inside the package, with one named exception: `dist/types/` when a bundle has stubbed the prop you need (WIX_PATTERNS_DOCS.md step 5).
+  - [ ] **🛑 Template-First Gate (MANDATORY, dashboard UI only, comes before writing any shell/provider/router):** Identified which case in [DRAFT_TEMPLATE.md](references/dashboard-page/DRAFT_TEMPLATE.md#which-case-matches-the-request) — A (collection only), B (collection + entity), C (settings only), or D (all three) — matches what Step 2's workflow analysis above just established — then copied and adapted that case's files. Composing the page shell, provider nesting, or router wiring from scratch when a case already shows it is the failure mode this gate exists to prevent — the Patterns/Component Docs gates below are for what the matching case's files don't cover, not a replacement for starting there. The reverse holds too: a case replaces composing the shell, never the discovery chain, so every symbol the case doesn't show still goes through the next gate.
+  - [ ] **🛑 Patterns Docs Gate (MANDATORY for any dashboard page UI):** Read [WIX_PATTERNS_DOCS.md](references/WIX_PATTERNS_DOCS.md) **before the first command that touches `node_modules/@wix/patterns`** — its discovery chain (`pkg-root.cjs`, the index, `Composition and Providers.md` once, `Collection Toolkit.md` for which component serves a need) lives only in that file, and this line is a summary of its step 1, not a substitute for opening it. Then **probe** `dist/docs/index.json` with `grep`/`python3` — never a whole-file `Read`, which truncates it silently. It is the one file that says, per symbol, where to import it from (`importPath`), whether its props live in the doc or in a `.d.ts` (`bundle`), and which worked examples exist (`examples`). Upgrade `@wix/patterns` if that file is missing. Patterns API facts come only from the published `dist/docs/` (pages), `dist/examples/` (worked calls) and `dist/dts-bundle/` (types) trees — never from `src/`, `dist/esm/`, or any other path inside the package, with one named exception: `dist/types/` when a bundle has stubbed the prop you need (WIX_PATTERNS_DOCS.md step 5).
   - [ ] **🛑 Component Docs Gate (MANDATORY, dashboard UI only):** For each patterns symbol you are about to write, decided **from the index** which single artifact answers the question you actually have — `importPath`, `examples`, or `bundle` — and read only that one, per [Component Selection Order](#component-selection-order)'s "the short version". State which artifact you read per symbol, and why, before the first line of JSX. Reading a doc *and* its bundle for the same symbol, or opening a page for an `importPath` the index already gave you, is the failure this gate exists to prevent.
 
     For the object `useTableCollection()` returns, read [TABLE_STATE.md](references/dashboard-page/TABLE_STATE.md) — a state object you receive rather than construct, whose members are unobvious and several plausible ones absent.
@@ -226,6 +226,14 @@ Use a Dashboard Modal for dialogs that neither write nor display a listed record
 
 Find the entity the user mentioned in the [entity → SDK module map](references/SDK_MODULE_MAP.md) and use that package. If the entity isn't listed or you're unsure, run `SearchWixSDKDocumentation` for it — **never conclude CMS with zero MCP calls**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.
 
+**SDK types:** access them through the namespace you import, as `<namespace>.<TypeName>`, using any type name shown in the docs — never import a type by name from the `@wix/<pkg>` root.
+
+```ts
+import { orders } from '@wix/ecom';
+const rows: orders.Order[] = [];              // ✅
+// import type { Order } from '@wix/ecom';    // ❌ has no exported member 'Order'
+```
+
 ---
 
 ## Data Collection Inference
@@ -440,7 +448,7 @@ Only after validation passes, provide a **concise summary section** at the top o
 - ✅ Dependencies: [Installed / status message]
 - ✅ TypeScript: [No compilation errors / status]
 - ✅ Build: [Completed successfully / status]
-- ✅/⚠️ Preview: [Running at URL / Failed - reason]
+- ✅/⚠️ Preview: [Created — Dashboard URL / Failed - reason]
 
 **⚠️ IMPORTANT: [X] manual step(s) required to complete setup** (see "Manual Steps Required" section below)
 ```
@@ -480,7 +488,7 @@ Execute these steps sequentially after all implementation is complete. See [APP_
 1. **Package Installation** — Detect package manager, run install
 2. **TypeScript Compilation** — `npx tsc --noEmit -p .`
 3. **Build** — `npx wix build`
-4. **Preview** — `npx wix preview`
+4. **Preview** — `npx wix preview`, in the foreground: it uploads, prints the preview URLs and exits on its own, so no `timeout`, backgrounding or `sleep`
 
 Stop and report errors if any step fails. Check `.wix/debug.log` on failures.
 

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

@@ -85,23 +85,29 @@ npx wix build
 
 ### Step 4: Preview Deployment
 
-Start the preview server:
+`npx wix preview` is a one-shot command, not a server: it uploads a preview build, prints the preview URLs and **exits on its own**, in seconds. Run it in the foreground and read its output:
 
 ```bash
 npx wix preview
 ```
 
+Don't wrap it in `timeout` (macOS has none, so the call fails before preview runs), background it, `sleep` or poll a log for it, or `kill` it afterwards. There is no process left to wait for or stop.
+
 **Success criteria:**
-- Preview server starts successfully
-- Preview URLs are generated (both site and dashboard)
+- The command exits 0
+- It printed `✔ Preview created successfully!` and the preview URLs
+
+**URL extraction:** the URLs follow `Open the preview on:`, one per line, each in parentheses:
 
-**URL extraction:** Parse the terminal output to find both preview URLs. Look for patterns like:
-- Site preview: `Site preview: https://...` or `Site URL: https://...`
-- Dashboard preview: `Dashboard preview: https://...` or `Preview URL: https://...` or `Your app is available at: https://...`
+```
+  › Site (https://www.wix.com/app-installer?appId=...)
+  › Editor (https://www.wix.com/app-installer?appId=...)
+  › Dashboard (https://www.wix.com/app-installer?appId=...)
+```
 
-Extract both URLs and provide them to the user for manual verification.
+A long URL wraps across several lines. Join the lines up to the closing `)` before using it. Give the Site and Dashboard URLs to the user for manual verification.
 
-**On failure:** Report the preview startup errors, [check the debug log](#debug-log-on-errors) for detailed diagnostics, and stop validation.
+**On failure:** Report the preview errors, [check the debug log](#debug-log-on-errors) for detailed diagnostics, and stop validation.
 
 ## Validation Report
 
@@ -111,7 +117,7 @@ After completing all steps, provide a summary:
 - Dependencies: ✓ All packages installed successfully
 - TypeScript: ✓ No compilation errors
 - Build: ✓ Compiled successfully
-- Preview: ✓ Running at [URL]
+- Preview: ✓ Created — [Dashboard URL]
 
 **Fail:**
 - Identify which step failed
@@ -138,7 +144,7 @@ Read: .wix/debug.log (with offset to the end)
 | Package installation fails | Missing lock file, network issues, or corrupted node_modules | Delete `node_modules` and lock file, then reinstall |
 | TypeScript compilation fails | Type mismatches, missing declarations, or incorrect types | Fix TypeScript errors shown in `npx tsc --noEmit -p .` output |
 | Build fails | TypeScript errors, missing dependencies, or internal CLI error | Fix TypeScript errors in source; for non-obvious failures, check `.wix/debug.log` |
-| Preview fails to start | Port conflict, config issue, or internal CLI error | Check `wix.config.json`; if unclear, check `.wix/debug.log` for details |
+| Preview fails | Config issue, not logged in, or internal CLI error | Check `wix.config.json`; if unclear, check `.wix/debug.log` for details |
 | Console errors in preview | Runtime exceptions | Check browser console output |
 | UI not rendering | Component errors | Review component code and imports |
 | CLI error with no clear message | Truncated terminal output | Read `.wix/debug.log` for the full error trace and stack details |

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/SDK_MODULE_MAP.md

@@ -41,4 +41,6 @@ Data owned by an existing Wix business app is read and written through that app'
 | locations / site properties | `@wix/business-tools` |
 | app instances | `@wix/app-management` |
 
+Types from these packages are accessed as `<namespace>.<TypeName>` — see [SDK types](../SKILL.md#sdk-first-rule-existing-wix-app-data-is-never-cms).
+
 If the entity isn't listed or you're unsure, run `SearchWixSDKDocumentation` for it — **never conclude CMS with zero MCP calls**. CMS is only for data your app itself introduces (configuration, rules, app-specific records) that no Wix app manages.

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

@@ -1,6 +1,6 @@
 # Draft Template — the starting point for every dashboard page
 
-**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** Pick the case below, copy its files, rename, and adapt fields/API calls/data source. Only leave this file for [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md), the package's own `Collection Toolkit.md` guide, [TABLE_STATE.md](TABLE_STATE.md), a component doc, or an MCP lookup when the request needs something no case shows.
+**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** Pick the case below, copy its files, rename, and adapt fields/API calls/data source. Only leave this file when the request needs something no case shows, and then go to [WIX_PATTERNS_DOCS.md](../WIX_PATTERNS_DOCS.md) first — before any lookup inside `node_modules/@wix/patterns`, `index.json` included. It routes you to the package's own `Collection Toolkit.md` guide, a component doc or an example; [TABLE_STATE.md](TABLE_STATE.md) and MCP lookups come after it.
 
 Every snippet below was copied from the installed `dist/docs/*.md` and `dist/dts-bundle/*.d.ts`, not from memory — confirm props against your own installed version before deviating.
 

package/skills/wix-app/references/editor-react-component/ACCESSIBILITY.md

@@ -1,7 +1,6 @@
 # Accessibility Implementation and Review
 
-Use this reference while authoring Editor React Component props and JSX, then
-run the review command once the JSX is complete.
+Use while authoring; run the review after JSX is complete.
 
 ## Contents
 
@@ -41,7 +40,9 @@ function Toggle({ elementProps }: ToggleProps) {
 
   return (
     <button {...toggleProps} aria-label={toggleA11y?.ariaLabel ?? ARIA_LABELS.toggle}>
-      <ChevronIcon aria-hidden="true" />
+      <svg aria-hidden="true" viewBox="0 0 16 16">
+        <path d="m3 6 5 5 5-5" fill="none" stroke="currentColor" />
+      </svg>
     </button>
   );
 }

package/skills/wix-app/references/editor-react-component/ANIMATED-COMPONENTS.md

@@ -5,23 +5,9 @@ Use this reference when the component's primary content **auto-advances or plays
 
 Every such component must ship an on-stage **play/pause button**.
 
-## Contents
-
-- [Apply When](#apply-when)
-- [Required Contract](#required-contract)
-- [Announce Manually Selected Parallel Content](#announce-manually-selected-parallel-content)
-- [Define Props](#1-define-props)
-- [Manage Playback State](#2-manage-playback-state)
-- [Add the Play/Pause Button](#3-add-the-playpause-button)
-- [Suppress Autoplay in `component.preview.tsx`](#4-suppress-autoplay-in-componentpreviewtsx)
-- [Edit the generated `component.preview.tsx`](#edit-the-generated-componentpreviewtsx)
-- [Checklist](#checklist)
-
 ## Apply When
 
-Apply automatically — without being asked — whenever the component has an
-`autoPlay` prop **or** its primary content is a **startable / loopable**
-animation a visitor would reasonably want to start or stop:
+Apply whenever the component has `autoPlay` or startable/loopable primary content:
 
 - Slideshow, carousel, slider, or gallery that advances slides/cards
 - Lottie / JSON vector animations
@@ -94,8 +80,20 @@ export interface MyAnimationProps {
 }
 ```
 
-The example shows a looping animation. Omit `loop` when the component does not
-support repeat behavior; do not add it only to match the example.
+Omit `loop` when repeat is unsupported.
+
+### Lottie / JSON source
+
+For Lottie, `animationUrl?: string` is a JSON URL, not `VectorArt` (SVG).
+This and its renderer are exceptions to the generic media/dependency rules in
+`COMPONENT-CONTRACT.md`. Check `package.json`: use `lottie-web` if present,
+otherwise add it as a runtime dependency. Import `lottie` and
+`type AnimationItem` from it. In an effect, call
+`lottie.loadAnimation({ container, renderer: 'svg', path: animationUrl,
+loop, autoplay: false })`; keep the item in a ref, destroy it on cleanup,
+and use `play()` / `pause()` when `isPlaying` changes. Browser work belongs in
+effects. If no URL is supplied, bundle a valid local Lottie JSON asset and
+import it with `?url` as the component default; a placeholder URL renders blank.
 
 ## 2. Manage Playback State
 
@@ -109,20 +107,22 @@ const reducedMotion = useReducedMotion();
 
 const [isPlayOn, setIsPlayOn] = React.useState(() => (autoPlay ?? true) && !reducedMotion);
 
-const skipInitialAutoPlaySync = React.useRef(true);
+const previousAutoPlay = React.useRef(autoPlay);
 React.useEffect(() => {
-  if (skipInitialAutoPlaySync.current) {
-    skipInitialAutoPlaySync.current = false;
-    return;
+  if (previousAutoPlay.current !== autoPlay) {
+    setIsPlayOn((autoPlay ?? true) && !reducedMotion);
+  } else if (reducedMotion) {
+    setIsPlayOn(false);
   }
-  setIsPlayOn(autoPlay ?? true);
-}, [autoPlay]);
+  previousAutoPlay.current = autoPlay;
+}, [autoPlay, reducedMotion]);
 
 const handlePause = () => setIsPlayOn(false);
 const handleResume = () => setIsPlayOn(true);
 ```
 
-`reducedMotion` is a runtime signal, not a manifest/data prop.
+`reducedMotion` is runtime-only. Pause when the OS turns reduced motion on, but
+do not restart when it turns off. Resume can still override the preference.
 
 Derive runtime playback from `isPlayOn` plus only needed conditions. Without
 another condition, use `const isPlaying = isPlayOn`. A carousel, slideshow,
@@ -140,7 +140,10 @@ clears `isStoppedByFocus`.
 
 ## 3. Add the Play/Pause Button
 
-Create play/pause icons that visually match the component's style. Use simple recognizable shapes — a triangle for play, two rectangles for pause — implemented as inline SVG so there is no external icon dependency. Size and color of SVG should be controlled by CSS variables declared on the button level: --icon-size and --icon-color.
+Use inline SVG icons: a triangle for play and two bars for pause. Declare
+`--icon-size` and `--icon-color` on the button. Apply `var(--icon-size)` to the
+SVG's CSS `width` and `height` (or React `style`), not raw SVG attributes;
+set button `color: var(--icon-color)` and SVG `fill: currentColor`.
 
 Position the button absolutely so it overlays the content without pushing other elements out of place:
 

package/skills/wix-app/references/editor-react-component/BRANDED-COMPONENTS.md

@@ -28,8 +28,14 @@ using CSS Modules `@value`, then consume with `var()`.
 - Do not use `var(--wst-*)` directly; import the `@value` alias first.
 - Do not pass a fallback as `var()`'s second argument
 - Do not use `@import`; CSS Modules resolves theme aliases through `@value`.
-- Do not use `wst-base-1-color` for text. Prefer heading/paragraph color tokens,
-  or `wst-base-2-color` when a base contrast color is required.
+- Do not use `wst-base-1-color` for text on a light surface. Prefer
+  heading/paragraph color tokens for body text.
+- Use matching control tokens: pair `wst-button-primary-background-color` with
+  `wst-button-primary-color` for a primary CTA (or the secondary pair for a
+  secondary CTA). Do not mix `wst-links-and-actions-color` with
+  `wst-base-2-color` as button background and text: they are unrelated tokens
+  and may fail contrast. Check the rendered contrast of every state, and choose
+  a different token pair or design if it fails.
 
 ## Checklist
 

package/skills/wix-app/references/editor-react-component/COMPONENT-CONTRACT.md

@@ -3,17 +3,6 @@
 Use this reference when defining props, defaults, named-part wiring, complex data,
 or internal file boundaries.
 
-## Contents
-
-- [Public Props Contract](#public-props-contract)
-- [Numeric Range Constraints](#numeric-range-constraints)
-- [Named Parts and `elementProps`](#named-parts-and-elementprops)
-- [Content and Data](#content-and-data)
-- [Active-Item Components](#active-item-components)
-- [Defaults and Resources](#defaults-and-resources)
-- [Internal File Splitting](#internal-file-splitting)
-- [Checklist](#checklist)
-
 ## Public Props Contract
 
 Keep identity and platform contracts together with component-specific data and
@@ -54,6 +43,9 @@ Rules:
 - Default to common optional SDK callbacks by capability; add specialized ones
   when requested. Keep implementation handlers internal.
 - Use `Array<T>`, not `T[]`, for exported arrays.
+- A CTA with a real destination is a native link with that `href`. If it only
+  performs an action, use a native button. Never use `href="#"` as a fallback;
+  it creates a focusable link without a meaningful destination.
 
 ## Numeric Range Constraints
 
@@ -153,6 +145,7 @@ slides, steps). Skip for always-visible lists, multi-select, or multi-expand.
   `@wix/react-component-utils`. The type argument must match the array prop name
   exactly, and `defaultProps` must set the index to `0`.
 - Render all bodies with `.map()`. Active body gets --active; inactive bodies get functional CSS visibility, aria-hidden, and inert.
+- With React 18 types, spread `...(!isActive ? { inert: 'true' } : {})` onto an inactive body; this emits the boolean HTML attribute without a TypeScript prop error. Use the app's typecheck instead of a scratch TypeScript project.
 - Provide keyboard navigation and the matching ARIA pattern.
 
 ```ts
@@ -184,11 +177,16 @@ media type, whether it is a top-level prop or a field in an array item. Name
 the field for the media itself (`image`, `video`, `audio`, and so on), not for
 one representation of it.
 
+Common fields in the installed types: `Image` has required `url: string` and
+optional `uri`, `alt`, `width`, `height`; `Link` has optional `href`, `target`
+(`'_self' | '_blank'`), and `rel`. Use `image.url` for `<img src>`,
+`image.alt` for its alternative text, and `link.href` for `<a href>`.
+
 Do not represent media as a URL/source string or split its metadata across
 primitive props. Preserve the media object through the public contract so the
-component can consume all of its supported data. See
-`node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts` for the
-full list.
+component can consume all of its supported data. Inspect the installed media
+type declaration only if a needed field is not covered here or a typecheck
+reports an error.
 
 ## Defaults and Resources
 

package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md

@@ -56,6 +56,7 @@ that semantic element is the root. Do not wrap it just to host root props.
 
 Use flat, top-level selectors. Each selector must target one class plus an
 optional state pseudo-class or global state modifier.
+Put state overrides before bare classes so the manifest keeps resting defaults.
 
 ```css
 .heading {
@@ -103,7 +104,7 @@ Choose the simplest root shape that fits the component:
 
 - column: `--display: flex; flex-direction: column`
 - row: `--display: flex; flex-direction: row`
-- split layout: `--display: grid; grid-template-columns: 1fr 1fr`
+- split layout: `--display: grid; grid-template-columns: repeat(2, minmax(0, 1fr))`
 - responsive collection: `--display: grid; grid-template-columns: repeat(auto-fit, minmax(...))`
 
 Do not hardcode the root's pixel dimensions. Installation defaults belong in
@@ -136,7 +137,7 @@ the extension file.
 ## Responsiveness and Direction
 
 Respond to the component container, not the browser viewport. Prefer intrinsic
-flex/grid sizing, `minmax()`, `auto-fit`, `1fr`, and `clamp()`. Do not add
+flex/grid sizing and tracks that can shrink below content size. Do not add
 viewport `@media` rules; Wix owns page breakpoints.
 
 Use logical inline-axis properties so layout flips automatically in RTL:
@@ -171,7 +172,7 @@ Use this pattern:
 
 .grid {
   --columns: 3;
-  grid-template-columns: repeat(var(--columns), 1fr);
+  grid-template-columns: repeat(var(--columns), minmax(0, 1fr));
 }
 ```