@wix/agent-skills 1.23.0 → 1.24.0

package/package.json

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

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

@@ -1,13 +1,11 @@
 # Wix Editor React Component Builder
 
 Build Editor React Components for Harmony/Studio2 Wix CLI apps only. First
-determine **create vs edit**; for edits, inspect the existing component and
-never re-scaffold.
+determine **create vs edit**; for edits, inspect the existing component.
 
 ## File Contract
 
-Use the Wix CLI scaffold as the source of truth. Do not replace it with a custom
-layout or a hand-written manifest. Preserve these file responsibilities:
+Keep the Wix CLI scaffold and file roles:
 
 | File | Ownership | Purpose |
 | --- | --- | --- |
@@ -16,37 +14,55 @@ layout or a hand-written manifest. Preserve these file responsibilities:
 | `<component-name>.module.css` | Edit | Scoped component styles |
 | `component.tsx` | Keep generated | Wire component and `defaultProps` with `withDefaults` |
 | `component.preview.tsx` | Edit narrowly | Sync preview adapter, one crucial data field, root class |
-| `<component-name>.generated.ts` | NEVER edit | Generated manifest — do not edit |
+| `<component-name>.generated.ts` | NEVER edit | Generated manifest |
 | `<component-name>.extension.ts` | Edit narrowly | Supported partial manifest overrides |
 
-Supplementary files (constants, hooks, sub-components) are allowed; keep scaffold
-roles intact.
+Supplementary files are allowed; keep scaffold roles intact.
 
 ## Workflow
 
-1. **Scaffold only when creating.** If the component folder does not exist, run
-   inside the Wix app project (the folder with `wix.config.json`):
+1. **Scaffold only when creating.** Run in the Wix app (`wix.config.json`).
+   Check the current directory, then this workspace; never search the OS:
 
    ```bash
-   npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A brief description"}'
+   npx wix generate --params '{"extensionType":"EDITOR_REACT_COMPONENT","name":"ComponentName","folder":"component-name","description":"A meaningful description of component's intent and functionality"}'
    ```
 
-   Creates `src/extensions/site/components/<component-name>/` and registers the
-   extension in `src/extensions.ts`. Do not rerun for an existing component.
+   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 component name or add implementation details.
 
-2. **Run the dependency preflight.** Verify that all component creation and
-   accessibility-review dependencies are installed:
+2. **Run the dependency preflight.** Check required packages:
 
    ```bash
-   node -e "const fs=require('fs'),path=require('path'),ps=['@wix/react-component-schema','@wix/react-component-utils','@wix/editor-react-types','@babel/parser','@babel/traverse','@babel/types','eslint','eslint-plugin-jsx-a11y','@typescript-eslint/parser','typescript','@types/eslint-plugin-jsx-a11y','jsdom','axe-core'];const missing=ps.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(', '));process.exit(1)}" || { d="$PWD"; while [ "$d" != "/" ] && [ ! -f "$d/yarn.lock" ]; do d="${d%/*}"; done; if [ -f "$d/yarn.lock" ]; then yarn add @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && yarn add -D @babel/parser @babel/traverse @babel/types eslint eslint-plugin-jsx-a11y @typescript-eslint/parser 'typescript@<7' @types/eslint-plugin-jsx-a11y jsdom axe-core; else npm install @wix/react-component-schema @wix/react-component-utils @wix/editor-react-types && npm install --save-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; fi; }
+   deps=(@wix/react-component-schema @wix/react-component-utils @wix/editor-react-types)
+   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' || {
+   const fs = require('fs'), path = require('path');
+   const missing = process.argv.slice(2)
+     .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(', ')}`);
+     process.exit(1);
+   }
+   JS
+     d="$PWD"
+     while [[ "$d" != / && ! -f "$d/yarn.lock" ]]; do d="$(dirname "$d")"; done
+     if [[ -f "$d/yarn.lock" ]]; then install=(yarn add); else install=(npm install); fi
+     "${install[@]}" "${deps[@]}" && "${install[@]}" -D "${dev[@]}"
+   }
    ```
 
-3. **Plan the contract and structure.** Identify props, semantic root, named
-   parts, and design states; read routed references below before writing code.
+3. **Plan.** Identify props, root, parts, and states; read routed references.
+   Use the scaffold and references before package declarations; probe an API
+   only when undocumented or a typecheck fails.
 
-4. **Implement the editable sources.** Preserve the scaffold contract: props in
-   the props file, logic in TSX, styles in the CSS Module. Do not edit
-   `*.generated.ts`.
+4. **Implement.** Keep props, logic, and styles in their scaffolded editable
+   files. Format edited source files with the app's configured formatter before
+   checking formatting. Never edit or format `*.generated.ts`.
 
 5. **Run the accessibility review.** Once the JSX is complete, run from the
    same folder (`<SKILL_ROOT>` is the directory containing the active `SKILL.md`):
@@ -55,42 +71,36 @@ roles intact.
    node <SKILL_ROOT>/scripts/scan-a11y-review.cjs src/extensions/site/components/<component-name>
    ```
 
