@wix/agent-skills 1.14.0 → 1.15.1

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

@@ -16,10 +16,12 @@ There are two kinds of classes, determined by whether the element is a named par
 
 | Element type | className | Why |
 |---|---|---|
-| Named part | `classNames('heading', styles.heading)` | Global string → zeroConfig creates an editor element; module class → applies the component's own CSS |
+| Named part | `classNames('profile-card-heading', styles.heading)` | Global string → zeroConfig creates an editor element; module class → applies the component's own CSS |
 | Non-part (layout/structural) | `styles.contentWrapper` | Module class only — invisible to zeroConfig, no spurious editor element created |
 
-**Named parts** get both a global plain string and a module class. The global string (`'<component-name>'` for root, `'<part-name>'` for inner parts — kebab-case) is what zeroConfig scans. The module class is what carries the component's structural CSS for that element.
+**Named parts** get both a global plain string and a module class. The global string is what zeroConfig scans: use `'<component-name>'` for the root and **`'<component-name>-<part-name>'` for every inner part** (kebab-case) — always prefix inner parts with the component name. The module class is what carries the component's structural CSS for that element; it stays short (`styles.heading`) because module classes are hashed and scoped, so they never need the prefix.
+
+**Why prefix inner parts:** the global string is a literal class that ends up on the live page, and its design-state variants are derived from it (`<component-name>-<part>--<state>`, e.g. `profile-card-cta--hover`). Those state classes are applied at runtime as global literals, so they must be unique across every component that can share a page — a bare `cta--hover` would collide between two different components. Prefixing with the component name guarantees uniqueness.
 
 **Non-part elements** (layout wrappers, grouping containers, structural helpers) get only a module class. CSS module classes are mangled and invisible to zeroConfig.
 
@@ -34,18 +36,18 @@ import styles from './ProfileCard.module.css';
 // ✅ Root: global string + module class + consumer className
 <div className={classNames(className, 'profile-card', styles.root)} id={id}>
 
-  {/* ✅ Named part: global string + module class */}
-  <h2 className={classNames('heading', styles.heading)}>{heading}</h2>
+  {/* ✅ Named part: prefixed global string + short module class */}
+  <h2 className={classNames('profile-card-heading', styles.heading)}>{heading}</h2>
 
   {/* ✅ Non-part layout wrapper: module class only */}
   <div className={styles.contentWrapper}>
-    <span className={classNames('label', styles.label)}>{label}</span>
+    <span className={classNames('profile-card-label', styles.label)}>{label}</span>
   </div>
 </div>
 
 // ✅ Internal sub-components — same pattern on part slots
