@wix/agent-skills 1.14.0 → 1.15.0

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

@@ -7,23 +7,17 @@ Rules and patterns for props structure, elementProps, data types, file structure
 ## Should This Use elementProps or CSS?
 
 ```
-Does this element need:
-- Configuration/data beyond styling
-- Direction override
-- State management
-- Event handlers
-
+Is this element a named part (carries a global class string)?
 │
 ├─ YES
-│   └─ ✅ Use elementProps
+│   └─ ✅ It gets an elementProps entry — spread it + merge its className.
+│         Add config fields inside the entry only as needed
+│         (data, direction, event handlers).
 │
-└─ NO → Is it purely visual/decorative (including conditionally displayed)?
-    │
-    ├─ YES (icons, separators, decorations, elements only hidden/shown via CSS)
-    │   └─ ❌ CSS class only (no elementProps)
-    │
-    └─ NO
-        └─ Re-evaluate: likely needs elementProps
+└─ NO → purely visual/decorative non-part
+        (icons, separators, decorations, layout wrappers,
+         elements only hidden/shown via CSS)
+    └─ ❌ CSS class only — no elementProps entry
 ```
 
 ---
@@ -58,23 +52,53 @@ interface ComponentProps {
 }
 ```
 
-### When to Use elementProps
+### Propagate `elementProps` to inner elements
+
+`elementProps` is a map keyed by the manifest's inner-element keys; each entry
+carries that element's `className` (the editor sets it — this is how design
+states reach the element) plus any data.
+
+**Every named inner element — every element that carries a global class
+string — gets an `elementProps` entry, and you spread that entry onto the
+element.** This is mandatory, even when the element needs no other config:
+without it the editor cannot style that element or drive its states.
 
-**Use `elementProps`** for parts that need:
+How `className` gets merged depends on what the element is:
+
+- **Raw HTML element** (`<button>`, `<li>`, `<div>`): merge
+  `elementProps?.<key>.className` inline, alongside the global string and module
+  class — there's no component to do it.
+- **Sub-component built with this skill** (`<Inner/>`): the spread alone is
+  enough. `className` rides along inside it, and the sub-component merges it onto
+  its own root (every skill component merges its incoming `className`). Don't
+  merge it again at the call site.
+
+```tsx
+interface PlanCardProps {
+  className?: string;
+  elementProps?: {
+    cta?: { className?: string; href?: string };
+  };
+}
 
-- Configuration/data beyond just styling
-- Direction override
-- State management
-- Event handlers
+// Raw HTML element — spread + merge className inline.
+// Note: the elementProps key is the short part name (`cta`), while the global
+// class is prefixed with the component name (`plan-card-cta`). Keep them as-is.
+<button {...elementProps?.cta} className={classNames('plan-card-cta', styles.cta, elementProps?.cta?.className)}>
+  {label}
+</button>
 
-**DO NOT use `elementProps`** for:
+// Sub-component built with this skill — spread is enough (it merges className itself):
+<PlanRow {...elementProps?.planRow} />
+```
 
-- Elements with only visual styling (use CSS classes)
-- Elements where conditional display is the only requirement (visibility controlled via CSS for per-breakpoint hiding, not React props)
-- Elements that would only have `className` — skip them entirely
-- Icons, decorations, separators
+**Non-parts** (module-class-only elements: icons, decorations, separators,
+layout wrappers — no global class) get no entry. Style them with CSS.
 
-**Minimal elementProps rule:** If an element would only have `className?: string` in elementProps, do NOT include it.
+**Inside each entry**, add only the config the element needs (data, direction,
+event handlers). Never add a bare `className?` as the *only* field to decide
+whether an element qualifies — `className` always flows through; the entry
+exists because the element is a named part.
 
 ### What Qualifies as a Part
 
@@ -178,8 +202,8 @@ editor) or imported local assets bundled with the component.
 
 ### Default values for `Image` props
 
-Image defaults belong in the component file's exported `defaultProps`
-constant (the one consumed by `withDefaults(Component, defaultProps)` in
+Image defaults belong in the `<componentName>.props.ts` file's exported
+`defaultProps` constant (consumed by `withDefaults(Component, defaultProps)` in
 `component.tsx`). Use a Wix-hosted image from the Free-from-Wix public
 media catalog and populate **only** `uri`, `url`, and `alt` — leave
 `width`, `height`, `focalPoint`, etc. unset so the editor fills them when
@@ -426,7 +450,7 @@ elementProps?: {
 // Style via CSS classes directly
 ```
 
-**Why:** If element only has `className` (even if it can be hidden/shown via CSS), skip elementProps entirely. Conditional display is controlled via CSS, not React props.
+**Why:** Don't declare a `className?:` field — `className` already flows through each named inner element's `elementProps` entry (see "Propagate `elementProps` to inner elements"). Conditional display is controlled via CSS, not React props.
 
 ### Using T[] array syntax
 
@@ -452,3 +476,4 @@ interface ComponentProps {
 ```
 
 See also: [Array Element Types: Always Objects with Named Keys](#array-element-types-always-objects-with-named-keys) — items must be objects with named keys.
+

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

@@ -128,14 +128,14 @@ resizeDirection: LAYOUT.RESIZE_DIRECTION.aspectRatio,
 
 ## 3. Wiring defaults into the manifest
 
-1. **Export `defaultProps` from `component.tsx`** so the extension file can import it.
+1. **Define and export `defaultProps` from `<componentName>.props.ts`** — this is the single source of truth used by both `component.tsx` and the extension file.
 2. **Import `componentUrl` from `'./component.tsx?url'`** (the wrapped component), not from `'./ComponentName.tsx?url'` (the raw component).
 3. **Wrap `editorElement` with `withEditorElementDefaults`** using the same `defaultProps`.
 
 ```ts
 import { withEditorElementDefaults } from '@wix/react-component-utils';
 import componentUrl from './component.tsx?url';
-import { defaultProps } from './component';
+import { defaultProps } from './<componentName>.props';
 
 // in the extension:
 editorElement: withEditorElementDefaults({

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.
+### Design states
 
-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.
-
-**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 */
@@ -574,3 +485,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,12 @@ 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
+- [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
 
 ## React 18 features are not supported
 
@@ -24,8 +24,9 @@ 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.
+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 +44,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 +69,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 +136,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 +151,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 +164,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.
+