@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-app/references/app-tools/TOOLS.md

@@ -0,0 +1,75 @@
+# App Tools Extension Reference
+
+## Overview
+
+The `APP_TOOLS` extension declares the tools your app exposes to the Wix AI assistant. Each tool entry tells the AI assistant what the tool does, what it accepts, and what it returns — so the assistant can discover and invoke it at runtime.
+
+The AI assistant does NOT call these tools directly. It uses the declarations here to understand the tool's purpose and invoke your **Tools Provider service plugin** at runtime. See [TOOLS_PROVIDER.md](../service-plugin/TOOLS_PROVIDER.md) for the runtime handler.
+
+## Registration
+
+Scaffold the extension with the CLI — it creates the `.extension.ts` file and registers it in `src/extensions.ts` automatically:
+
+```bash
+wix generate --params '{"extensionType":"APP_TOOLS","name":"my-tools"}'
+```
+
+The generated file lives at `src/extensions/backend/app-tools/my-tools/my-tools.extension.ts`. Replace the stub tool with your own:
+
+```typescript
+import { extensions } from '@wix/astro/builders';
+
+export default extensions.appTools({
+  id: '<generated-uuid>',
+  name: 'my-tools',
+  tools: [
+    {
+      methodName: 'get-order-status',
+      description: 'Returns the current fulfillment status, shipping carrier, and tracking number for a customer order. Use this tool when a collaborator or customer asks where their order is, whether it has shipped, when it will arrive, or needs a tracking number. Requires a valid orderId.',
+      requestSchema: {
+        type: 'object',
+        properties: {
+          orderId: { type: 'string', description: 'The order ID to look up.' }
+        },
+        required: ['orderId']
+      },
+      responseSchema: {
+        type: 'object',
+        properties: {
+          status: { type: 'string' },
+          trackingNumber: { type: 'string' }
+        }
+      },
+      activated: true
+    }
+  ]
+});
+```
+
+## `AppToolConfig` Fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `methodName` | `string` | Yes | Unique word identifying the tool. Used to route calls in the service plugin handler. 1–30 characters. |
+| `description` | `string` | Yes | Natural-language description the AI assistant uses to decide when to invoke this tool. Write it like a prompt: state what the tool does, list the user intents or trigger phrases that should activate it, and describe what it returns. A narrow one-liner reduces relevance matching — prefer 2–4 sentences covering intent, triggers, and output. 10–1000 characters. |
+| `requestSchema` | `Record<string, any>` | No | JSON Schema describing the tool's request payload. The AI assistant uses this for context — it is NOT validated by Wix at call time. |
+| `responseSchema` | `Record<string, any>` | No | JSON Schema describing the tool's response payload. |
+| `activated` | `boolean` | Yes | Only tools with `activated: true` are called by the AI assistant. |
+
+## Important Constraints
+
+- `tools` array: min 1, max 100 tools per extension.
+- `methodName` must be unique across all tools in the extension — it is the routing key in the service plugin handler.
+- Schemas are advisory for the AI assistant; your handler must still validate inputs defensively.
+- Only `activated: true` tools are invoked. Use `activated: false` to temporarily disable a tool without removing it.
+
+## Relationship to the Tools Provider
+
+The `APP_TOOLS` extension is the **declaration** side. The **execution** side is the Tools Provider service plugin registered with `toolsProviderConfig`:
+
+```
+APP_TOOLS (declaration)  →  AI assistant discovers & selects a tool
+toolsProviderConfig (SPI) →  Wix calls your runTool handler at runtime
+```
+
+Both extensions must be registered for the feature to work end-to-end. See [APP_TOOLS.md](../APP_TOOLS.md) for the full picture and [TOOLS_PROVIDER.md](../service-plugin/TOOLS_PROVIDER.md) for the handler implementation.

package/skills/wix-app/references/backend-event/COMMON-EVENTS.md

@@ -12,10 +12,15 @@ This reference lists common event types, SDK imports, permissions, and links. Fo
 
 ## eCommerce Events
 
+Order events use **`@wix/ecom`** (namespace `orders`). Order **refund** events are the exception: they live in **`@wix/payments`** (namespace `refunds`), not `@wix/ecom`.
+
 | Event | Import | Handler Call | Permission | API Reference |
 | --- | --- | --- | --- | --- |
 | Order created | `import { orders } from "@wix/ecom"` | `orders.onOrderCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-created?apiView=SDK) |
 | Order approved | `import { orders } from "@wix/ecom"` | `orders.onOrderApproved(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderApproved](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-approved?apiView=SDK) |