-   Then follow [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md):
-   fix confirmed findings, rerun after each fix pass (at most two), and report
-   what remains.
+   Follow [`editor-react-component/ACCESSIBILITY.md`](editor-react-component/ACCESSIBILITY.md); fix and
+   rerun at most twice, then report remaining findings.
 
-6. **Configure the editor extension when required.** For a new component or a
-   requested sizing, installation, or manifest change, apply
+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)
-   to `<component-name>.extension.ts`. Otherwise leave the file unchanged.
-   Synchronize `requiredDataFields` and `rootClassName` in
-   `component.preview.tsx`.
+   to the extension; otherwise leave it unchanged. Synchronize preview
+   `requiredDataFields` and `rootClassName`.
 
-7. **Generate and validate.** Run:
+7. **Generate and validate.** Batch implementation edits, then build and
+   generate the manifest once:
 
    ```bash
    npx wix build && npx wix generate manifest
-   npx tsc --noEmit
    ```
 
-   Run relevant tests and lint when available. Inspect the regenerated manifest;
-   never repair it by hand. On failure, diagnose with
+   Run `npx tsc --noEmit`, relevant tests/lint, and the accessibility 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).
 
-8. **Report the result.** Summarize edited files and checks. Call out any
-   unresolved conflict, missing dependency, unsupported CLI version, or check
-   that could not run.
+   For creation/layout changes, complete the routed overflow resize review.
 
-## Reference Policy
+8. **Report.** Summarize files, checks, blockers, and checks that could not run.
 
-- Read **only** matching required + triggered optional rows; optional triggers
-  become required when they match.
-- References refine the active step; they do not restart workflow or expand scope.
-- Never re-scaffold an existing component or edit `*.generated.ts`.
+## Reference Policy
 
-`SKILL.md` is the only reference router; reference files are self-contained
-leaves. For existing components, preserve out-of-scope public props, styling,
-extension configuration, and supporting files.
+Read only matched references. Preserve unrelated behavior. `SKILL.md` routes;
+references are leaves.
 
 ### Required References
 
@@ -102,6 +112,7 @@ extension configuration, and supporting files.
 | 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 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) |
 
@@ -109,7 +120,7 @@ extension configuration, and supporting files.
 
 | Trigger | Read |
 | --- | --- |
-| Interactive/selectable part or custom state | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
+| Interactive/selectable part, custom state, or open/collapse toggle | [`DESIGN-STATES.md`](editor-react-component/DESIGN-STATES.md) |
 | Creating interactive components or changing interactions/callbacks | [`FUNCTION-HANDLERS.md`](editor-react-component/FUNCTION-HANDLERS.md) |
 | Browser APIs, effects, or time-dependent output | [`SSR.md`](editor-react-component/SSR.md) |
 | Non-established CSS feature or DOM API, or user asks for one by name | [`BROWSER-SUPPORT.md`](editor-react-component/BROWSER-SUPPORT.md) |
@@ -135,14 +146,17 @@ extension configuration, and supporting files.
   top-level props).
 - Native design states: pair selectors with injected modifiers; keep non-input
   `:focus-visible` standalone unless editable focus is requested; toggle custom
-  state classes from data.
+  state classes from data, each with a matching `:global()` rule.
+- Open/collapse components: expose a props-only `isOpen: ElementState<boolean>`
+  root state and sync internal state from it.
 - Single-visible-body arrays: `name` per item, `ActiveItemIndex<'prop'>`, render
   all bodies, hide inactive accessibly.
 - Autoplay/loop: play/pause control, honor reduced motion, suppress autoplay in
   editor design mode.
