@wix/agent-skills 1.35.0 → 1.36.0

package/package.json

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

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/dashboard-page/DRAFT_TEMPLATE.md

@@ -1,6 +1,6 @@
 # Draft Template — the starting point for every dashboard page
 
-**Start here for any Dashboard Page request, before writing a shell, provider, or router from scratch.** The templates themselves ship inside the installed `@wix/patterns`: whole, working pages that the package type-checks against its own release, so they never drift from the version your code compiles against. This file says how to find one, where its files go in a Wix CLI app, and what this skill adds on top. Which template fits, and the wiring each one must keep, is the package's answer — read it there.
+**Start here for any Dashboard Page request, before writing a shell, provider, or router.** Page templates ship inside the installed `@wix/patterns`. This file covers finding and placing their files in a Wix CLI app; the package's `Page Templates.md` chooses the template and explains its wiring.
 
 Go through [WIX_PATTERNS_DOCS.md § Prerequisites](../WIX_PATTERNS_DOCS.md#prerequisites) first for `<pkgRoot>`; every path below is relative to it.
 
@@ -12,7 +12,7 @@ One call lists every page template with its files, plus the guide that chooses b
 node <pkgRoot>/bin/patterns-lookup.cjs --templates
 ```
 
-It also takes names (`--templates Table useTableCollection …`), so the patterns names you already know you'll need can go in the same call ([WIX_PATTERNS_DOCS.md § 1](../WIX_PATTERNS_DOCS.md#1--the-index)). If the script is missing (an older `@wix/patterns`), list those entries from `<pkgRoot>/dist/docs/index.json` in one probe.
+Add known symbols to the same call (`--templates Table useTableCollection`). Without the script, probe the Templates entries in `<pkgRoot>/dist/docs/index.json` once.
 
 **No `Templates` entries means the install predates them — upgrade `@wix/patterns`.** Do not rebuild a page from memory or from an older copy of this skill instead: the templates exist so the shell, provider nesting and router wiring come from the package.
 
@@ -53,6 +53,8 @@ Then copy **every** file `--templates` lists for it into the generated folder (`
 
 - **Theme the entry file.** In it, replace the template's `WixDesignSystemProvider` and its `@wix/design-system/styles.global.css` import with the app's `BusinessManagerTheme` — written once per app ([BUSINESS_MANAGER_THEME.md § 2](../BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app)), kept in the entry file so it sits above `WixPatternsProvider`. **Business Manager passes none of the redesign through the extension's iframe**, so the bare provider renders the pre-redesign look while `tsc`, `wix build` and `wix preview` all pass.
 
+**If the page needs tabs:** Start from a Patterns template. When tabs navigate between different sections, use WDS `Tabs`, reuse the template’s provider and router, and keep Patterns components for managing each section’s entities. Adapt the routes and navigation together so opening an entity and returning selects the correct section. When tabs only filter the same entity list, pass Patterns `TabsFilter` to the Table’s `tabs` prop.
+
 ## 4. Replace the data file
 
 Each template's data file (`items-api.ts`, `settings-api.ts`) is an in-memory stand-in with the signatures the pages call. Replace the bodies, keep the signatures:
@@ -79,7 +81,7 @@ npm dedupe
 find node_modules -path '*@wix/patterns/package.json' -not -path '*/dist/*'
 ```
 
-More than one line is a bug that `tsc` and `wix build` both pass. Declared ranges produce it when `@wix/patterns` ships ahead of `@wix/patterns-cms`, or a lockfile holds an older one. Run the second `npm install` line above, then the check again.
+More than one copy breaks shared context despite passing `tsc` and build. Align the versions with the second install command above, then check again.
 
 ### Turning `query.search` into a query
 

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,