@wix/agent-skills 1.19.0 → 1.19.2

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

@@ -1,13 +1,13 @@
 # Accessibility Implementation and Review
 
-Use this reference while authoring Editor React Component props and JSX and
-after every JSX edit.
+Use this reference while authoring Editor React Component props and JSX, then
+run the review command once the JSX is complete.
 
 ## Contents
 
 - [Implementation Contract](#implementation-contract)
 - [Review Scope](#review-scope)
-- [Automated Scanners](#automated-scanners)
+- [Automated Review](#automated-review)
 - [Finding Triage](#finding-triage)
 - [Manual Review](#manual-review)
 - [Pre-Fix Checks for Non-Interactive Controls](#pre-fix-checks-for-non-interactive-controls)
@@ -15,29 +15,42 @@ after every JSX edit.
 
 ## Implementation Contract
 
-### Route ARIA Through `a11y`
+### Own Accessibility per Part
 
-Do not add individual public props such as `ariaLabel`, `ariaDescribedBy`, or
-`role`. Use the platform `A11y` type and convert it at the semantic target.
+Use the platform `A11y` type instead of individual public props such as
+`ariaLabel`, `ariaDescribedBy`, or `role`. For each part:
+
+- Prefer a native element.
+- Keep roles, heading levels, keyboard and focus behavior, relationships, live
+  regions, and widget state in component code.
+- Read `a11y.ariaLabel` only when a control has no visible name.
+
+Every `a11y` field that reaches the DOM becomes an editor control. Read only the
+field the part needs and write it as its HTML attribute,
+`aria-label={a11y?.ariaLabel}`. Never spread the whole object.
 
 ```tsx
-import type { A11y, Direction } from '@wix/editor-react-types';
-import { convertA11yKeysToHtmlFormat } from '@wix/react-component-utils';
-
-export type TabsProps = {
-  id: string;
-  className?: string;
-  direction?: Direction;
-  a11y?: A11y;
+import type { A11y } from '@wix/editor-react-types';
+
+type ToggleProps = {
+  elementProps?: { toggle?: { className?: string; a11y?: A11y } };
 };
 
-<nav {...(a11y && convertA11yKeysToHtmlFormat(a11y))}>{tabs}</nav>;
+function Toggle({ elementProps }: ToggleProps) {
+  const { a11y: toggleA11y, ...toggleProps } = elementProps?.toggle ?? {};
+
+  return (
+    <button {...toggleProps} aria-label={toggleA11y?.ariaLabel ?? ARIA_LABELS.toggle}>
+      <ChevronIcon aria-hidden="true" />
+    </button>
+  );
+}
 ```
 
-Apply root accessibility to the elected root. If requirements assign
-accessibility to a named inner part, route it through that part's
-`elementProps.<name>.a11y` contract and convert it on the actual semantic
-element.
+Keep the root's typed `a11y?: A11y` prop even when it reads no field. Destructure
+`a11y` out of an `elementProps` entry before spreading the entry; a spread entry
+records the nested object as a whole. Image alt text comes from the `Image`
+type's `alt` field, not from `a11y`.
 
 ### Provide Accessible Names
 
@@ -53,6 +66,7 @@ Never hardcode an `aria-label` string directly in JSX.
 ```tsx
 // constants.ts
 export const ARIA_LABELS = {
+  toggle: 'Toggle details',
   playButton: 'Play animation',
   pauseButton: 'Pause animation',
 } as const;
@@ -80,36 +94,47 @@ including an icon plus visible text, usually do not need another ARIA label.
 
 ## Review Scope
 
-Run this review after creating or editing JSX.
+Run this review once the JSX is complete and again after each fix pass, at
+most two passes. Do not rerun after a clean result unless JSX changed.
 
-| Request | Scan and inspect |
+| Request | Pass to the command |
 | --- | --- |
-| Specific file | That file and rendered wrappers or shared components it imports |
-| A component name or "this component" | All hand-edited files in its component folder plus relevant shared imports |
-| Full audit | Every component under `src/extensions/site/components/` plus relevant shared imports |
+| Specific file | That file; its component folder is rendered |
+| A component name or "this component" | The component folder |
+| Full audit | `src/extensions/site/components/` |
 
-Exclude `*.generated.ts`; it is regenerated from JSX and CSS.
+`*.generated.ts` is regenerated from JSX and CSS and is never scanned.
 Imported shared components are inspection context, not automatic edit scope.
 Report a confirmed shared-component issue instead of changing a broadly reused
 primitive unless the requested fix requires that shared change and its impact is
 understood.
 
-## Automated Scanners
+## Automated Review
 
 `<SKILL_ROOT>` is the absolute directory containing the active `SKILL.md`. Run
-both commands from the consumer Wix package so dependencies resolve from that
-project. Pass `.tsx` or `.jsx` paths relative to the current directory.
+from the consumer Wix package so dependencies resolve from that project.
 
 ```bash
-node <SKILL_ROOT>/scripts/scan-a11y-eslint.cjs <file1> [file2] ...
-node <SKILL_ROOT>/scripts/scan-a11y-code.cjs <file1> [file2] ...
+node <SKILL_ROOT>/scripts/scan-a11y-review.cjs <component-dir | files...>
 ```
 
-Do not treat scanner startup failure as a clean result. The ESLint scanner
-reports JSX accessibility rules. The semantic scanner follows imports up to
-four levels and emits resolution evidence and confidence. Neither scanner
-covers every Editor React Component contract, so complete the manual review
-even when both return zero findings.
+One command, one report. It runs the jsx-a11y ESLint rules, a semantic scanner
+that follows imports and checks the per-part `a11y` contract, and a render
+audit: the component is rendered with `defaultProps` in Node (an SSR check),
+loaded into jsdom with its CSS Modules, and audited with axe-core.
+`component.preview.tsx` must render without falling back to the placeholder.
+
+The JSON report has `summary.line`, then `findings` grouped by rule with a
+count, locations or DOM target, the scanner message, and the axe help link,
+then `notChecked`. Exit `0` means every scanner ran and found nothing, `1`
+means findings, `2` means the review is inconclusive; never treat `2` as clean.
+Exit `2` with `render FAILED (missing-deps)` means `jsdom` or `axe-core` is not
+installed: install them (SKILL.md step 2) and rerun. Exit `2` with
+`render FAILED (loader)` means the audit could not load a module the component
+imports; that is a scanner limit, not a component defect. Change the import
+only if `tsc` also rejects it; otherwise stop and report the loader limit in the
+final summary as a check that could not run. Color contrast, target size, and
+keyboard behavior need a browser and remain manual.
 
 ## Finding Triage
 
@@ -154,42 +179,31 @@ evidence supports.
 
 ## Manual Review
 
-Verify all of the following after triaging scanner output.
-
-### Semantic Targeting
-
-- `a11y` is typed and converted on the correct semantic element.
-- Wrappers and polymorphic components preserve their documented semantics.
-- Configurable heading or tag choices reach the rendered element.
-- Extension overrides preserve generated accessibility fields.
-
-### Names and Visual Content
-
-- Icon-only controls have configurable or stable system-owned names.
-- Visually hidden text remains in the accessibility tree when needed.
-- Meaningful images and icons are named; decorative repetitions are hidden.
-- Accessibility strings are not hardcoded directly in JSX.
-
-### Hidden Content and Focus
-
-- Hidden or collapsed state agrees across visuals, focusability, and the
-  accessibility tree.
-- Invisible content cannot receive focus unless the interaction requires it.
-- Disabled and inert states behave consistently for keyboard and assistive
-  technology users.
-
-### Interaction and Structure
-
-- Interactive-looking elements use native semantics or complete role, focus,
-  and keyboard behavior.
-- `onClick` on a non-interactive tag is checked, including conditional spreads.
-- Nested interactive children and existing focus management are inspected
-  before semantics are added to a wrapper.
-- Lists, headings, landmarks, tabs, menus, dialogs, and breadcrumbs keep their
-  intended structure.
+In the default rendered state the command checks names, alt text, ARIA
+validity, nesting, list and heading structure, hidden-but-focusable content,
+the `a11y` contract, and SSR safety. Verify what it cannot see:
+
+- Every meaningful non-default state (expanded, selected, playing, error,
+  empty, hover/focus) keeps correct names, focusability, hidden state, and
+  structure; the command audits only the default render.
+- Wrappers and polymorphic components preserve their documented semantics;
+  extension overrides preserve generated accessibility fields.
+- Accessible names describe the action, and visually hidden text that carries
+  meaning stays in the accessibility tree.
+- State hidden through `--display` or transforms agrees with focusability and
+  the accessibility tree; disabled and inert states behave consistently.
+- Custom widgets (tabs, menus, dialogs, sliders) implement their full APG
+  keyboard pattern (arrow keys, Home/End, Escape, roving `tabIndex`) and
+  structural relationships, or use a plain native element instead of
+  borrowing the role.
+- Interactive controls have a hit area of at least 24×24 CSS px and visible
+  focus.
 - The root implements the direction contract, and every `ReactNode` slot
   isolates nested content with `dir="ltr"`.
 
+- An auto-rotating set of readable parallel items uses `aria-live="off"` while
+  it is rotating and `aria-live="polite"` while it is stopped.
+
 ## Pre-Fix Checks for Non-Interactive Controls
 
 Before adding `role="button"`, `tabIndex`, and keyboard handlers to a non-native
@@ -211,12 +225,13 @@ Prefer a native element when it preserves product behavior.
 
 The accessibility review is complete only when:
 
-- both scanners start successfully;
-- every finding is triaged;
-- confirmed issues are fixed when safe;
-- the manual review is complete; and
-- both scanners are rerun on every changed `.tsx` or `.jsx` file.
+- the last run exited `0` or `1`; exit `2` is acceptable only for a reported
+  `loader` limit;
+- every finding is triaged and confirmed issues are fixed when safe;
+- the command was rerun after the last fix pass; and
+- the manual review is complete.
 
+After two fix passes, stop and report the remaining findings with their triage.
 Preserve visual and runtime behavior. Fix the semantic owner: root, named inner
 part, shared primitive, or call site. Then return to the main workflow for the
 Wix build, manifest generation, TypeScript check, and relevant project tests.

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

@@ -9,10 +9,12 @@ Every such component must ship an on-stage **play/pause button**.
 
 - [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
@@ -41,12 +43,26 @@ implementation detail.
    existing playback prop names and add only the missing safety contract.
    Carousels, sliders, slideshows, and galleries **must** define `autoPlay`
    (default `true`).
-2. **Playback state** — `isPlaying` + `handlePause` / `handleResume`
+2. **Playback state** — play/pause toggle state, derived `isPlaying`, and
+   `handlePause` / `handleResume`
 3. **Play/pause button** — overlay `<button>` with inline SVG icon and CSS
    positioning; it must be a named part with `elementProps` wiring, a hover
    design state, and a standalone `:focus-visible` keyboard indicator
 4. **Modify `component.preview.tsx`** — suppress autoplay in editor design mode
-5. **Respect `prefers-reduced-motion`** — suppress autoplay when the OS requests reduced motion
+5. **Respect `prefers-reduced-motion`** — start paused when the OS requests reduced motion
+
+### Announce Manually Selected Parallel Content
+
+For carousel-like components that swap readable parallel items, make the item
+wrapper a live region:
+
+- Use `aria-live={isPlaying ? 'off' : 'polite'}` and `aria-atomic="false"`.
+- `isPlaying = isPlayOn && !isHovered && !isStoppedByFocus`. Reduced motion
+  starts paused; editor mode, `autoPlay={false}`, and pause set it false.
+  Keyboard focus remains stopped until the rotation control restarts; hover
+  pauses temporarily.
+- Previous/next changes items. Use root `onMouseEnter`/`onMouseLeave`;
+  leaving resumes unless focus has stopped rotation.
 
 ## 1. Define Props
 
@@ -83,36 +99,44 @@ support repeat behavior; do not add it only to match the example.
 
 ## 2. Manage Playback State
 
-Track play/pause state with `useState`. Initialize it from `autoPlay` and the OS reduced-motion preference — when the visitor has requested reduced motion, the animation starts paused:
+Track play/pause button state with `useState`. Initialize it from `autoPlay`
+and reduced motion; reduced motion starts paused, but a visitor can start it.
 
 ```tsx
 import { useReducedMotion } from '@wix/react-component-utils';
 
-// inside the component:
 const reducedMotion = useReducedMotion();
 
-const [isPlaying, setIsPlaying] = React.useState((autoPlay ?? true) && !reducedMotion);
-
-// when autoPlay prop changes, re-sync (but still respect reduced motion)
-React.useEffect(() => {
-  setIsPlaying((autoPlay ?? true) && !reducedMotion);
-}, [autoPlay]);
+const [isPlayOn, setIsPlayOn] = React.useState(() => (autoPlay ?? true) && !reducedMotion);
 
-// when reduced motion is enabled, suppress playback; never re-enable on its own
-// (visitor may have manually paused — don't restart against their will)
+const skipInitialAutoPlaySync = React.useRef(true);
 React.useEffect(() => {
-  if (reducedMotion) {
-    setIsPlaying(false);
+  if (skipInitialAutoPlaySync.current) {
+    skipInitialAutoPlaySync.current = false;
+    return;
   }
-}, [reducedMotion]);
+  setIsPlayOn(autoPlay ?? true);
+}, [autoPlay]);
 
-const handlePause = () => setIsPlaying(false);
-const handleResume = () => setIsPlaying(true);
+const handlePause = () => setIsPlayOn(false);
+const handleResume = () => setIsPlayOn(true);
 ```
 
-**`reducedMotion`** is `true` when the hook reports that reduced motion is enabled. When active, the animation starts paused — the visitor can still press the play button to start it manually. It is a runtime browser signal, not a manifest/data prop; never expose it as a component prop or in the manifest.
+`reducedMotion` is a runtime signal, not a manifest/data prop.
+
+Derive runtime playback from `isPlayOn` plus only needed conditions. Without
+another condition, use `const isPlaying = isPlayOn`. A carousel, slideshow,
+slider, or gallery also uses hover and focus-stop state:
+
+```tsx
+const isPlaying = isPlayOn && !isHovered && !isStoppedByFocus;
+```
 
-Pass `isPlaying` to the animation renderer and toggle between `handlePause` / `handleResume` on button click.
+Pass `isPlaying` to the renderer. The button uses `isPlayOn` and toggles
+between `handlePause` / `handleResume` on click. In a carousel-like component,
+focus entering anything except that button sets `isPlayOn` to `false` and
+`isStoppedByFocus` to `true`; `handleResume` sets `isPlayOn` to `true` and
+clears `isStoppedByFocus`.
 
 ## 3. Add the Play/Pause Button
 
@@ -177,12 +201,12 @@ Wire the named part completely:
     styles.playButton,
     elementProps?.playButton?.className,
   )}
-  onClick={isPlaying ? handlePause : handleResume}
+  onClick={isPlayOn ? handlePause : handleResume}
   aria-label={
-    isPlaying ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton
+    isPlayOn ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton
   }
 >
-  {isPlaying ? <PauseIcon /> : <PlayIcon />}
+  {isPlayOn ? <PauseIcon /> : <PlayIcon />}
 </button>
 ```
 

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

@@ -33,6 +33,10 @@ export type PlanCardProps = {
   heading?: string;
   plans?: Array<Plan>;
   onClick?: (event: React.MouseEvent) => void;
+  onMouseIn?: (event: React.MouseEvent) => void;
+  onMouseOut?: (event: React.MouseEvent) => void;
+  onFocus?: (event: React.FocusEvent) => void;
+  onBlur?: (event: React.FocusEvent) => void;
 
   elementProps?: {
     cta?: { className?: string; href?: string };
@@ -42,13 +46,13 @@ export type PlanCardProps = {
 
 Rules:
 
-- Route all ARIA attributes through `a11y`; do not add individual `ariaLabel`,
-  `role`, or similar props.
+- Follow `ACCESSIBILITY.md`. Expose only `ariaLabel`, for a control without a
+  visible name, through the typed `a11y` contract. Keep semantics and state in
+  code. Do not add one-off ARIA props or spread the whole object.
 - Expose only content and behavior that the site owner controls. Keep derived
   values internal.
-- Add only callbacks required by the component specification. Use supported SDK
-  event names and types for public callbacks; keep implementation-only handlers
-  internal.
+- 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.
 
 ## Numeric Range Constraints
@@ -175,7 +179,16 @@ export const defaultProps = {
 ### Wix Data Types
 
 Use `Image`, `Link`, `Video`, `Audio`, `VectorArt`, `RichText` from
-`@wix/editor-react-types`. See `node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts` for the full list.
+`@wix/editor-react-types`. Model authored media with the corresponding Wix
+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.
+
+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.
 
 ## Defaults and Resources
 
@@ -241,5 +254,6 @@ Do not extract tiny fragments merely to satisfy a line-count threshold.
 - [ ] Named inner parts have `elementProps` wiring; leaf components avoid exported `children`.
 - [ ] One-body-visible arrays use the active-item contract and render all bodies.
 - [ ] 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).
 - [ ] Resources are Wix-hosted, prop-supplied, or locally bundled.

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

@@ -195,6 +195,12 @@ and do not expose a visual prop solely for that purpose.
 }
 ```
 
+The same override risk applies to paintable properties. A layout-only inner
+wrapper must stay visually transparent; if it isn't, promote it to its own
+named part instead of hardcoding an opaque style on an unexposed node, since
+that style would otherwise mask the parent part's own
+`background`/`border`/`box-shadow`.
+
 ## Interaction and Motion
 
 - Set `pointer-events: auto` on the root and each interactive element.
@@ -254,3 +260,6 @@ contract; the contrast relationship is.
 - [ ] 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 inside a named part paints its own opaque
+      `background`/`border`/`box-shadow`; a wrapper needing its own surface is
+      promoted to a named part instead.

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

@@ -1,57 +1,92 @@
 # Function Handlers
 
-Use this reference only when the component specification exposes callbacks to
-site owners. Keep implementation-only handlers out of the public props type.
+When creating a component or changing interactions, expose common optional
+callbacks by capability, without requiring an explicit request.
+
+## Default Support
+
+Apply defaults to the public interaction surface:
+
+| Component capability | Default optional props |
+| --- | --- |
+| Pointer/click interaction, including native controls | `onClick`, `onMouseIn`, `onMouseOut` |
+| Focusable control | `onFocus`, `onBlur` |
+| Editable value, text, or selection | `onChange` |
+
+Combine matching rows; leave decorative elements alone. Explicit API restrictions
+override defaults. Specialized callbacks (`onDblClick`, `onPlay`, `onEnded`,
+`onActivate`, etc.) require a request.
+
+Classify composite controls by their interactive descendants. For example, a
+radio-based rating input matches all three rows and exposes all six callbacks.
 
 ## Standard SDK Handlers
 
 Use the exact SDK prop name and wire it to the matching React DOM event.
 
-| SDK prop | React DOM prop | Type |
-| --- | --- | --- |
-| `onClick` | `onClick` | `(event: React.MouseEvent) => void` |
-| `onDblClick` | `onDoubleClick` | `(event: React.MouseEvent) => void` |
-| `onChange` | `onChange` | `(event: React.ChangeEvent<HTMLElement>) => void` |
-| `onFocus` | `onFocus` | `(event: React.FocusEvent) => void` |
-| `onBlur` | `onBlur` | `(event: React.FocusEvent) => void` |
-| `onMouseIn` | `onMouseEnter` | `(event: React.MouseEvent) => void` |
-| `onMouseOut` | `onMouseLeave` | `(event: React.MouseEvent) => void` |
-
-Declare only the handlers the component actually exposes.
+| SDK prop | React DOM prop | Type | Zero config `domEvent` |
+| --- | --- | --- | --- |
+| `onClick` | `onClick` | `(event: React.MouseEvent) => void` | `POINTER` |
+| `onDblClick` | `onDoubleClick` | `(event: React.MouseEvent) => void` | `POINTER` |
+| `onChange` | `onChange` | `(event: React.ChangeEvent<HTMLElement>) => void` | `CHANGE` |
+| `onFocus` | `onFocus` | `(event: React.FocusEvent) => void` | `FOCUS` |
+| `onBlur` | `onBlur` | `(event: React.FocusEvent) => void` | `FOCUS` |
+| `onMouseIn` | `onMouseEnter` | `(event: React.MouseEvent) => void` | `POINTER` |
+| `onMouseOut` | `onMouseLeave` | `(event: React.MouseEvent) => void` | `POINTER` |
+
+React `onChange` fires on live text edits and selection changes. Pass that
+`ChangeEvent` directly. Do not synthesize a commit callback from blur or cast a
+`FocusEvent` to `ChangeEvent`.
+
+Callbacks only notify; they never enable controlled mode. Internal handlers run
+component logic, then call the optional callback once, preserving event payloads
+and disabled/read-only guards. Behavior must work without callbacks or consumer
+prop updates. Forward directly when no internal logic is needed. Add controlled
+state only when requested; preserve existing controlled APIs when editing.
 
 ```tsx
+import * as React from 'react';
+
 export type ActionProps = {
   onClick?: (event: React.MouseEvent) => void;
-  onDblClick?: (event: React.MouseEvent) => void;
   onMouseIn?: (event: React.MouseEvent) => void;
   onMouseOut?: (event: React.MouseEvent) => void;
+  onFocus?: (event: React.FocusEvent) => void;
+  onBlur?: (event: React.FocusEvent) => void;
 };
 
 export const Action: React.FC<ActionProps> = (props) => {
-  const { onClick, onDblClick, onMouseIn, onMouseOut } = props;
+  const { onClick, onMouseIn, onMouseOut, onFocus, onBlur } = props;
+  const [count, setCount] = React.useState(0);
+
+  const handleClick = (event: React.MouseEvent) => {
+    setCount((value) => value + 1);
+    onClick?.(event);
+  };
 
   return (
     <button
       type="button"
-      onClick={onClick}
-      onDoubleClick={onDblClick}
+      onClick={handleClick}
       onMouseEnter={onMouseIn}
       onMouseLeave={onMouseOut}
-    />
+      onFocus={onFocus}
+      onBlur={onBlur}
+    >
+      Clicked {count} times
+    </button>
   );
 };
 ```
 
-Do not expose DOM names such as `onDoubleClick`, `onMouseEnter`, or
-`onMouseLeave` in the component API; zero config recognizes the SDK names.
+Zero config requires SDK names, not `onDoubleClick`, `onMouseEnter`, or
+`onMouseLeave`, in public props.
 
 ## Custom Callbacks
 
-A component-level notification that is not one of the standard SDK DOM events
-uses `() => void` unless the component contract explicitly defines a serializable
-payload. Do not expose a React synthetic event for custom callbacks.
-
-Use this pattern:
+Custom notifications use `() => void`; zero config emits no event parameter for
+unrecognized callback names. Custom callbacks must not declare React event
+parameters. Use a standard SDK handler above when the event is public:
 
 ```tsx
 export type VideoPlayerProps = {
@@ -62,14 +97,19 @@ export type VideoPlayerProps = {
 
 export const VideoPlayer: React.FC<VideoPlayerProps> = (props) => {
   const { onPlay, onPause, onEnded } = props;
-  return <video onPlay={onPlay} onPause={onPause} onEnded={onEnded} />;
+  return (
+    <video
+      controls
+      onPlay={() => onPlay?.()}
+      onPause={() => onPause?.()}
+      onEnded={() => onEnded?.()}
+    />
+  );
 };
 ```
 
 ## Checklist
 
-- [ ] The specification explicitly requires each public callback.
-- [ ] Standard handler names match the SDK contract exactly.
-- [ ] Mismatched SDK/DOM names are mapped at the rendered element.
-- [ ] Custom callbacks do not leak React event objects.
-- [ ] Internal handlers remain implementation details.
+- [ ] Defaults match capabilities; specialized callbacks are requested.
+- [ ] SDK names, DOM mappings, and payloads match the contract.
+- [ ] Internal behavior works independently and notifies callbacks once.

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

@@ -24,14 +24,17 @@ would plausibly control independently in the editor. It receives:
 
 - one prefixed global class: `'<component-name>-<part-name>'`
 - one CSS Module class
-- one matching `elementProps` entry, spread onto the element
+- one matching `elementProps` entry, spread onto the element. Declare `a11y` on
+  the entry only when the part reads `ariaLabel`, and destructure it out before
+  spreading (see `ACCESSIBILITY.md`)
 
 Apply this filter to every candidate:
 
 - A state or variant (`selected`, `active`, `open`, `disabled`) is not a part.
   Implement it as a prefixed design-state modifier on the affected part.
 - A hidden and shown version of the same element is one part, not two.
-- A grouping or layout-only wrapper is not a part.
+- A grouping or layout-only wrapper is not a part. A wrapper that isn't
+  visually transparent is no longer layout-only — promote it to a named part.
 - A static child whose styling and data are fully owned by its parent is not a
   part. For example, an image whose source and appearance both belong to its
   carousel slide can remain module-class-only.

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

@@ -12,8 +12,7 @@ contracts changed by the request:
 2. Separate user-authored content and stable behavior from derived values and
    visual styling.
 3. Identify interaction and selectable states affected by the request.
-4. Keep implementation behavior internal unless the component specification
-   requests a public callback.
+4. Include common callbacks by capability; keep implementation handlers internal.
 5. Identify runtime concerns such as browser APIs, autoplay, editor-only
    behavior, or live site context before implementation.
 
@@ -49,8 +48,8 @@ export const ProfileCard: React.FC<ProfileCardProps> = (props) => {
 - When local state intentionally mirrors a prop, synchronize it when that prop
   changes. Do not use effect-managed state for a value that can be derived
   during render.
-- Keep implementation-only handlers internal. Expose a callback only when the
-  specification makes it part of the component API.
+- Internal handlers run component behavior, then notify optional callbacks.
+  Callback presence never enables controlled mode.
 
 ### Structure and Parts
 
@@ -86,4 +85,4 @@ export const ProfileCard: React.FC<ProfileCardProps> = (props) => {
 - [ ] Direction and accessibility contracts are wired to the correct elements.
 - [ ] Public handlers use supported SDK names; internal handlers stay internal.
 - [ ] CSS changed by the request keeps editable selectors flat and scoped.
-- [ ] The accessibility review runs after JSX edits.
+- [ ] The accessibility review command passes, or its remaining findings are triaged.