+| Order canceled | `import { orders } from "@wix/ecom"` | `orders.onOrderCanceled(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderCanceled](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-canceled?apiView=SDK) |
+| Refund created | `import { refunds } from "@wix/payments"` | `refunds.onRefundCreated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundCreated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-created?apiView=SDK) |
+| Refund updated | `import { refunds } from "@wix/payments"` | `refunds.onRefundUpdated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundUpdated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-updated?apiView=SDK) |
 | Cart created | `import { cart } from "@wix/ecom"` | `cart.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-created?apiView=SDK) |
 | Cart updated | `import { cart } from "@wix/ecom"` | `cart.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-updated?apiView=SDK) |
 

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

@@ -23,8 +23,8 @@ Host Module '@wix/dashboard' 'navigate()' method for navigating between dashboar
 import { dashboard } from '@wix/dashboard';
 // Navigate to your own app's page with some internal state
 dashboard.navigate({pageId: <your-page-id>, relativeUrl: "/an/internal/state?param=value"})
-// Navigate to a relative route of the current page
-dashboard.navigate({ relativeUrl: "/some/internal/route" });
+// Navigate to a relative URL within a page (pageId required even for relative paths)
+dashboard.navigate({ pageId: '<your-page-id>', relativeUrl: "/some/internal/route" });
 // Navigate to the Products List page
 dashboard.navigate({ pageId: "0845ada2-467f-4cab-ba40-2f07c812343d" });
 // Add a button that navigates to the Products List page (React/TSX)

package/skills/wix-app/references/editor-react-component/A11Y-REVIEW-REFERENCE.md

@@ -0,0 +1,172 @@
+# Editor React Component A11y Review Reference
+
+Use this reference for decisions that require code inspection after running the scanners in [`A11Y-REVIEW.md`](A11Y-REVIEW.md). The scanner output owns rule-specific context: rule ID, location, message, resolution path, evidence, and confidence. Do not maintain a separate rule catalog here.
+
+## Scanner Result Handling
+
+Treat every scanner finding as a lead until the component implementation confirms how the flagged behavior reaches the rendered element.
+
+1. Read the full finding, including evidence and confidence when present.
+2. Trace the component topology through local wrappers, shared primitives, and package implementations.
+3. Deduplicate findings that identify the same issue at the same location.
+4. Assign a verdict: `confirmed`, `false-positive`, or `not-relevant`.
+5. Fix confirmed issues inline, then re-run both scanners on changed JSX files.
+
+When both scanners flag the same issue, keep the finding with the strongest semantic evidence. The scanners complement each other; a finding from one scanner is not automatically stronger because of its tier.
+
+## Confidence Model
+
+### High
+
+Use high confidence when the code and scanner evidence unambiguously show the violation, for example:
+
+- the flagged rendered element and static props establish the behavior directly
+- the component implementation resolves to the flagged semantic element
+- an explicit polymorphic prop establishes the rendered element
+
+Fix high-confidence findings immediately.
+
+### Medium
+
+Use medium confidence when:
+
+- props strongly imply the rendered semantics
+- the implementation only partially resolves but preserves likely semantics
+- the component name, props, and surrounding evidence strongly agree
+
+Read the surrounding code. If it confirms the inference, fix the issue. If it contradicts the inference, discard the finding. If the implementation remains unresolved, treat it as low confidence.
+
+### Low
+
+Use low confidence when:
+
+- only weak heuristics support the semantic guess
+- the implementation cannot be resolved
+- runtime props or spreads can materially change the rendered semantics
+
+Continue tracing the code. Fix only after the issue is confirmed; otherwise leave the code unchanged.
+
+### Confidence vs. Actionability
+
+Confidence answers whether the issue is real. It does not decide whether a confirmed fix is safe.
+
+- Confirmed + safe/local fix: fix now.
+- Confirmed + risky behavior change or non-local refactor: leave unchanged.
+- Unconfirmed or ambiguous: leave unchanged.
+
+If the violation is visible in the code and has a localized, behavior-preserving fix, treat it as confirmed and apply the fix.
+
+Valid reasons to leave code unchanged:
+
+- semantics remain ambiguous after reading the available code
+- product intent cannot be derived from the code
+- the fix requires a risky behavior change or a non-local refactor
+
+Do not leave a confirmed safe/local issue unchanged because it is low severity, secondary, shared, or outside the first file in scope.
+
+## Semantic Resolution
+
+Resolve the rendered behavior in this order:
+
+1. The flagged JSX element and its static props
+2. Explicit polymorphic props such as `as="a"` or `component="button"`
+3. The local component implementation
+4. Installed package source or declarations in `node_modules`
+5. Prop evidence such as `href`, `to`, `src`, `alt`, and `role`
+6. Component-name heuristics
+
+For local imports, follow the exported component's rendered root. Continue through local or package components until the semantics resolve or the evidence becomes too weak.
+
+For package imports, resolve the import from `node_modules` and inspect its exported entry point. If the package hides its rendered semantics, use prop and naming evidence without assigning more confidence than the evidence supports.
+
+## Tier 2 Manual Review Checklist
+
+Run this checklist after scanner findings are triaged. Tier 2 is required even when both scanners return zero findings.
+
+### Semantic Targeting
+
+- Do ARIA attributes land on the semantically correct element instead of a layout wrapper?
+- Do labels, descriptions, and roles reach the actual interactive or landmark element?
+- Do wrappers preserve the semantics exposed by their API?
+
+### Icon-Only and Visual-Only States
+
+- Do icon-only buttons, links, or controls have an accessible name?
+- If visible text is hidden, is it visually hidden in an accessibility-safe way instead of removed from the accessibility tree?
+- Do meaningful icons or images expose accessible text when needed?
+
+### CSS and Hidden Content
+
+- Does `display: none` remove content that should remain available to assistive technology?
+- Are hidden or collapsed states consistent across visuals, focusability, and the accessibility tree?
+- Do conditional classes or CSS variables create states where labels or instructions disappear from assistive technology?
+
+### Decorative vs. Meaningful Content
+
+- Are decorative separators, ornaments, and repeated icons hidden from assistive technology?
+- Are meaningful visuals, status icons, or graphics named appropriately?
+
+### Focus and Interaction Consistency
+
+- Can hidden or collapsed items still receive focus?
+- Do interactive-looking elements expose the correct role and keyboard behavior?
+- Do disabled, inert, or collapsed states behave consistently for keyboard users and assistive technology?
+- Search all in-scope files for `onClick` on elements without built-in interaction (`div`, `span`, `section`, `header`, `footer`, `li`, `td`, and similar tags). Include conditional patterns such as `{...(condition && { onClick: handler })}`. Verify that each match also has the required `role`, `tabIndex`, and keyboard handler (`onKeyDown` or `onKeyUp`). A missing combination is a high-confidence finding.
+- Before fixing missing keyboard semantics, check for nested interactive children, existing focus management, and the condition that enables interaction. Use the [pre-fix checks](#pre-fix-checks-for-adding-button-semantics-to-a-non-interactive-element).
+
+### Structural Semantics
+
+- Are landmarks, headings, and list semantics preserved through wrappers and layout components?
+- When the component implements breadcrumbs, tabs, menus, dialogs, or similar patterns, do the expected semantics reach the rendered structure?
+
+### Editor React Component Contracts
+
+- Are ARIA attributes routed through the typed `a11y` prop and converted at the correct element?
+- Do icon-only labels come from `constants.ts` or user-configurable `a11y` instead of hardcoded strings?
+- Does the component preserve direction support and isolate each `ReactNode` content prop with `dir="ltr"`?
+- Do extension overrides preserve a11y-relevant manifest fields generated from JSX?
+
+## Fix Principles
+
+- Use the rule ID, message, and evidence emitted by the scanner as the rule-specific fix context.
+- Read the surrounding code before editing.
+- Preserve visual and runtime behavior.
+- Prefer the smallest correct change and avoid unrelated refactors.
+- Fix the semantic owner: the component root, the correct inner element, a shared base, or the call site that supplies the value.
+- When a wrapper already accepts and forwards a required prop, fix the call site. When it does not, update the wrapper contract and forwarding before fixing the call site.
+- Do not hardcode reusable accessibility values such as alternative text. Accept them through the component API when they depend on consumer content.
+- Route Editor React Component ARIA through `a11y` and `convertA11yKeysToHtmlFormat(a11y)` according to [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
+
+## Pre-Fix Checks for Adding Button Semantics to a Non-Interactive Element
+
+Before adding `role="button"`, `tabIndex`, and keyboard handlers to an element such as `<div>`, verify all four conditions below.
+
+### 1. Interactive Children
+
+Check whether the element conditionally or unconditionally contains `<a>`, `<button>`, `<input>`, `<Link>`, or a component that resolves to an interactive element. Button semantics on the parent would create nested interaction.
+
+If interactive children are possible, either exclude that branch from the parent's interaction condition or use a separate control element.
+
+### 2. Existing Focus Management
+
+Check whether the element already receives `tabIndex` from another source, such as `getTabIndexAttribute`, an a11y prop spread, or an interactions framework. Determine the prop merge order and keep one source authoritative.
+
+When an existing a11y spread should win, place the conditional interaction spread before it so `tabIndex: 0` only acts as a fallback.
+
+### 3. Interaction Condition
+
+Read the full boolean expression that enables interaction. Verify that it:
+
+- excludes states that already render an interactive child
+- excludes editor preview, externally controlled, disabled, or reduced-motion states when required
+- uses explicit comparisons such as `=== undefined` or `=== true` when `true`, `false`, and `undefined` have different meanings
+
+Fix a fragile condition as part of the accessibility change. Correct semantics attached to the wrong state are still incorrect behavior.
+
+### 4. Accessible Name Scope
+
+Decide whether an accessible label names the interaction or the component as a whole. Keep a component-level label outside the interaction condition so it persists in non-interactive states. Apply an action-specific label only while that action is available.
+
+## After Fixing
+
+Re-run both scanners on changed `.tsx` / `.jsx` files. Continue with `npx wix build`, `npx wix generate manifest`, and the project's TypeScript check as required by [`A11Y-REVIEW.md`](A11Y-REVIEW.md#phase-5-verify).

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

@@ -0,0 +1,138 @@
+# Editor React Component A11y Review
+
+Use this reference to audit and fix accessibility issues in an Editor React Component. This complements [`ACCESSIBILITY.md`](ACCESSIBILITY.md), which covers ARIA prop conventions and patterns, with an automated scan and triage workflow over the component's runtime, manifest extension, and shared code.
+
+This is not a separate skill. It runs as part of the Editor React Component workflow described in [`../SKILL.md`](../SKILL.md). Run it after editing the React/CSS sources and before `npx wix build && npx wix generate manifest`.
+
+## Scanner Invocation
+
+Two scanners live at the Editor React Component skill root:
+
+```bash
+node scripts/scan-a11y-eslint.cjs <file1> [file2] ...
+node scripts/scan-a11y-code.cjs  <file1> [file2] ...
+```
+
+Run them from the consumer project root (the Wix CLI app's working directory) so dependencies resolve from the project's `package.json`. Pass paths relative to that cwd. The dependency preflight is part of the workflow in [`../SKILL.md`](../SKILL.md).
+
+The ESLint scanner uses the explicitly declared `eslint-plugin-jsx-a11y` dev dependency. The semantic scanner follows imports up to four levels deep and adds resolution evidence and confidence to its findings.
+
+## When To Run
+
+Run the review when:
+
+- You finished editing an Editor React Component's `.tsx` / `.module.css` files.
+- The user asks for an a11y audit, accessibility review, or a11y fix on an Editor React Component.
+- The user mentions missing alt text, invalid ARIA, broken semantics, direction issues, icon-only controls, or wrappers that hide accessibility issues.
+
+Do not run on generated files (`*.generated.ts`); they are regenerated from JSX and CSS Modules.
+
+## Target Resolution
+
+Resolve scope before scanning:
+
+| User says | Required scope |
+|-----------|----------------|
+| Specific file | That file plus any imported wrappers / shared components it renders |
+| "this component" | `<componentName>.tsx`, `component.tsx`, `<componentName>.extension.ts`, plus shared imports |
+| A component name | All in-component files (excluding `*.generated.ts`) |
+| "full audit" | Every Editor React Component folder under `src/extensions/site/components/`, excluding `*.generated.ts` |
+
+## Workflow
+
+Execute every phase inline while editing. Do not pause for approval or add a separate summary phase.
+
+### Phase 1: Resolve Topology
+
+1. Enumerate in-scope files under `src/extensions/site/components/<componentName>/`.
+2. Include imported shared components or utilities that affect rendered semantics.
+3. Exclude `*.generated.ts`.
+4. Trace the topology from the component through wrappers and shared primitives to the rendered element.
+
+### Phase 2a: ESLint JSX A11y Scan (Tier 0)
+
+```bash
+node scripts/scan-a11y-eslint.cjs <file1> [file2] ...
+```
+
+Use each finding's rule ID, message, and location as the rule-specific context. Validate the finding against the component implementation before editing.
+
+### Phase 2b: Semantic Scan (Tier 1)
+
+```bash
+node scripts/scan-a11y-code.cjs <file1> [file2] ...
+```
+
+Use the emitted resolution path, evidence, and confidence to trace each finding. The scanner output is the source of rule-specific details; the reference only defines how to evaluate and act on those details.
+
+Neither scanner validates manifest contracts or all Editor React Component patterns. Complete Phase 3 even when both scanners return zero findings.
+
+### Deduplication and Triage
+
+Evaluate every finding before fixing it.
+
+**Deduplicate.** When both scanners flag the same location for the same issue, keep the finding with richer evidence. Prefer the semantic scanner when it resolved the component topology; prefer ESLint when the issue is outside the semantic scanner's scope.
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| `confirmed` | The violation is real | Fix it |
+| `false-positive` | The rule fires but the rendered behavior is correct | Discard it |
+| `not-relevant` | The rule does not apply to this architecture | Discard it |
+
+Use this order to evaluate a finding:
+
+1. Trace the component implementation and confirm that the flagged behavior reaches the rendered element.
+2. Check delegated semantics. Editor React Components route ARIA through the typed `a11y` prop and `convertA11yKeysToHtmlFormat(a11y)` (see [`ACCESSIBILITY.md`](ACCESSIBILITY.md)). If the attributes reach the correct element through a runtime path the scanner cannot see, discard the finding as a false positive.
+3. Check conditional interactivity. When `onClick` is spread conditionally with `role`, `tabIndex`, and `onKeyDown`, discard the finding as a false positive. If only `onClick` is conditional, confirm it.
+4. Apply the semantic checks in [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#tier-2-manual-review-checklist).
+5. When uncertain, continue tracing the implementation. Default to `confirmed` only after checking the available code and evidence.
+
+Only confirmed findings proceed to edits.
+
+### Phase 3: Editor React Component Semantic Review
+
+Perform a manual semantic review even when scanners return zero findings.
+
+- All ARIA attributes come through the typed `a11y?: A11y` prop, never individual `ariaLabel?: string`, `role?: string`, and similar props. See [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
+- `a11y` is forwarded to the root via `{...(a11y && convertA11yKeysToHtmlFormat(a11y))}`, or to an inner element via `elementProps.<name>.a11y` when requirements specify.
+- Icon-only interactive elements (icon/emoji/image/svg with no text node) have an accessible name from `constants.ts` or user-configurable `a11y`, never a hardcoded string literal.
+- Direction support is mandatory: props include `direction?: Direction`, the root applies `dir={direction}` and the unconditional `fallbackDirection` class, and CSS defines `.fallbackDirection:not([dir])`. See [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
+- Every `ReactNode` content prop is rendered inside an element with `dir="ltr"` so user-provided nested content does not inherit the component direction.
+- `<componentName>.extension.ts` overrides do not strip a11y-relevant manifest fields generated from the JSX.
+- Decorative-only output is hidden with `aria-hidden` when appropriate.
+- Heading/tag selection, when configurable, reaches the rendered semantic element.
+- Interactive-looking elements expose the required keyboard behavior and roles.
+
+Use the full Tier 2 checklist in [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#tier-2-manual-review-checklist).
+
+### Phase 4: Fix
+
+Apply fixes only to findings that survived triage:
+
+- `high`: fix immediately
+- `medium`: read the surrounding code, confirm, then fix
+- `low`: resolve the semantics from code and evidence; fix only when confirmed
+
+Confirmed safe/local fixes must be applied. Leave code unchanged only when the semantics remain ambiguous or the fix requires a risky, non-local behavior change. See [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#confidence-model).
+
+Fix principles:
+
+- Preserve intended visual and runtime behavior.
+- Fix the real semantic owner: component root, inner element via `elementProps`, or shared base.
+- Follow established Editor React Component patterns: route ARIA through `a11y`, use `constants.ts` for required labels, and never hardcode string literals.
+- Before adding `role`, `tabIndex`, or keyboard handlers to a non-interactive element, run the [pre-fix checks](A11Y-REVIEW-REFERENCE.md#pre-fix-checks-for-adding-button-semantics-to-a-non-interactive-element).
+
+### Phase 5: Verify
+
+If any `.tsx` / `.jsx` file was edited:
+
+1. Re-run both scanners on the modified files.
+2. Run `npx wix build && npx wix generate manifest` so the manifest reflects any JSX changes.
+3. Run the project's TypeScript check (`npx tsc --noEmit`), which is already part of the wix-app validation flow.
+
+Verification is mandatory after edits. Continue directly from fixes to verification, and do not consider the workflow complete while a required check remains unrun.
+
+## References
+
+- [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md) - triage, confidence, semantic resolution, Tier 2 checks, and pre-fix safeguards
+- [`ACCESSIBILITY.md`](ACCESSIBILITY.md) - ARIA conventions for Editor React Components

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

@@ -0,0 +1,172 @@
+# Animated Components (Play/Pause Control)
+
+Rules and patterns for components whose primary content is a **playable
+animation** — a Lottie/JSON animation, an animated GIF/SVG, a canvas/WebGL
+loop, or a video-like surface.
+
+Every such component MUST ship an on-stage **play/pause button**.
+
+---
+
+## When this applies
+
+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:
+
+- Any component with an `autoPlay` prop (gallery, slider, carousel, etc.)
+- Lottie / JSON vector animations
+- Animated GIFs or animated SVGs
+- Canvas / WebGL animation loops
+- Any video-like playing surface
+
+**Key rule:** If the component accepts an `autoPlay` prop — even if the
+underlying mechanism is a `setInterval` advancing an index rather than a media
+player — it MUST expose a play/pause button so visitors can stop the
+auto-advancing behavior. "Autoplay" is a behavior contract, not an
+implementation detail.
+
+---
+
+## What to add (checklist)
+
+1. **Props** — `autoPlay`, `loop`, `pauseButtonVisibility`
+2. **Playback state** — `isPlaying` + `handlePause` / `handleResume`
+3. **Play/pause button** — overlay `<button>` with inline SVG icon + CSS positioning and optional hover-only visibility
+4. **Modify `component.preview.tsx`** — suppress autoplay in editor design mode
+5. **Respect `prefers-reduced-motion`** — suppress autoplay when the OS requests reduced motion
+
+---
+
+## 1. Props
+
+Playback controls are **behavior** props (see [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md)):
+
+```typescript
+import type { A11y, Direction } from '@wix/editor-react-types';
+
+export interface MyAnimationProps {
+  id?: string;
+  className?: string;
+  direction?: Direction;
+  a11y?: A11y;
+
+  /** Start playing on load. Default `true`. */
+  autoPlay?: boolean;
+
+  /** Repeat when finished. Default `true`. */
+  loop?: boolean;
+
+  /** Show play/pause button. Default `'showOnHover'`. */
+  pauseButtonVisibility?: 'showAlways' | 'showOnHover';
+}
+```
+
+---
+
+## 2. Playback state
+
+Track play/pause state with `useState`. Initialize it from `autoPlay` and the OS reduced-motion preference — when the visitor has requested reduced motion, the animation starts paused:
+
+```tsx
+import { useReducedMotion } from '@wix/react-component-utils';
+
+// inside the component:
+const reducedMotion = useReducedMotion();
+
+const [isPlaying, setIsPlaying] = React.useState((autoPlay ?? true) && !reducedMotion);
+
+// when autoPlay prop changes, re-sync (but still respect reduced motion)
+React.useEffect(() => {
+  setIsPlaying((autoPlay ?? true) && !reducedMotion);
+}, [autoPlay]);
+
+// when reduced motion is enabled, suppress playback; never re-enable on its own
+// (visitor may have manually paused — don't restart against their will)
+React.useEffect(() => {
+  if (reducedMotion) {
+    setIsPlaying(false);
+  }
+}, [reducedMotion]);
+
+const handlePause = () => setIsPlaying(false);
+const handleResume = () => setIsPlaying(true);
+```
+
+**`reducedMotion`** is `true` when the hook reports that reduced motion is enabled. When active, the animation starts paused — the visitor can still press the play button to start it manually. It is a runtime browser signal, not a manifest/data prop; never expose it as a component prop or in the manifest.
+
+Pass `isPlaying` to the animation renderer and toggle between `handlePause` / `handleResume` on button click.
+
+---
+
+## 3. 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, stroke, and fill should feel native to the component's design.
+
+Position the button absolutely so it overlays the content without pushing other elements out of place:
+
+```css
+.animationContainer {
+  position: relative;
+  block-size: 100%;
+  inline-size: 100%;
+}
+
+.playButton {
+  position: absolute;
+  inset-inline-end: 5px;
+  inset-block-start: 5px;
+}
+```
+
+```css
+/* pauseButtonVisibility variants — structural CSS, not named-part rules */
+
+/* showOnHover (default) */
+.root[data-pause-button-visibility="showOnHover"] .playButton {
+  opacity: 0;
+  pointer-events: none;
+}
+
+.root[data-pause-button-visibility="showOnHover"]:hover .playButton {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* showAlways — no extra CSS needed; button is visible by default */
+```
+
+---
+
+## 4. Modify `component.preview.tsx` for autoplay suppression
+
+For animated components, modify the generated `component.preview.tsx` to suppress autoplay in editor design mode. See [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) for how the preview file works.
+
+### Target state of `component.preview.tsx`
+
+Replace the generated passthrough with the following. Replace `MyComponent` with the real component name.
+
+```tsx
+import React from 'react';
+import MyComponent from './component';
+import { useIsEditMode } from '@wix/react-component-utils';
+
+export default function MyComponentPreview(
+  props: React.ComponentProps<typeof MyComponent>,
+) {
+  const isEditMode = useIsEditMode();
+
+  return (
+    <MyComponent
+      {...props}
+      autoPlay={isEditMode ? false : props.autoPlay}
+      pauseButtonVisibility={isEditMode ? 'showAlways' : props.pauseButtonVisibility}
+    />
+  );
+}
+```
+
+In editor design mode (`isEditMode` is `true`) → `autoPlay` is forced to `false` and `pauseButtonVisibility` is forced to `'showAlways'` so the site owner can always see and interact with the button.  
+In preview mode (`isEditMode` is `false`) → both use the user's configured values.
+
+---

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

@@ -0,0 +1,29 @@
+# Branded / Themed Components
+
+Apply automatically — without being asked — whenever the user requests a
+**branded**, **themed**, or **brand-aware** component.
+
+---
+
+Import theme tokens from `@wix/react-component-schema/theme-variables.module.css`
+using CSS Modules `@value`, then consume with `var()`.
+
+```css
+@value wst-primary-background-color from "@wix/react-component-schema/theme-variables.module.css";
+@value wst-heading-3-font, wst-heading-3-color from "@wix/react-component-schema/theme-variables.module.css";
+@value wst-paragraph-1-font, wst-paragraph-1-color from "@wix/react-component-schema/theme-variables.module.css";
+
+.root    { background: var(wst-primary-background-color); }
+.heading { font: var(wst-heading-3-font); color: var(wst-heading-3-color); }
+.body    { font: var(wst-paragraph-1-font); color: var(wst-paragraph-1-color); }
+```
+
+**Colors:** `wst-primary-background-color`, `wst-secondary-background-color`, `wst-base-1-color`, `wst-base-2-color`, `wst-shade-1/2/3-color`, `wst-accent-1/2/3/4-color`, `wst-links-and-actions-color`
+
+**Headings:** `wst-heading-1..6-font` / `wst-heading-1..6-color`
+
+**Body:** `wst-paragraph-1..3-font` / `wst-paragraph-1..3-color`
+
+❌ Don't use `var(--wst-*)` directly — import the `@value` alias first.  
+❌ Don't use `@import` — CSS Modules doesn't process `@value` aliases from `@import`; `@value` is the only mechanism that resolves them at build time.  
+❌ Don't use `wst-base-1-color` for text — it typically resolves to white and is invisible on the default white background. Use `wst-heading-*-color` / `wst-paragraph-*-color` for text, or `wst-base-2-color` if you need a base contrast color.  

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

@@ -102,7 +102,7 @@ exists because the element is a named part.
 
 ### What Qualifies as a Part
 
-See [`PARTS.md`](PARTS.md) for the mandatory filter and full rules.
+See [`PARTS.md`](PARTS.md) for root election (Step 0), the mandatory filter, and full rules. The root gets no `elementProps` entry — its `className`, `a11y`, and `direction` arrive as top-level props.
 
 ### Derived values are not props