-- `component.preview.tsx`: preserve this outer-to-inner composition, inline or
-  through component variables:
+- Resizable layout: keep required content usable at 320px. Reflow visible
+  groups inside their page and cap track minima with
+  `minmax(min(100%, <minimum>), 1fr)`. Follow [`OVERFLOW.md`](editor-react-component/OVERFLOW.md).
+- Preview composition, inline or through variables:
   `withDefaults(withFallbackPlaceholder(PreviewOrComponent, options), defaultProps)`.
-  Keep `withDefaults` outermost, wrap the preview adapter when present, use one
-  crucial `requiredDataFields` entry, and match `rootClassName` to the root
-  global class.
+  Keep `withDefaults` outermost; use one crucial data field and match the root
+  class.

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

@@ -1,7 +1,6 @@
 # Accessibility Implementation and Review
 
-Use this reference while authoring Editor React Component props and JSX, then
-run the review command once the JSX is complete.
+Use while authoring; run the review after JSX is complete.
 
 ## Contents
 
@@ -41,7 +40,9 @@ function Toggle({ elementProps }: ToggleProps) {
 
   return (
     <button {...toggleProps} aria-label={toggleA11y?.ariaLabel ?? ARIA_LABELS.toggle}>
-      <ChevronIcon aria-hidden="true" />
+      <svg aria-hidden="true" viewBox="0 0 16 16">
+        <path d="m3 6 5 5 5-5" fill="none" stroke="currentColor" />
+      </svg>
     </button>
   );
 }

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

@@ -5,23 +5,9 @@ Use this reference when the component's primary content **auto-advances or plays
 
 Every such component must ship an on-stage **play/pause button**.
 