-<CardHeader className={classNames('header', styles.header)}>
-  <CardTitle className={classNames('title', styles.title)}>{title}</CardTitle>
+<CardHeader className={classNames('profile-card-header', styles.header)}>
+  <CardTitle className={classNames('profile-card-title', styles.title)}>{title}</CardTitle>
 </CardHeader>
 ```
 
@@ -64,6 +66,9 @@ on context — either way the editor cannot decide which rule to
 modify when a user changes a property. CSS nesting compiles to
 descendant selectors and has the same effect.
 
+A state modifier on the element's own class (`.title:hover`,
+`.title:global(.profile-card-title--featured)`) is allowed — see [`DESIGN-STATES.md`](DESIGN-STATES.md).
+
 ```css
 /* ✅ Do: Single-class selector — unambiguous mapping to an editor control */
 .profile-card {
@@ -417,102 +422,10 @@ refined default costs nothing.
 | Hierarchy | Interactive elements visually distinct from static via weight, fill, or elevation |
 | Touch targets | Interactive elements ≥ 44×44 px |
 
-### Don't author state styles (`:hover`, `:focus`, `:disabled`, `[data-state]`)
-
-State pseudo-classes and state attribute selectors are not allowed
-in component CSS. That includes `:hover`, `:focus`, `:focus-visible`,
-`:active`, `:disabled`, and attribute selectors like
-`[data-state='open']` or `[aria-selected='true']`.
-
-**Why:** the editor owns state styling. Hover, focus, disabled, and
-similar interaction states are exposed to the site owner as
-editable visual states — the platform writes those rules itself
-based on what the user configures. State styles authored in the
-component compete with the platform's rules and produce two
-sources of truth for the same state.
-
-```css
-/* ❌ Don't: hover/focus/disabled state — platform owns these */
-.button:hover {
-  background-color: #f0f0f0;
-}
-.button:focus {
-  outline: 2px solid blue;
-}
-.button:disabled {
-  opacity: 0.5;
-}
-
-/* ❌ Don't: state attribute selectors — same problem */
-.panel[data-state='open'] {
-  background-color: #fafafa;
-}
-
-/* ✅ Do: Style the resting state only — platform layers state styling on top */
-.button {
-  background-color: #ffffff;
-  color: #111;
-}
-```
-
-### Express selection / mode variants with JS-toggled modifier classes
-
-The previous rule banned **interaction states** (`:hover`, `:focus`,
-`:focus-visible`, `:active`, `:disabled`, `[data-state]`,
-`[aria-selected]`) — those are user-controlled and platform-owned.
-**Selection / mode variants** (`selected`, `active`, `current`,
-`open`, `expanded`) are different: they are part of the component's
-own data model and the component owns their styling.
-
-Express each variant as a **JS-toggled modifier class**, applied
-alongside the base class via `classNames`. Each class — base and
-modifier — is its own **single-class** CSS rule. The decision of
-which class applies is made in JSX from props/state, not by a CSS
-selector.
+### Design states
 
-**Why:** the modifier class is decided in JSX, not in CSS. zeroConfig
-still sees one selector per rule (both classes are single-class
-rules), so the editor's mapping stays unambiguous. `PARTS.md`
-excludes "state or variant" from the named-parts taxonomy — the
-modifier is CSS-only, not a part.
-
-```tsx
-/* ✅ Do: JS-toggled modifier class, applied alongside the base */
-<button
-  className={classNames(
-    styles.toggleSegment,
-    isSelected && styles.toggleSegmentSelected,
-  )}
-/>
-```
-
-```css
-/* ✅ Do: each class is its own single-class rule */
-.toggleSegment {
-  background: transparent;
-  color: #475569;
-  font-weight: 500;
-}
-
-.toggleSegmentSelected {
-  background: #ffffff;
-  color: #0f172a;
-  font-weight: 600;
-  box-shadow: 0 1px 2px rgba(15, 23, 42, 0.06), 0 1px 3px rgba(15, 23, 42, 0.1);
-}
-
-/* ❌ Don't: compound selector — banned by the single-class-selector rule */
-.toggleSegment.selected {
-}
-
-/* ❌ Don't: attribute selector keyed on ARIA — banned by the no-state-CSS rule */
-.toggleSegment[aria-selected='true'] {
-}
-
-/* ❌ Don't: pseudo-class — that's an interaction state, platform-owned */
-.toggleSegment:checked {
-}
-```
+Style interaction and selection states (`hover`, `focus`, `disabled`,
+`selected`, …) per [`DESIGN-STATES.md`](DESIGN-STATES.md).
 
 ### Don't add transitions or animations unless functionally required
 
@@ -528,9 +441,7 @@ shorthand (`transition: 0.2s ease`).
 configures the component — colors, font, padding, border width,
 even layout properties on parent classes. Animating those mutations
 makes the editor visibly laggy: values meant to update instantly
-slide instead. State transitions like hover and focus are owned by
-the platform (see the rule above), so the component shouldn't
-author them either.
+slide instead.
 
 ```css
 /* ❌ Don't: decorative transition with no functional reason */
@@ -554,6 +465,12 @@ author them either.
 }
 ```
 
+**Media playback is functional, not decorative.** When the component's content
+*is* a playing animation (Lottie/JSON, animated GIF/SVG, canvas/WebGL, video),
+letting it play is allowed — the motion is the content. Such components get a
+play/pause control positioned in CSS. See
+[`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md).
+
 ### Set `pointer-events: auto` on the root and every interactive element
 
 The root selector and every nested class that the user can click,
@@ -574,3 +491,4 @@ published site, where the wrapper is gone.
   pointer-events: auto;
 }
 ```
+

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

@@ -0,0 +1,127 @@
+# Design States
+
+A design state styles an element differently per interaction (`hover`,
+`focus`, `disabled`, `invalid`) or per a selectable value in its data
+(`selected`, `active`, `open`, …). Author states in the component's `.tsx`
+and `.module.css`.
+
+## 1. Which states each element supports
+
+| Element | Author these states |
+|---|---|
+| Interactive — `button`/`a`/`input`/`select`/`textarea`/`summary`, an interactive `role` (`button`/`link`/`tab`/`switch`/`checkbox`/`radio`/`menuitem`/`option`), or an interactive handler (`onClick`/`onMouseEnter`/`onFocus`/…) | `hover`, `focus` |
+| Disableable — `button`/`input`/`select`/`textarea`/`fieldset` or a disableable role | `disabled` (+ `invalid` for `input`/`select`/`textarea`) |
+| Has a selectable/variant value in its data — `selected`/`active`/`current`/`open`/`expanded`/`checked`/`featured` | that custom state |
+| None of the above | no states — resting style only |
+
+A custom state may also be driven by a root-level boolean prop (e.g.
+`isFeatured`) instead of by markup or item data — see §5.
+
+## 2. Name the state class
+
+Flat: the element's own global class + `--<state>`. Because inner-part
+global classes are prefixed with the component name (see
+[`CSS-GUIDELINES.md`](CSS-GUIDELINES.md)), the state class is prefixed too —
+e.g. `pricing-card-cta--hover`, `pricing-card-plan-row--selected`. Never bare
+(`cta--hover` would collide with other components on the page) and never
+nested (`card__row--selected`).
+
+## 3. CSS
+
+Put the resting value in the bare class; put only the state override in the
+state selector.
+
+- **Native** — pair the pseudo-class with the `:global` modifier.
+- **Custom** — the `:global` modifier alone.
+
+The bare selector is the short **module** class (`.cta`); the `:global(...)`
+state class is the **prefixed** global one.
+
+```css
+.cta {
+  background: #6366f1;
+} /* resting */
+.cta:global(.pricing-card-cta--hover),
+.cta:hover {
+  background: #4f46e5;
+}
+.cta:global(.pricing-card-cta--disabled) {
+  opacity: 0.5;
+}
+.plan-row:global(.pricing-card-plan-row--selected) {
+  border-color: #6366f1;
+}
+```
+
+## 4. React
+
+- **Native** — render the correct interactive element (`<button>`, an
+  interactive `role`, or a handler). Nothing else needed.
+- **Custom** — toggle the global state class from the element's data.
+- **Inner elements** — every named inner element gets an `elementProps` entry;
+  spread it so editor-driven states reach it. On a raw HTML element also merge
+  `elementProps?.<key>.className` inline; on a skill-built sub-component the
+  spread alone suffices (it merges `className` itself). The `elementProps` key
+  stays the **short** part name (`cta`) even though the element's global class
+  is prefixed (`pricing-card-cta`) — don't rename the key to match the class.
+  See [`COMPONENT-API.md`](COMPONENT-API.md).
+
+```tsx
+<button
+  type="button"
+  {...elementProps?.cta}
+  className={classNames('pricing-card-cta', styles.cta, elementProps?.cta?.className)}
+>
+  {label}
+</button>
+
+<li className={classNames('pricing-card-plan-row', styles.planRow, row.selected && 'pricing-card-plan-row--selected')}>
+  {row.label}
+</li>
+```
+
+## 5. Prop-triggered states (root only)
+
+A **prop-triggered** state is a custom state switched by a single boolean
+**prop**, rather than by interactive markup (native) or a per-item data flag
+(class-triggered). Use it only when one component-level boolean should flip the
+whole component's appearance — e.g. `isLoading`, `isFeatured`.
+
+Mark the prop with the `ElementState<boolean>` type from
+`@wix/react-component-utils`. It is an identity alias — the prop still behaves
+as a plain `boolean` at runtime and stays a normal boolean in the component's
+data — but the manifest generator detects the marker and emits a custom state
+on the **root element**.
+
+```tsx
+import type { ElementState } from '@wix/react-component-utils';
+
+export type PricingCardProps = {
+  // …other props…
+  isFeatured?: ElementState<boolean>;
+};
+```
+
+Rules:
+
+- **Boolean only, root only.** A prop trigger always attaches to the component
+  root — never to an inner element. Inner-element states must be native or
+  class-triggered (§1–§4).
+- The state name is the prop name in **kebab-case** (`isFeatured` →
+  `is-featured`; no `is`/`has` stripping). The manifest records
+  `props: { isFeatured: true }` as the trigger.
+- To give the state styling, pair the root's **module** class with a prefixed
+  `:global(.<component-name>--<state>)` rule. With a matching class the manifest
+  entry carries that `className`; with none it is props-only (the editor still
+  toggles the prop, but nothing restyles).
+
+```css
+.pricingCard:global(.pricing-card--is-featured) {
+  border-color: #f5a623;
+}
+```
+
+Prefer a native state (interactive markup) or a class trigger (per-item data
+such as `row.selected`) whenever one fits — those are the common cases and work
+at any depth. Reach for a prop trigger only for a root-level boolean switch.
+

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

@@ -9,7 +9,7 @@ An element deserves its own named part if a site owner would plausibly need to i
 
 ## Mandatory filter — apply to every candidate element
 
-- ❌ **State or variant** (`active`, `selected`, `current`, `disabled`, `open`, `checked`) — not a part. Implement as a BEM modifier class toggled in JSX (e.g. `image-carousel__slide--active`) and a single-class CSS rule. The modifier class is CSS-only; it is not a named part.
+- ❌ **State or variant** (`active`, `selected`, `current`, `disabled`, `open`, `checked`) — not a part, it's a **design state** of a part. Implement it per [`DESIGN-STATES.md`](DESIGN-STATES.md): native states from interactive markup; custom states as a flat global modifier on the element's own (component-name-prefixed) class (e.g. `carousel-slide--active`, toggled in JSX) plus a `:global(.carousel-slide--active)` CSS rule. The modifier is a state, not a named part.
 - ❌ **Hidden/shown state of an existing part** — the hidden and shown states of a part are not separate parts. The element itself should be a named part (so the editor can control its visibility per breakpoint); creating an additional part to represent its hidden or shown variant is wrong.
 - ❌ **Pure grouping wrapper** — not a part. A `<div>` whose only role is to hold already-named siblings has no independent editor surface; let layout live in the parent's CSS.
 - ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs.
@@ -23,3 +23,4 @@ Before finalising, verify each proposed part against its parent:
 > Would the editor controls generated for this part be a strict subset of its parent's controls?
 
 If yes — the part adds no independent editor surface and should be removed. This catches rationalisation after-the-fact ("the parent *could* expose this CSS property too, but so could the child separately"). When in doubt, fewer parts is usully better.
+

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

@@ -4,12 +4,14 @@ This guide defines rules and guidance on **how to implement** production-quality
 
 **Topic reference files:**
 - [`PARTS.md`](PARTS.md) — What qualifies as a named part (mandatory filter)
+- [`DESIGN-STATES.md`](DESIGN-STATES.md) — Which design states a part supports, and how to author them
 - [`ACCESSIBILITY.md`](ACCESSIBILITY.md) — ARIA/a11y rules and patterns
 - [`DIRECTIONALITY.md`](DIRECTIONALITY.md) — RTL/LTR rules and patterns
 - [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`COMPONENT-API.md`](COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
-- [`SSR.md`](SSR.md) — Server-side rendering rules (mandatory)
-- [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — CSS rules, common mistakes
+- [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
+- [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) — `component.preview.tsx` patterns and `useIsEditMode()` usage
+- [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
 
 ## React 18 features are not supported
 
@@ -23,9 +25,10 @@ Understand the component and infer its behavior. Extract what is provided; use r
 
 1. **Identity** — Component name.
 2. **Structure** — Identify named parts by applying the mandatory filter in [`PARTS.md`](PARTS.md) to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
-3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally.
+3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally. If the component's primary content is a **playable animation** (Lottie/JSON, animated GIF/SVG, canvas/WebGL loop, video-like surface), it gets a play/pause control — follow [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md).
+4. **States** — For every part, decide which design states it supports (native: `hover`/`focus`/`disabled`/`invalid`; custom: `selected`/`active`/`open`/… ) by applying the heuristic in [`DESIGN-STATES.md`](DESIGN-STATES.md), and record them in the plan. These become the editor's per-element state styling controls.
 
-**Understanding → implementation (checklist):** For every part, decide `elementProps` vs CSS-only; build the props interface (data + behavior); wire interaction in React (`useState`, `useEffect`, refs, native event handlers); generate TS + CSS. Infer reasonable defaults where anything is unspecified.
+**Understanding → implementation (checklist):** For every part, decide `elementProps` vs CSS-only and which design states it supports ([`DESIGN-STATES.md`](DESIGN-STATES.md)); build the props interface (data + behavior); wire interaction in React (`useState`, `useEffect`, refs, native event handlers); give every named inner element an `elementProps` entry and spread it + merge its `className` ([`COMPONENT-API.md`](COMPONENT-API.md)); generate TS + CSS. Infer reasonable defaults where anything is unspecified.
 
 # Part 1: Standards & Conventions
 
@@ -43,10 +46,6 @@ Direction support is mandatory — see [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
 
 See [`ACCESSIBILITY.md`](ACCESSIBILITY.md) for full rules and patterns.
 
-### SSR Safety
-
-Components are server-rendered, then hydrated — they MUST render correctly, completely, and identically on the server. See [`SSR.md`](SSR.md) for full rules and patterns.
-
 ### TypeScript
 
 - All components must be fully typed
@@ -72,11 +71,11 @@ All components MUST follow these patterns:
 
 **1. SSR-Safe Implementation**
 
-- NO browser APIs at module scope or during render (window, document, navigator, etc.) — guard inside `useEffect`
-- First render must be complete and deterministic; effects are client-only enhancement
-- Internal ids via `useStableId`; NO `useLayoutEffect`
+- NO browser APIs at module scope (window, document, navigator, etc.)
+- Guard browser APIs with typeof checks or useEffect
+- All browser-dependent logic must run client-side only
 
-See [`SSR.md`](SSR.md) for full rules and code examples.
+See [`REACT-PATTERNS.md`](REACT-PATTERNS.md) §1.1 for code examples.
 
 **2. Clean Code**
 
@@ -139,6 +138,8 @@ For each part of the component, decide:
 - ✅ Has state or behavior
 - ✅ Needs event handlers
 
+For the same part, also decide which **design states** it supports (native + custom) per [`DESIGN-STATES.md`](DESIGN-STATES.md).
+
 See [`COMPONENT-API.md`](COMPONENT-API.md) and [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) for the decision trees.
 
 ### Step 2: Build Props Interface
@@ -152,7 +153,7 @@ Combine:
 
 ### Step 3: Implement
 
-Follow Part 2 templates with mandatory patterns applied.
+Follow Part 2 templates with mandatory patterns applied. For each part's supported design states, author the interactive markup / class toggles and the state CSS per [`DESIGN-STATES.md`](DESIGN-STATES.md).
 
 # Part 2: CSS Rules
 
@@ -165,8 +166,9 @@ See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.
 
 ## 3.1 Implementation Checklist
 
-**Phase 1: Analysis** — Parse information, map component structure (see Part 0)
+**Phase 1: Analysis** — Parse information, map component structure and supported design states (see Part 0)
+
+**Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; toggle custom-state classes from data ([`DESIGN-STATES.md`](DESIGN-STATES.md))
 
-**Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; verify SSR safety against [`SSR.md`](SSR.md)
+**Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md))
 
-**Phase 3: Styles** — Apply Part 2 SCSS rules

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

@@ -6,7 +6,23 @@ Code patterns and common mistakes for Editor React components.
 
 ## 1.1 SSR-Safe Implementation
 
-Components are server-rendered then hydrated. See [`SSR.md`](SSR.md) for the full rules and code examples (browser globals, complete first render, deterministic output, `useStableId`, no `useLayoutEffect`).
+Avoid browser-only APIs at module scope or during render; use them inside `useEffect` with `typeof window !== 'undefined'`.
+
+**❌ Wrong:**
+
+```typescript
+const userAgent = window.navigator.userAgent;
+```
+
+**✅ Correct:**
+
+```typescript
+useEffect(() => {
+  if (typeof window !== "undefined") {
+    const userAgent = window.navigator.userAgent;
+  }
+}, []);
+```
 
 ## 1.2 Element Visibility (Platform-Managed)
 
@@ -23,71 +39,26 @@ Authoritative SCSS rules: `REACT-GUIDELINES.md` Part 2. For RTL/logical CSS patt
 ```scss
 // ❌ NEVER include:
 
-// State CSS
-&:hover { ... }              // ❌
-&:focus { ... }              // ❌
-&:disabled { ... }           // ❌
-&[data-state='open'] { ... } // ❌
-
 // Transitions/Animations
 transition: all 0.3s;        // ❌
 animation: fadeIn 0.5s;      // ❌
 ```
 
+> Design states (`hover`, `focus`, `selected`, …) are authored per
+> [`DESIGN-STATES.md`](DESIGN-STATES.md).
+
 ---
 
 # Part 3: Common Mistakes
 
-## 3.1 Adding interaction-state CSS to parts
-
-The resting visual (background, color, border-radius, padding, font)
-belongs in the component's CSS — see `CSS-GUIDELINES.md` §"Keep all
-styling in CSS". What does NOT belong is **interaction-state CSS**
-(`:hover`, `:focus`, `:focus-visible`, `:active`, `:disabled`,
-`[data-state]`, `[aria-selected]`) — the platform owns those.
-Selection / mode variants (`selected`, `active`, `open`) are
-different — they go through a JS-toggled modifier class; see
-`CSS-GUIDELINES.md` §"Express selection / mode variants".
+## 3.1 Custom-state classes
 
-**❌ Wrong — pseudo-class rules must be removed:**
-
-```scss
-.button {
-  background-color: #ffffff;
-  color: #0f172a;
-  border-radius: 8px;
-  padding-block: 8px;
-  padding-inline: 16px;
-}
-
-.button:hover { /* ❌ Interaction state — platform owns this */
-  background-color: #f0f0f0;
-}
-
-.button:disabled { /* ❌ Interaction state — platform owns this */
-  opacity: 0.5;
-}
-```
-
-**✅ Correct — keep the resting visual; drop the pseudo-class rules:**
-
-```scss
-.button {
-  display: flex;
-  align-items: center;
-  background-color: #ffffff;
-  color: #0f172a;
-  border-radius: 8px;
-  padding-block: 8px;
-  padding-inline: 16px;
-  box-sizing: border-box;
-}
-```
+For a custom design state, toggle the element's **global** state class from
+its data in JSX (e.g. `isSelected && 'pricing-card-row--selected'`, using the
+component-name-prefixed class) — don't express it as a module-scoped class. State styling lives in [`DESIGN-STATES.md`](DESIGN-STATES.md).
 
 ## 3.2 Browser APIs at module scope
 
-See [`SSR.md`](SSR.md) for the full SSR rules.
-
 **❌ Wrong:**
 
 ```typescript
@@ -121,3 +92,4 @@ For lists, breadcrumbs, tabs, menus, and similar collection-style UI, render the
 ```
 
 Handle separators with CSS pseudo-elements or inside each item.
+

package/skills/wix-app/references/stores/CATEGORIES.md

@@ -0,0 +1,22 @@
+# Stores — Collections (V1) ↔ Categories (V3)
+
+```typescript
+// V1 write ops (createCollection, updateCollection, addProductsToCollection, …)
+// live on the `products` namespace, NOT `collections`. The `collections` namespace is read-only.
+import { products } from '@wix/stores';
+import { categories } from '@wix/categories';
+
+if (v === 'V3_CATALOG') {
+  // V3 createCategory(category, options). treeReference is REQUIRED and goes in `options`.
+  // For Wix Stores categories: appNamespace MUST be the literal "@wix/stores", treeKey is null.
+  const category = await categories.createCategory(
+    { name: 'Sale' },
+    { treeReference: { appNamespace: '@wix/stores', treeKey: null } },
+  );
+  return category;
+}
+const { collection } = await products.createCollection({ name: 'Sale' });  // V1 returns { collection }
+return collection;
+```
+
+V3 categories are tree-structured. Reference them on a product via `directCategories[]`, not `collectionIds[]`. **All Stores category API calls must pass `treeReference: { appNamespace: '@wix/stores', treeKey: null }` in `options`** — applies to `createCategory`, `updateCategory`, `queryCategories`, etc.

package/skills/wix-app/references/stores/GET_PRODUCT.md

@@ -0,0 +1,99 @@
+# Stores — Get Product
+
+## Get a single product
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);  // returns Product directly
+  return product;
+}
+const { product } = await products.getProduct(id);  // V1 wraps in { product }
+return product;
+```
+
+---
+
+## Read product options and choices (V1 vs V3)
+
+V1 and V3 differ in **both where choices live and what the choice fields are named**. Getting this wrong causes `TS2339` at validate time.
+
+| | V1 | V3 |
+|---|---|---|
+| Options array on product | `product.productOptions` | `product.options` |
+| Option name | `option.name` | `option.name` |
+| Option type | `option.optionType` (`"color"` / `"drop_down"`) | `option.optionRenderType` (`"SWATCH_CHOICES"` / `"TEXT_CHOICES"`) |
+| **Choices array** | `option.choices` ← **directly on the option** | `option.choicesSettings?.choices` ← **nested** |
+| Choice display value | `choice.value` | `choice.name` |
+| Choice color | `choice.value` (hex string) | `choice.colorCode` |
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  for (const option of product.options ?? []) {
+    const choices = option.choicesSettings?.choices ?? [];  // ✅ nested — NOT option.choices / option.optionValues (TS2339)
+    for (const choice of choices) {
+      render(option.name, choice.name, choice.colorCode);   // name = label; colorCode = hex for SWATCH_CHOICES
+    }
+  }
+} else {
+  const res = await products.getProduct(id);
+  const product = res.product!;  // product is optional in the raw type; ! matches SDK's strict-mode guarantee
+  for (const option of product.productOptions ?? []) {
+    for (const choice of option.choices ?? []) {           // ✅ direct in V1
+      render(option.name, choice.value);                   // value = label or hex string
+    }
+  }
+}
+```
+
+**In a site plugin on a product page**: get `productId` from `widget.getProp('product-id')`, then call the appropriate version's `getProduct` — same pattern as above.
+
+---
+
+## Modifiers (V1 `manageVariants=false` options)
+
+In V3, options that **don't** create variants (V1 `manageVariants=false`) live on `product.modifiers`, not `product.options`. They use the identical `choicesSettings.choices` pattern. Reading only `product.options` silently misses these.
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  // variant-creating options
+  for (const option of product.options ?? []) {
+    for (const choice of option.choicesSettings?.choices ?? []) {
+      render(option.name, choice.name, choice.colorCode);
+    }
+  }
+  // display-only / free-text customizations (formerly manageVariants=false)
+  for (const modifier of product.modifiers ?? []) {
+    for (const choice of modifier.choicesSettings?.choices ?? []) {
+      render(modifier.name, choice.name, choice.colorCode);
+    }
+  }
+}
+```
+
+---
+
+## Variant choices (V1 object map → V3 array)
+
+V1 `variant.choices` was a plain object map `{ "Size": "Small" }`. V3 restructures it as an array — accessing it with a key returns `undefined` silently.
+
+```typescript
+if (v === 'V3_CATALOG') {
+  const product = await productsV3.getProduct(id);
+  // variants are NOT returned by queryProducts — use getProduct or Read-Only Variants API
+  for (const variant of product.variantsInfo?.variants ?? []) {
+    for (const c of variant.choices ?? []) {
+      render(c.optionChoiceNames?.optionName, c.optionChoiceNames?.choiceName);
+    }
+    // ❌ variant.choices['Size'] — always undefined in V3 (object map is gone)
+  }
+} else {
+  const res = await products.getProduct(id);
+  const product = res.product!;  // product is optional in the raw type; ! matches SDK's strict-mode guarantee
+  for (const variant of product.variants ?? []) {
+    // V1: choices is { [optionName]: value }
+    render(Object.entries(variant.choices ?? {}).map(([k, v]) => `${k}:${v}`).join(', '));
+  }
+}
+```