@wix/agent-skills 1.35.1 → 1.36.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.35.1",
+  "version": "1.36.1",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {
@@ -15,8 +15,13 @@
     "version": "node .github/scripts/sync-plugin-versions.mjs && git add .claude-plugin/plugin.json .codex-plugin/plugin.json .cursor-plugin/plugin.json plugin.json gemini-extension.json antigravity/wix/plugin.json skills/wix-headless-kit/install/pins.json"
   },
   "files": [
-    "skills/**",
-    "!skills/wix-headless-cold-start/**",
+    "skills/wix-app/**",
+    "skills/wix-design-system/**",
+    "skills/wix-docs/**",
+    "skills/wix-headless-kit/**",
+    "skills/wix-headless-templates/**",
+    "skills/wix-manage/**",
+    "skills/wix-readme/**",
     "README.md",
     "LICENSE"
   ],

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

@@ -8,7 +8,7 @@ Applies to all generated code across every Wix CLI app extension type. Each per-
 - Prefer type-narrowing and exhaustive logic over assertions; avoid non-null assertions (`!`) and unsafe casts (`as any`).
 - Treat optional values, refs, and array indexing results as possibly undefined and handle them explicitly.
 - Use exhaustive checks for unions (e.g., `switch` with a `never` check) and return total values (no implicit `undefined`).
-- Do NOT use `// @ts-ignore` or `// @ts-expect-error`; fix the types or add guards instead.
+- Do NOT use `// @ts-ignore` or `// @ts-expect-error`; fix the types or add guards instead. The one exception is a `// @ts-ignore` directly above an import of a context provider's hook by its `moduleSpecifier`: TypeScript cannot resolve that specifier, because the site's import map supplies it only at runtime.
 
 ## Core Principles
 

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

@@ -21,18 +21,17 @@ Supplementary files are allowed; keep scaffold roles intact.
 
 ## Required Reading (blocking)
 
-Before writing code, open and read in full every reference in the matching
-row. An unopened one is a failed run. Open paths directly; never skim or
-grep instead.
+Before writing code, read every reference in the matched row in full.
+Unopened references fail the run—open paths directly; no skim or grep.
 
 | Scope | Required references |
 | --- | --- |
-| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md), [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
+| Creating a component | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`VISUAL-QUALITY.md`](editor-react-component/VISUAL-QUALITY.md), [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md), [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md), [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
 | Editing React or JSX | [`REACT-GUIDELINES.md`](editor-react-component/REACT-GUIDELINES.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md) |
 | Changing public contract, semantic root, or named parts | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PARTS.md`](editor-react-component/PARTS.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md) |
 | Changing public data props or elected root global class | [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
 | Item array where only one body is visible | [`COMPONENT-CONTRACT.md`](editor-react-component/COMPONENT-CONTRACT.md), [`PROPS-VS-CSS.md`](editor-react-component/PROPS-VS-CSS.md), [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md), [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
-| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md) |
+| Creating or changing CSS | [`CSS-GUIDELINES.md`](editor-react-component/CSS-GUIDELINES.md), [`VISUAL-QUALITY.md`](editor-react-component/VISUAL-QUALITY.md) |
 | Creating or changing layout/content | [`OVERFLOW.md`](editor-react-component/OVERFLOW.md) |
 | Root direction contract, direction-sensitive behavior, or `ReactNode` slot | [`DIRECTIONALITY.md`](editor-react-component/DIRECTIONALITY.md) |
 | Sizing, installation, or manifest overrides | [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md) |
@@ -47,14 +46,13 @@ grep instead.
    ```
 
    Never rerun the scaffold for an existing component.
-   Write a meaningful `description` in 1-2 plain sentences (max 300 chars): what
-   the user sees, when to use it, and capabilities that affect that choice.
-   Don't repeat the name or add implementation details.
+   Write a meaningful `description` (max 300 chars, 1-2 sentences): what users see,
+   when to use it, and capability tradeoffs—no name repeat or implementation detail.
 
 2. **Run the dependency preflight.**
 
    ```bash
-   deps=(@wix/react-component-schema @wix/react-component-utils @wix/editor-react-types)
+   deps=(@wix/react-component-schema @wix/react-component-utils @wix/editor-react-types clsx deepmerge-ts)
    dev=(@babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y jsdom axe-core)
 
    node - "${deps[@]}" "${dev[@]}" <<'JS' || {
@@ -63,7 +61,7 @@ grep instead.
      .map(p => p.replace(/@<7$/, ''))
      .filter(p => !require.resolve.paths(p)?.some(d => fs.existsSync(path.join(d, p, 'package.json'))));
    if (missing.length) {
-     console.error(`Missing dependencies: ${missing.join(', ')}`);
+     console.error(`Missing: ${missing.join(', ')}`);
      process.exit(1);
    }
    JS
@@ -74,27 +72,26 @@ grep instead.
    }
    ```
 
-3. **Plan.** Identify props, root, parts, and states; open all required references first.
-   Use them and the scaffold before inspecting package declarations; inspect
-   only for undocumented APIs or fields, or typecheck failures. Declarations
-   govern API shapes; retain editor rules.
+3. **Plan.** Identify props, root, parts, and states; open required references first.
+   Use them and the scaffold before package declarations—only for undocumented APIs
+   or typecheck failures. Declarations govern API shapes; keep editor rules.
 
 4. **Implement.** Keep props, logic, and styles in their scaffolded editable
    files. Format edited source files with the app's formatter. Never edit or format `*.generated.ts`.
 
-5. **Run the accessibility review (mandatory).** Once the JSX is complete, run from the
-   same folder (`<SKILL_ROOT>` is the directory containing the active `SKILL.md`):
+5. **Run the a11y review (mandatory).** After JSX, run from the
+   same folder (`<SKILL_ROOT>` contains the active `SKILL.md`):
 
    ```bash
    node <SKILL_ROOT>/scripts/scan-a11y-review.cjs src/extensions/site/components/<component-name>
    ```
 
-   Follow [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md); fix and
+   Follow [`ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md); fix and
    rerun at most twice, then report remaining findings.
 
 6. **Configure the editor extension.** For creation or a requested sizing,
    installation, or manifest change, apply
-   [`editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md)
+   [`EDITOR-EXTENSION-CONFIGURATION.md`](editor-react-component/EDITOR-EXTENSION-CONFIGURATION.md)
    to the extension; otherwise leave it unchanged. Synchronize preview
    `requiredDataFields` and `rootClassName`.
 
@@ -105,15 +102,15 @@ grep instead.
    npx wix build && npx wix generate manifest
    ```
 
-   Run `npx tsc --noEmit`, relevant tests/lint, and the accessibility review.
+   Run `npx tsc --noEmit`, relevant tests/lint, and the a11y review.
    If later edits affect a check, rerun that check. Inspect the manifest when generated; never hand-repair it.
    Diagnose failures with
-   [`editor-react-component/MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
+   [`MANIFEST-ERRORS.md`](editor-react-component/MANIFEST-ERRORS.md).
 
-   For creation/layout changes, complete the routed overflow resize review.
+   For creation/layout changes, run the overflow resize review.
 
-8. **Report.** Summarize files, checks, blockers, unrun checks.
-   List required references as read/unread; read any unread one and fix first.
+8. **Report.** Summarize files, checks, blockers, and skipped checks.
+   List references read/unread; fix unread before closing.
 
 ## Reference Policy
 
@@ -133,10 +130,11 @@ trigger. Preserve unrelated behavior. References are leaves.
 | Animation, video, carousel, or other playable/looped/autoplaying content | [`ANIMATED-COMPONENTS.md`](editor-react-component/ANIMATED-COMPONENTS.md), [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) |
 | Site/runtime/editor context hooks needed | [`SITE-CONTEXT-HOOKS.md`](editor-react-component/SITE-CONTEXT-HOOKS.md) (+ [`COMPONENT-PREVIEW.md`](editor-react-component/COMPONENT-PREVIEW.md) when design-mode behavior differs) |
 | Branded, themed, or brand-aware component requested | [`BRANDED-COMPONENTS.md`](editor-react-component/BRANDED-COMPONENTS.md) |
+| Owner-replaceable icon/SVG (not fixed UI glyphs) | [`VECTOR-ART.md`](editor-react-component/VECTOR-ART.md) |
 
 ## Non-Negotiables
 
-- React 18 only; do not assume React 19 runtime features.
+- React 18 only; no React 19 runtime features.
 - Include typed `id`, `className`, `direction`, and `a11y` support.
 - Elected root: `dir={direction}`, fallback-direction class, logical CSS for
   direction-sensitive layout.
@@ -148,13 +146,13 @@ trigger. Preserve unrelated behavior. References are leaves.
 - Named parts: global class, module class, and `elementProps` (root uses
   top-level props).
 - Every visible text: a text prop plus a named part; no JSX text literals.
-- Native design states: interactive elements only, never a non-interactive root
-  or part; pair selectors with injected modifiers; toggle custom state classes
-  from data, each with a matching `:global()` rule.
+- Native design states: interactive elements only; pair selectors with injected
+  modifiers. Custom states need a class toggle from logic or data, or a root prop
+  trigger; styled states need matching `:global()` rules.
 - Open/close/reveal: props-only root
   `isOpen: ElementState<boolean>` synced to state; module classes, no `--open` class.
-- Single-visible-body arrays: `name` per item, `ActiveItemIndex<'prop'>`, render
-  all bodies, hide inactive accessibly.
+- Single-visible-body arrays: `ActiveItemIndex<'prop'>`, render all bodies,
+  hide inactive accessibly; item `name` only when rendered.
 - No arrays inside array items; keep group fields flat (no object props).
 - Autoplay/loop: play/pause control, honor reduced motion, suppress autoplay in
   editor design mode.

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

@@ -197,7 +197,7 @@ Wire the named part completely:
 <button
   type="button"
   {...elementProps?.myAnimationPlayButton}
-  className={classNames(
+  className={clsx(
     'my-animation-play-button',
     styles.playButton,
     elementProps?.myAnimationPlayButton?.className,

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

@@ -43,12 +43,12 @@ Rules:
   when requested. Keep implementation handlers internal.
 - Use `Array<T>`, not `T[]`, for exported arrays.
 - Use a native link for a CTA with a real `href`, or a native button for an
-  action. Never fall back to `href="#"`: it has no meaningful destination.
+  action. Never use `href="#"`: it has no destination.
 
 ## Numeric Range Constraints
 
-Use inline `@min` and `@max` JSDoc tags for fixed-domain numeric props. Manifest
-generation reads the tags automatically.
+Use inline `@min`, `@max` JSDoc tags for fixed-domain numeric props. Manifest
+generation reads them automatically.
 
 ```ts
 export type RatingProps = {
@@ -57,12 +57,12 @@ export type RatingProps = {
 };
 ```
 
-Use fixed bounds for ratings, percentages, playback speed, columns, etc. Omit
-for open-ended values or indices tied to a dynamic collection.
+Use for ratings, percentages, columns; omit for open-ended values or indices
+tied to a dynamic collection.
 
 ## Named Parts and `elementProps`
 
-Treat an independently editable inner element as a named part. Wiring rules:
+An independently editable inner element is a named part:
 
 - Root receives top-level `id`, `className`, `direction`, `a11y` — no
   `elementProps` entry.
@@ -75,7 +75,7 @@ On a raw HTML element, spread the entry and explicitly merge its injected
 ```tsx
 <a
   {...elementProps?.planCardCta}
-  className={classNames(
+  className={clsx(
     'plan-card-cta',
     styles.cta,
     elementProps?.planCardCta?.className,
@@ -118,12 +118,12 @@ does not inherit the component's direction.
 
 ### Array Props
 
-Array elements must be objects with named keys for semantics and extensibility.
+Array elements must be objects with named keys for semantics and extensibility. Always declare array-item fields optional.
 
 ```ts
 type GalleryProps = {
-  images: Array<{ image: Image; caption?: string }>;
-  tags: Array<{ label: string }>;
+  images: Array<{ image?: Image; caption?: string }>;
+  tags: Array<{ label?: string }>;
 };
 ```
 
@@ -131,22 +131,25 @@ Do not export `Array<string>`, `Array<Image>`, `Array<Array<T>>`, or nested
 arrays inside items.
 
 The parent owns the array. Item sub-components receive one item, not the
-collection. Do not add an `id` field for React keys—use the item's semantic
-named fields instead. Prefer: (1) a stable unique field (`value`, `uri`, `label`, …), (2)
-else slug a user-facing string (`name`, `label`), (3) else the array index.
+collection. Do not add an `id` field for React keys—use semantic named fields.
+Prefer: (1) a stable unique field (`value`, `uri`, `label`, …), (2) else slug a
+user-facing string (`name`, `label`), (3) else the index.
 
 ## Active-Item Components
 
-Apply this contract when an array-driven UI shows one item body at a time (tabs,
-slides, steps). Skip for always-visible lists, multi-select, or multi-expand.
+Apply when an array-driven UI shows one item body at a time (tabs, slides,
+steps). Skip for always-visible lists, multi-select, or multi-expand.
 
-- Every item needs `name: string` (used for hat-selector labels).
+- Declare `name` only when a part renders it; the hat shows `name`, else
+  "Item N". A visible per-item trigger label (tabs, steps) is the `name` field.
+  Slides, cards, carousels with no per-item label: no `name`. Never declare an
+  item field no part renders.
 - **Import and use `ActiveItemIndex<'arrayPropName'>`** from
   `@wix/react-component-utils`. The type argument must match the array prop name
   exactly, and `defaultProps` must set the index to `0`.
-- Render all bodies with `.map()`. Active body gets --active; inactive bodies get functional CSS visibility, aria-hidden, and inert.
-- With React 18 types, spread `...(!isActive ? { inert: 'true' } : {})` onto an inactive body; this emits the boolean HTML attribute without a TypeScript prop error. Use the app's typecheck instead of a scratch TypeScript project.
-- Provide keyboard navigation and the matching ARIA pattern.
+- Render all bodies with `.map()`. Active body gets `--active`; inactive bodies get CSS visibility, `aria-hidden`, and `inert`.
+- React 18 types: spread `...(!isActive ? { inert: 'true' } : {})` onto an inactive body; it emits the boolean attribute without a type error. Typecheck with the app, not a scratch project.
+- Keyboard navigation and the matching ARIA pattern.
 
 ```ts
 import type { A11y, Direction } from '@wix/editor-react-types';
@@ -180,7 +183,7 @@ one representation of it.
 Common fields in the installed types: `Image` has required `url: string` and
 optional `uri`, `alt`, `width`, `height`; `Link` has optional `href`, `target`
 (`'_self' | '_blank'`), and `rel`. Use `image.url` for `<img src>`,
-`image.alt` for its alternative text, and `link.href` for `<a href>`.
+`image.alt` for alt text, and `link.href` for `<a href>`.
 
 Do not represent media as a URL/source string or split its metadata across
 primitive props. Preserve the media object through the public contract so the
@@ -216,7 +219,7 @@ export const defaultProps = {
 ```
 
 Use distinct Wix-hosted defaults per image slot; keep all fallback data in
-`defaultProps` so rendering never hardcodes a second fallback in JSX.
+`defaultProps` so JSX never hardcodes a second fallback.
 
 Use this pool in order, cycling only when more than five defaults are needed:
 
@@ -228,8 +231,6 @@ Use this pool in order, cycling only when more than five defaults are needed:
 | 4 | `11062b_45e67783d39c4963ab9e4fc418173233~mv2.jpg` | Abstract pink waves |
 | 5 | `11062b_4c11f014b0d04948b2e6f554076bc40a~mv2.jpg` | Coastal village aerial |
 
-For one image use entry 1; for multiple slots use a different entry each.
-
 ## Internal File Splitting
 
 Split independently understandable units when it makes the main component easier
@@ -248,7 +249,7 @@ component-name/
 └── component-name.module.css
 ```
 
-Do not extract tiny fragments merely to satisfy a line-count threshold.
+Do not extract tiny fragments just to pass a line-count threshold.
 
 ## Checklist
 
@@ -256,7 +257,7 @@ Do not extract tiny fragments merely to satisfy a line-count threshold.
 - [ ] Props hold authored data/behavior; derived values stay internal.
 - [ ] Fixed-domain numeric props use `@min`/`@max` JSDoc tags.
 - [ ] Named inner parts have `elementProps` wiring; leaf components avoid exported `children`.
-- [ ] One-body-visible arrays use the active-item contract and render all bodies.
+- [ ] One-body-visible arrays use the active-item contract and render all bodies; `name` only when a part renders it.
 - [ ] Array elements are objects with semantic named fields. No separate `id` field added to item types; React keys use item fields (stable unique → slug → index), not a typed `id`.
 - [ ] Authored media uses the corresponding Wix media type, not URL/source strings or flattened metadata.
 - [ ] Defaults live only in the props file (no JSX fallbacks).

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

@@ -3,9 +3,6 @@
 Use these rules for the scaffolded `<component-name>.module.css` file and any
 colocated CSS Modules owned by internal sub-components.
 
-**Visual intent.** When the request specifies how the component should look —
-mood, palette, layout style, or a reference — follow that direction. Default to a modern, refined look — intentional layout, pleasing proportions, polished and deliberate styling.
-
 ## Contents
 
 - [Classes and Named Parts](#classes-and-named-parts)
@@ -15,12 +12,11 @@ mood, palette, layout style, or a reference — follow that direction. Default t
 - [Responsiveness and Direction](#responsiveness-and-direction)
 - [Editable Values](#editable-values)
 - [Interaction and Motion](#interaction-and-motion)
-- [Default Visual Quality](#default-visual-quality)
 - [Checklist](#checklist)
 
 ## Classes and Named Parts
 
-Apply classes with `classnames`:
+Apply classes with `clsx` (`import clsx from 'clsx'`):
 
 | Element | Classes |
 | --- | --- |
@@ -37,7 +33,7 @@ spread its `elementProps` entry and merge the injected class.
 ```tsx
 <h2
   {...elementProps?.profileCardHeading}
-  className={classNames(
+  className={clsx(
     'profile-card-heading',
     styles.heading,
     elementProps?.profileCardHeading?.className,
@@ -71,11 +67,11 @@ Do not use compound selectors, tag selectors, child/sibling combinators, or CSS
 nesting for editable styling. They make an element's editor surface depend on
 DOM context.
 
-Narrow exception: a relationship selector may control behavior-only visibility
-when the behavior requires ancestor state and the rule does not define editable
-appearance. A hover-revealed play/pause control is the canonical case. Keep all
-of the control's size, color, border, typography, and state styling on its own
-single-class rules.
+Narrow exceptions, neither defining editable appearance: a relationship
+selector for behavior-only visibility that needs ancestor state (a
+hover-revealed play/pause control), and an icon part's layout-only `svg` rule
+(`VECTOR-ART.md`). Keep each control's size, color, border, typography, and state
+styling on its own single-class rules.
 
 ## Root Layout
 
@@ -218,11 +214,14 @@ per icon (`--start-icon-size`), applied via `inline-size`/`block-size` and
 }
 ```
 
+- **Replaceable**: follow `VECTOR-ART.md`.
+
 ## Interaction and Motion
 
 - Set `pointer-events: auto` on the root and each interactive element.
-- Pair native interaction selectors with the matching editor-injected global
-  state modifier. Toggle custom state modifiers from component data.
+- Pair native design states (`hover`, `focus`, `disabled`, `invalid`) with
+  the matching editor-injected global modifier. Custom modifiers need a class
+  toggle from component logic/data or a root prop trigger (`DESIGN-STATES.md` §5).
 - Do not add decorative transitions or animations.
 - When motion is functionally required, list the exact transition properties;
   never use `transition: all` or an implicit `all` shorthand.
@@ -233,32 +232,6 @@ per icon (`--start-icon-size`), applied via `inline-size`/`block-size` and
 }
 ```
 
-## Default Visual Quality
-
-Create a clear hierarchy with at least two techniques that fit the component:
-a defined surface, border or soft shadow, type scale or weight, spacing, an
-accent, or visible interaction states. Use these neutral defaults unless the
-request or existing design provides better values:
-
-- 16px or larger body text, 14px or larger labels, and 600–700 weight for titles
-- 8–16px spacing inside controls and 16–32px spacing inside containers
-- 8–12px corner radii for cards and controls; `50%` for circular media
-- a subtle border or soft shadow when a card, panel, or control needs separation
-- touch targets at least 44 by 44px and visible keyboard focus states
-
-### Foreground and Background Ownership
-
-If the component is a self-contained block (card, panel, banner, accordion item), give the root a background. An inline control meant to blend in (link, ghost button, icon button) may leave it transparent.
-
-- On a transparent root, don't hardcode text or icon colors; inherit them from the parent.
-- Set the background and main text/icon color together on the same element. Any secondary text (captions, hints, icons) must still be readable against that same background.
-- If an interactive state changes the background, set the foreground color in that state too. Don't assume a color inherited from a parent or from a previous state will still look right on the new background.
-- In every default and interactive state, meet WCAG AA contrast: 4.5:1 for body text and 3:1 for large text and UI controls.
-
-A neutral owned surface may use a light background with dark primary and
-secondary foregrounds, plus one accessible accent. The exact colors are not a
-contract; the contrast relationship is.
-
 ## Checklist
 
 - [ ] The scaffolded component and each extracted internal sub-component own
@@ -273,8 +246,5 @@ contract; the contrast relationship is.
 - [ ] Every part that sets `font-size` also sets `font-family`, on the part that
       should own the typography control.
 - [ ] Interactive elements expose pointer events and accessible design states.
-- [ ] Visual containers have deliberate hierarchy rather than bare scaffolding.
-- [ ] Every explicit foreground has a known contrasting background; transparent
-      components inherit foregrounds from their host.
 - [ ] No unexposed descendant paints an opaque surface; promote it to a named
       part instead.

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

@@ -6,16 +6,6 @@ eligible interaction (`hover`, `focus`, `disabled`, `invalid`) or per a
 selectable value in its data (`selected`, `active`, `checked`, …). Author states
 in the component's `.tsx` and `.module.css`.
 
-## Contents
-
-- [Choose Supported States](#1-choose-supported-states)
-- [Name the State Class](#2-name-the-state-class)
-- [Author CSS](#3-author-css)
-- [Wire React](#4-wire-react)
-- [Use Prop-Triggered States on the Root Only](#5-use-prop-triggered-states-on-the-root-only)
-- [Expose Open/Collapsed Toggles](#6-expose-opencollapsed-toggles)
-- [Checklist](#checklist)
-
 ## 1. Choose Supported States
 
 | Element | Author these states |
@@ -48,7 +38,7 @@ Flat: the element's own global class + `--<state>`. Because inner-part
 global classes are prefixed with the component name, the state class is prefixed too —
 e.g. `pricing-card-cta--hover`, `pricing-card-plan-row--selected`. Never bare
 (`cta--hover` collides with other components) and never
-nested (`card__row--selected`).
+nested (`card__row--selected`). Add it only to an element that has its base class.
 
 ## 3. Author CSS
 
@@ -58,7 +48,7 @@ state selector. When both set the same property, write the state selector
 value as the part's resting `defaultValue`, even though runtime CSS renders
 correctly.
 
-- **Native design state** — pair the pseudo-class with the `:global` modifier.
+- **Native (`hover`, `focus`, `disabled`, `invalid`)** — pair the pseudo-class with the `:global` modifier.
   Every exposed native state needs both selectors in the same rule; do not
   split the pair across states. A standalone `:focus-visible` accessibility
   rule on a non-input control is not an editor design state and has no global
@@ -101,10 +91,9 @@ The local static accessibility scan cannot measure rendered color contrast.
 - **Native** — render the correct interactive element (`<button>`, an
   interactive `role`, or a handler). No custom state class is needed, but the
   element must still satisfy the accessibility contract for its semantics.
-- **Custom** — toggle the global state class from the element's data, except
-  for open/collapsed content (§6). Every state class toggled in TSX needs a
-  matching `:global()` rule in §3; without one the manifest generator silently
-  drops the state.
+- **Custom** — each `:global()` state rule must have a matching class toggle
+  driven by component logic or data, or a root prop trigger (§5). Open/collapsed
+  content uses §6.
 - **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
@@ -115,14 +104,14 @@ The local static accessibility scan cannot measure rendered color contrast.
 <button
   type="button"
   {...elementProps?.pricingCardCta}
-  className={classNames('pricing-card-cta', styles.cta, elementProps?.pricingCardCta?.className)}
+  className={clsx('pricing-card-cta', styles.cta, elementProps?.pricingCardCta?.className)}
 >
   {label}
 </button>
 
 <li
   {...elementProps?.pricingCardPlanRow}
-  className={classNames(
+  className={clsx(
     'pricing-card-plan-row',
     styles.planRow,
     row.selected && 'pricing-card-plan-row--selected',
@@ -205,7 +194,7 @@ React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
   {...elementProps?.infoPanelContent}
   aria-hidden={!open}
   {...(!open && { inert: '' })}
-  className={classNames(
+  className={clsx(
     'info-panel-content',
     styles.content,
     open && styles.contentOpen,
@@ -229,7 +218,7 @@ React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
 - [ ] Non-input controls retain a standalone `:focus-visible` keyboard indicator.
 - [ ] Custom state classes are flat, global, and prefixed by component and part.
 - [ ] Named inner parts spread and merge their `elementProps` entry.
-- [ ] Every state class toggled in TSX has a matching `:global()` CSS rule.
+- [ ] Custom CSS state rules and their class toggles or root prop triggers match.
 - [ ] `ElementState<boolean>` is used only for a component-level root state.
 - [ ] An open/collapsed component exposes a props-only `isOpen` root state,
       syncs internal state from it, always renders its content, and adds no

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

@@ -23,12 +23,13 @@ After each fix, re-run `npx wix build && npx wix generate manifest` to confirm.
 ## Warnings
 
 The build can also print non-fatal warnings such as
-`[css] … styles selectors that matched no element in the extraction render`.
+`.item is missing from initial render (<file>)`.
 Read every warning and fix it; this is mandatory, with one exception below.
 
-- **A part's own class** (`.errorMessage`, `.item`) means the part is not
-  mounted in the extraction render. Keep it mounted per `PARTS.md`, then
-  re-run build and manifest generation.
+- **A `.tsx` file in parentheses**, or **a part's own class** (`.errorMessage`,
+  `.item`) in a `.css` file, means the part is not mounted in the extraction
+  render. Keep it mounted and hide it with `hidden` or CSS per `PARTS.md`,
+  then re-run build and manifest generation.
 - **A class applied only by state** (`.contentOpen` from `open && styles.contentOpen`)
   is expected: the part is mounted and only the state look is absent. Leave the
   markup and CSS unchanged; do not force the state on or remove the styling.

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

@@ -71,7 +71,7 @@ const item = current ?? placeholderItem; // placeholder shows only while hidden
 <div hidden={phase !== 'question'}>
   <h3
     {...elementProps?.quizQuestion}
-    className={classNames('quiz-question', styles.question, elementProps?.quizQuestion?.className)}
+    className={clsx('quiz-question', styles.question, elementProps?.quizQuestion?.className)}
   >
     {item.question}
   </h3>

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

@@ -32,7 +32,7 @@ Use this pattern:
 ```tsx
 <div
   {...elementProps?.audioPlayerProgressBar}
-  className={classNames(
+  className={clsx(
     'audio-player-progress-bar',
     styles.progressBar,
     elementProps?.audioPlayerProgressBar?.className,

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

@@ -0,0 +1,95 @@
+# Vector Art
+
+Use this reference when a component shows an icon or other SVG the site owner
+can replace. Fixed glyphs stay inline per
+CSS-GUIDELINES.md "SVG Icons".
+
+## The Prop
+
+Import `VectorArt` from `@wix/editor-react-types`. All fields are required; keep
+the whole object, never flatten it to a URL string.
+
+Declare it at the top level or as an array-item field, never in `elementProps`,
+which stays `className` only:
+
+```ts
+export type FeatureRowProps = {
+  icon?: VectorArt;
+  elementProps?: { featureRowIcon?: { className?: string } };
+};
+```
+
+## Render and Style
+
+The icon is a named part per `PARTS.md`. Inject `svgContent` unmodified (no
+`.replace()` or added attributes). Mark it `aria-hidden="true"` beside a visible label, or name the
+control with `a11y.ariaLabel` per `ACCESSIBILITY.md`.
+
+```tsx
+{icon && (
+  <span
+    {...elementProps?.featureRowIcon}
+    className={clsx('feature-row-icon', styles.icon, elementProps?.featureRowIcon?.className)}
+    aria-hidden="true"
+    dangerouslySetInnerHTML={{ __html: icon.svgContent }}
+  />
+)}
+```
+
+Declare the controls per CSS-GUIDELINES.md "SVG Icons", plus `--icon-rotation`
+via `rotate`. Add no border, background, or padding.
+
+```css
+.icon {
+  --icon-size: 24px;
+  --icon-color: #116dff;
+  --icon-rotation: 0deg;
+  display: block;
+  inline-size: var(--icon-size);
+  block-size: var(--icon-size);
+  fill: var(--icon-color);
+  rotate: var(--icon-rotation);
+}
+
+.icon svg {
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+}
+```
+
+With several icons, give each part its own class and prefixed properties;
+shared names merge into one control. Only the property-free `svg` rule may be
+shared (`.startIcon svg, .endIcon svg`).
+
+## Defaults
+
+Populate all six fields in `defaultProps`; keep them there, with no second
+fallback in JSX. Never invent a `uri` or use a `data:` URI.
+
+```ts
+export const defaultProps = {
+  icon: {
+    uri: '417ddd_00f94d35a8f84b959241a5d4293ee772.svg',
+    viewBox: '0 0 200 200',
+    contentBox: '10 10 180 180',
+    colors: {},
+    contentType: 'shape',
+    svgContent:
+      '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" data-type="shape"><path d="M100 190c49.706 0 90-40.294 90-90s-40.294-90-90-90-90 40.294-90 90 40.294 90 90 90"/></svg>',
+  },
+} as const satisfies Omit<FeatureRowProps, 'id' | 'className'>;
+```
+
+For further slots substitute `uri` and the path `d` (same `viewBox` and `contentBox`):
+
+| `uri` | Shape | path `d` |
+| --- | --- | --- |
+| `417ddd_3d6ddf28b43e45499ea8557b8d963c79.svg` | Arch | `M100 10c49.704 0 90 37.654 90 84.102V190H10V94.102C10 47.654 50.294 10 100 10` |
+| `417ddd_c4e65c20d3844ffd97c9b2551ce7d269.svg` | Heptagon | `m100 10 72.174 35.651L190 125.76 140.054 190H59.946L10 125.759l17.826-80.108z` |
+
+## Checklist
+
+- [ ] A replaceable icon is a `VectorArt` prop, not an inline `<svg>` or URL string.
+- [ ] Each icon is its own named part injecting `svgContent` unmodified, with prefixed `--icon-*` properties.
+- [ ] `defaultProps` carries all six fields with a `uri` from the pool.