-## Contents
-
-- [Apply When](#apply-when)
-- [Required Contract](#required-contract)
-- [Announce Manually Selected Parallel Content](#announce-manually-selected-parallel-content)
-- [Define Props](#1-define-props)
-- [Manage Playback State](#2-manage-playback-state)
-- [Add the Play/Pause Button](#3-add-the-playpause-button)
-- [Suppress Autoplay in `component.preview.tsx`](#4-suppress-autoplay-in-componentpreviewtsx)
-- [Edit the generated `component.preview.tsx`](#edit-the-generated-componentpreviewtsx)
-- [Checklist](#checklist)
-
 ## Apply When
 
-Apply automatically — without being asked — whenever the component has an
-`autoPlay` prop **or** its primary content is a **startable / loopable**
-animation a visitor would reasonably want to start or stop:
+Apply whenever the component has `autoPlay` or startable/loopable primary content:
 
 - Slideshow, carousel, slider, or gallery that advances slides/cards
 - Lottie / JSON vector animations
@@ -94,8 +80,20 @@ export interface MyAnimationProps {
 }
 ```
 
-The example shows a looping animation. Omit `loop` when the component does not
-support repeat behavior; do not add it only to match the example.
+Omit `loop` when repeat is unsupported.
+
+### Lottie / JSON source
+
+For Lottie, `animationUrl?: string` is a JSON URL, not `VectorArt` (SVG).
+This and its renderer are exceptions to the generic media/dependency rules in
+`COMPONENT-CONTRACT.md`. Check `package.json`: use `lottie-web` if present,
+otherwise add it as a runtime dependency. Import `lottie` and
+`type AnimationItem` from it. In an effect, call
+`lottie.loadAnimation({ container, renderer: 'svg', path: animationUrl,
+loop, autoplay: false })`; keep the item in a ref, destroy it on cleanup,
+and use `play()` / `pause()` when `isPlaying` changes. Browser work belongs in
+effects. If no URL is supplied, bundle a valid local Lottie JSON asset and
+import it with `?url` as the component default; a placeholder URL renders blank.
 
 ## 2. Manage Playback State
 
@@ -109,20 +107,22 @@ const reducedMotion = useReducedMotion();
 
 const [isPlayOn, setIsPlayOn] = React.useState(() => (autoPlay ?? true) && !reducedMotion);
 
-const skipInitialAutoPlaySync = React.useRef(true);
+const previousAutoPlay = React.useRef(autoPlay);
 React.useEffect(() => {
-  if (skipInitialAutoPlaySync.current) {
-    skipInitialAutoPlaySync.current = false;
-    return;
+  if (previousAutoPlay.current !== autoPlay) {
+    setIsPlayOn((autoPlay ?? true) && !reducedMotion);
+  } else if (reducedMotion) {
+    setIsPlayOn(false);
   }
-  setIsPlayOn(autoPlay ?? true);
-}, [autoPlay]);
+  previousAutoPlay.current = autoPlay;
+}, [autoPlay, reducedMotion]);
 
 const handlePause = () => setIsPlayOn(false);
 const handleResume = () => setIsPlayOn(true);
 ```
 
-`reducedMotion` is a runtime signal, not a manifest/data prop.
+`reducedMotion` is runtime-only. Pause when the OS turns reduced motion on, but
+do not restart when it turns off. Resume can still override the preference.
 
 Derive runtime playback from `isPlayOn` plus only needed conditions. Without
 another condition, use `const isPlaying = isPlayOn`. A carousel, slideshow,
@@ -140,7 +140,10 @@ clears `isStoppedByFocus`.
 
 ## 3. Add the Play/Pause Button
 
-Create play/pause icons that visually match the component's style. Use simple recognizable shapes — a triangle for play, two rectangles for pause — implemented as inline SVG so there is no external icon dependency. Size and color of SVG should be controlled by CSS variables declared on the button level: --icon-size and --icon-color.
+Use inline SVG icons: a triangle for play and two bars for pause. Declare
+`--icon-size` and `--icon-color` on the button. Apply `var(--icon-size)` to the
+SVG's CSS `width` and `height` (or React `style`), not raw SVG attributes;
+set button `color: var(--icon-color)` and SVG `fill: currentColor`.
 
 Position the button absolutely so it overlays the content without pushing other elements out of place:
 

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

@@ -28,8 +28,14 @@ using CSS Modules `@value`, then consume with `var()`.
 - Do not use `var(--wst-*)` directly; import the `@value` alias first.
 - Do not pass a fallback as `var()`'s second argument
 - Do not use `@import`; CSS Modules resolves theme aliases through `@value`.
-- Do not use `wst-base-1-color` for text. Prefer heading/paragraph color tokens,
-  or `wst-base-2-color` when a base contrast color is required.
+- Do not use `wst-base-1-color` for text on a light surface. Prefer
+  heading/paragraph color tokens for body text.
+- Use matching control tokens: pair `wst-button-primary-background-color` with
+  `wst-button-primary-color` for a primary CTA (or the secondary pair for a
+  secondary CTA). Do not mix `wst-links-and-actions-color` with
+  `wst-base-2-color` as button background and text: they are unrelated tokens
+  and may fail contrast. Check the rendered contrast of every state, and choose
+  a different token pair or design if it fails.
 
 ## Checklist
 

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

@@ -3,17 +3,6 @@
 Use this reference when defining props, defaults, named-part wiring, complex data,
 or internal file boundaries.
 
-## Contents
-
-- [Public Props Contract](#public-props-contract)
-- [Numeric Range Constraints](#numeric-range-constraints)
-- [Named Parts and `elementProps`](#named-parts-and-elementprops)
-- [Content and Data](#content-and-data)
-- [Active-Item Components](#active-item-components)
-- [Defaults and Resources](#defaults-and-resources)
-- [Internal File Splitting](#internal-file-splitting)
-- [Checklist](#checklist)
-
 ## Public Props Contract
 
 Keep identity and platform contracts together with component-specific data and
@@ -54,6 +43,9 @@ Rules:
 - Default to common optional SDK callbacks by capability; add specialized ones
   when requested. Keep implementation handlers internal.
 - Use `Array<T>`, not `T[]`, for exported arrays.
+- A CTA with a real destination is a native link with that `href`. If it only
+  performs an action, use a native button. Never use `href="#"` as a fallback;
+  it creates a focusable link without a meaningful destination.
 
 ## Numeric Range Constraints
 
@@ -153,6 +145,7 @@ slides, steps). Skip for always-visible lists, multi-select, or multi-expand.
   `@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.
 
 ```ts
@@ -184,11 +177,16 @@ media type, whether it is a top-level prop or a field in an array item. Name
 the field for the media itself (`image`, `video`, `audio`, and so on), not for
 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>`.
+
 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
-component can consume all of its supported data. See
-`node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts` for the
-full list.
+component can consume all of its supported data. Inspect the installed media
+type declaration only if a needed field is not covered here or a typecheck
+reports an error.
 
 ## Defaults and Resources
 

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

@@ -56,6 +56,7 @@ that semantic element is the root. Do not wrap it just to host root props.
 
 Use flat, top-level selectors. Each selector must target one class plus an
 optional state pseudo-class or global state modifier.
+Put state overrides before bare classes so the manifest keeps resting defaults.
 
 ```css
 .heading {
@@ -103,7 +104,7 @@ Choose the simplest root shape that fits the component:
 
 - column: `--display: flex; flex-direction: column`
 - row: `--display: flex; flex-direction: row`
-- split layout: `--display: grid; grid-template-columns: 1fr 1fr`
+- split layout: `--display: grid; grid-template-columns: repeat(2, minmax(0, 1fr))`
 - responsive collection: `--display: grid; grid-template-columns: repeat(auto-fit, minmax(...))`
 
 Do not hardcode the root's pixel dimensions. Installation defaults belong in
@@ -136,7 +137,7 @@ the extension file.
 ## Responsiveness and Direction
 
 Respond to the component container, not the browser viewport. Prefer intrinsic
-flex/grid sizing, `minmax()`, `auto-fit`, `1fr`, and `clamp()`. Do not add
+flex/grid sizing and tracks that can shrink below content size. Do not add
 viewport `@media` rules; Wix owns page breakpoints.
 
 Use logical inline-axis properties so layout flips automatically in RTL:
@@ -171,7 +172,7 @@ Use this pattern:
 
 .grid {
   --columns: 3;
-  grid-template-columns: repeat(var(--columns), 1fr);
+  grid-template-columns: repeat(var(--columns), minmax(0, 1fr));
 }
 ```
 

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

@@ -13,6 +13,7 @@ in the component's `.tsx` and `.module.css`.
 - [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
@@ -24,6 +25,7 @@ in the component's `.tsx` and `.module.css`.
 | Other interactive element whose editable focus appearance the user explicitly requests | `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 |
+| Whole component opens/collapses (expandable panel, disclosure, dropdown, drawer), even when a click toggles it | root `isOpen` prop state — see §6 |
 | None of the above | no states — resting style only |
 
 An explicit `role` overrides the tag's implicit semantics: `<input role="button">`
@@ -51,7 +53,10 @@ nested (`card__row--selected`).
 ## 3. Author CSS
 
 Put the resting value in the bare class; put only the state override in the
-state selector.
+state selector. When both set the same property, write the state selector
+**before** the bare class. Manifest generation can otherwise record the state
+value as the part's resting `defaultValue`, even though runtime CSS renders
+correctly. The state selector still wins at runtime through its specificity.
 
 - **Native design state** — pair the pseudo-class with the `:global` modifier.
   Every exposed native state needs both selectors in the same rule; do not
@@ -63,17 +68,22 @@ state selector.
 The bare selector is the short **module** class (`.cta`); the `:global(...)`
 state class is the **prefixed** global one.
 
+Check text contrast against every background it appears on, including resting,
+hover, and selected states. Normal text needs at least 4.5:1; large text needs
+3:1. Pale gray small text on white or a tinted selected row commonly fails.
+The local static accessibility scan cannot measure rendered color contrast.
+
 ```css
+.cta:global(.pricing-card-cta--hover),
+.cta:hover {
+  background: #4f46e5;
+}
 .cta {
   background: #6366f1;
   font-family: 'Inter', sans-serif;
   font-size: 14px;
   color: #ffffff;
 } /* resting */
-.cta:global(.pricing-card-cta--hover),
-.cta:hover {
-  background: #4f46e5;
-}
 .cta:global(.pricing-card-cta--disabled),
 .cta:disabled {
   opacity: 0.5;
@@ -91,7 +101,9 @@ state class is the **prefixed** global one.
 - **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.
+- **Custom** — toggle the global state class from the element's data. Every
+  state class toggled in TSX needs a matching `:global()` rule in §3; without
+  one the manifest generator silently drops the state.
 - **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
@@ -155,8 +167,9 @@ Rules:
   `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).
+  entry carries that `className` and the editor lists it with the design-panel
+  states; with none it is props-only and appears in the on-stage state picker,
+  which sets the prop. An open/collapsed toggle must stay props-only (§6).
 
 ```css
 .pricingCard:global(.pricing-card--is-featured) {
@@ -166,7 +179,48 @@ Rules:
 
 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.
+at any depth. Reach for a prop trigger only for a root-level boolean switch
+or an open/collapsed toggle (§6).
+
+## 6. Expose Open/Collapsed Toggles
+
+For a component that opens or collapses, expose its state to the editor even
+when a click toggles it. `useState` alone gives the manifest no state picker.
+For one-of-many item bodies, use the active-item contract instead.
+
+- Add `isOpen?: ElementState<boolean>` and set `isOpen: false` in
+  `defaultProps`.
+- Seed and resync internal state from the prop; clicks update internal state.
+- Always render the collapsible content; hide it with CSS plus `aria-hidden`
+  and `inert` when closed. Never mount it with `open && …`.
+- Style the open state with inner-part classes
+  (`<component-name>-content--open`) and matching `:global()` rules, not only
+  inline styles or refs measured during render.
+- Keep the root state props-only for the on-stage picker (§5).
+
+```tsx
+const [open, setOpen] = React.useState(Boolean(isOpen));
+React.useEffect(() => setOpen(Boolean(isOpen)), [isOpen]);
+
+<div
+  {...elementProps?.content}
+  aria-hidden={!open}
+  {...(!open && { inert: '' })}
+  className={classNames(
+    'info-panel-content',
+    styles.content,
+    open && 'info-panel-content--open',
+    elementProps?.content?.className,
+  )}
+>
+  <p>{text}</p>
+</div>
+```
+
+```css
+.content { display: none; }
+.content:global(.info-panel-content--open) { display: block; }
+```
 
 ## Checklist
 
@@ -176,4 +230,7 @@ at any depth. Reach for a prop trigger only for a root-level boolean switch.
 - [ ] 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.
 - [ ] `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, and always renders its content.

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

@@ -9,12 +9,17 @@ generation rewrites
 For a new component, complete the scaffolded installation and layout fields.
 For an existing component, change only the sizing, installation, or manifest
 behavior requested by the user; preserve every other extension field.
+Use the current scaffold's field shape and the values below. Inspect installed
+`@wix/astro` or schema types only if a related typecheck or build error requires it.
+Normal component setup needs no `ELEMENT_TYPE` or `DATA_TYPE` lookup: the
+generated `editorElement` and props manifest supply those details.
 
 ## Contents
 
 - [Preserve the Extension Shape](#preserve-the-extension-shape)
 - [Choose Initial Height](#choose-initial-height)
 - [Choose Resize Direction](#choose-resize-direction)
+- [Values](#values)
 - [Checklist](#checklist)
 
 ## Preserve the Extension Shape
@@ -53,6 +58,12 @@ should fit content, use `content`.
 
 Allow an axis only when dragging it produces a meaningful result.
 
+For each allowed axis, implement what happens when content no longer fits.
+Content height must grow after wrapping or changing items. A bounded height
+needs a fitting layout or a deliberate accessible scroll region. Installation
+defaults alone do not prevent overflow after resizing. Do not rely on native
+container overflow controls for a custom component's internal DOM.
+
 | Value | Use when |
 | --- | --- |
 | `horizontalAndVertical` | Content meaningfully fills both axes; default for framed visuals and most layouts |
@@ -61,11 +72,25 @@ Allow an axis only when dragging it produces a meaningful result.
 | `aspectRatio` | Distortion would break the component's identity |
 | `none` | A parent fully owns size; do not use for a top-level component |
 
+## Values
+
+Every value the scaffold uses comes from `LAYOUT` in
+`@wix/react-component-schema`; do not search `node_modules` for them.
+
+| Field | Values |
+| --- | --- |
+| `layout.resizeDirection` (`LAYOUT.RESIZE_DIRECTION`) | `horizontal`, `vertical`, `horizontalAndVertical`, `aspectRatio`, `none` |
+| `layout.contentResizeDirection` (`LAYOUT.CONTENT_RESIZE_DIRECTION`) | `horizontal`, `vertical`, `horizontalAndVertical`, `none`: the axes along which content growth resizes the component |
+| `initialSize.{width,height}.sizingType` (`LAYOUT.SIZING_TYPE`) | `content`, `pixels`, `stretched` |
+| `installation.staticContainer` | `'HOMEPAGE'`, `'GLOBAL_PAGE'` |
+
 Edit the scaffolded `layout`, `installation`, and `resources` fields in place;
 do not reconstruct the extension from an example. For a new component, add
 `staticContainer: 'HOMEPAGE'`. For an existing component, preserve its current
 `staticContainer` value unless the request explicitly changes installation
 behavior.
+The scaffold's `installation` object accepts `staticContainer` next to
+`initialSize`; add the literal above without searching `@wix/astro` types.
 
 ## Checklist