@wix/agent-skills 1.15.1 → 1.16.0

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

@@ -0,0 +1,138 @@
+# Editor React Component A11y Review
+
+Use this reference to audit and fix accessibility issues in an Editor React Component. This complements [`ACCESSIBILITY.md`](ACCESSIBILITY.md), which covers ARIA prop conventions and patterns, with an automated scan and triage workflow over the component's runtime, manifest extension, and shared code.
+
+This is not a separate skill. It runs as part of the Editor React Component workflow described in [`../SKILL.md`](../SKILL.md). Run it after editing the React/CSS sources and before `npx wix build && npx wix generate manifest`.
+
+## Scanner Invocation
+
+Two scanners live at the Editor React Component skill root:
+
+```bash
+node scripts/scan-a11y-eslint.cjs <file1> [file2] ...
+node scripts/scan-a11y-code.cjs  <file1> [file2] ...
+```
+
+Run them from the consumer project root (the Wix CLI app's working directory) so dependencies resolve from the project's `package.json`. Pass paths relative to that cwd. The dependency preflight is part of the workflow in [`../SKILL.md`](../SKILL.md).
+
+The ESLint scanner uses the explicitly declared `eslint-plugin-jsx-a11y` dev dependency. The semantic scanner follows imports up to four levels deep and adds resolution evidence and confidence to its findings.
+
+## When To Run
+
+Run the review when:
+
+- You finished editing an Editor React Component's `.tsx` / `.module.css` files.
+- The user asks for an a11y audit, accessibility review, or a11y fix on an Editor React Component.
+- The user mentions missing alt text, invalid ARIA, broken semantics, direction issues, icon-only controls, or wrappers that hide accessibility issues.
+
+Do not run on generated files (`*.generated.ts`); they are regenerated from JSX and CSS Modules.
+
+## Target Resolution
+
+Resolve scope before scanning:
+
+| User says | Required scope |
+|-----------|----------------|
+| Specific file | That file plus any imported wrappers / shared components it renders |
+| "this component" | `<componentName>.tsx`, `component.tsx`, `<componentName>.extension.ts`, plus shared imports |
+| A component name | All in-component files (excluding `*.generated.ts`) |
+| "full audit" | Every Editor React Component folder under `src/extensions/site/components/`, excluding `*.generated.ts` |
+
+## Workflow
+
+Execute every phase inline while editing. Do not pause for approval or add a separate summary phase.
+
+### Phase 1: Resolve Topology
+
+1. Enumerate in-scope files under `src/extensions/site/components/<componentName>/`.
+2. Include imported shared components or utilities that affect rendered semantics.
+3. Exclude `*.generated.ts`.
+4. Trace the topology from the component through wrappers and shared primitives to the rendered element.
+
+### Phase 2a: ESLint JSX A11y Scan (Tier 0)
+
+```bash
+node scripts/scan-a11y-eslint.cjs <file1> [file2] ...
+```
+
+Use each finding's rule ID, message, and location as the rule-specific context. Validate the finding against the component implementation before editing.
+
+### Phase 2b: Semantic Scan (Tier 1)
+
+```bash
+node scripts/scan-a11y-code.cjs <file1> [file2] ...
+```
+
+Use the emitted resolution path, evidence, and confidence to trace each finding. The scanner output is the source of rule-specific details; the reference only defines how to evaluate and act on those details.
+
+Neither scanner validates manifest contracts or all Editor React Component patterns. Complete Phase 3 even when both scanners return zero findings.
+
+### Deduplication and Triage
+
+Evaluate every finding before fixing it.
+
+**Deduplicate.** When both scanners flag the same location for the same issue, keep the finding with richer evidence. Prefer the semantic scanner when it resolved the component topology; prefer ESLint when the issue is outside the semantic scanner's scope.
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| `confirmed` | The violation is real | Fix it |
+| `false-positive` | The rule fires but the rendered behavior is correct | Discard it |
+| `not-relevant` | The rule does not apply to this architecture | Discard it |
+
+Use this order to evaluate a finding:
+
+1. Trace the component implementation and confirm that the flagged behavior reaches the rendered element.
+2. Check delegated semantics. Editor React Components route ARIA through the typed `a11y` prop and `convertA11yKeysToHtmlFormat(a11y)` (see [`ACCESSIBILITY.md`](ACCESSIBILITY.md)). If the attributes reach the correct element through a runtime path the scanner cannot see, discard the finding as a false positive.
+3. Check conditional interactivity. When `onClick` is spread conditionally with `role`, `tabIndex`, and `onKeyDown`, discard the finding as a false positive. If only `onClick` is conditional, confirm it.
+4. Apply the semantic checks in [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#tier-2-manual-review-checklist).
+5. When uncertain, continue tracing the implementation. Default to `confirmed` only after checking the available code and evidence.
+
+Only confirmed findings proceed to edits.
+
+### Phase 3: Editor React Component Semantic Review
+
+Perform a manual semantic review even when scanners return zero findings.
+
+- All ARIA attributes come through the typed `a11y?: A11y` prop, never individual `ariaLabel?: string`, `role?: string`, and similar props. See [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
+- `a11y` is forwarded to the root via `{...(a11y && convertA11yKeysToHtmlFormat(a11y))}`, or to an inner element via `elementProps.<name>.a11y` when requirements specify.
+- Icon-only interactive elements (icon/emoji/image/svg with no text node) have an accessible name from `constants.ts` or user-configurable `a11y`, never a hardcoded string literal.
+- Direction support is mandatory: props include `direction?: Direction`, the root applies `dir={direction}` and the unconditional `fallbackDirection` class, and CSS defines `.fallbackDirection:not([dir])`. See [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
+- Every `ReactNode` content prop is rendered inside an element with `dir="ltr"` so user-provided nested content does not inherit the component direction.
+- `<componentName>.extension.ts` overrides do not strip a11y-relevant manifest fields generated from the JSX.
+- Decorative-only output is hidden with `aria-hidden` when appropriate.
+- Heading/tag selection, when configurable, reaches the rendered semantic element.
+- Interactive-looking elements expose the required keyboard behavior and roles.
+
+Use the full Tier 2 checklist in [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#tier-2-manual-review-checklist).
+
+### Phase 4: Fix
+
+Apply fixes only to findings that survived triage:
+
+- `high`: fix immediately
+- `medium`: read the surrounding code, confirm, then fix
+- `low`: resolve the semantics from code and evidence; fix only when confirmed
+
+Confirmed safe/local fixes must be applied. Leave code unchanged only when the semantics remain ambiguous or the fix requires a risky, non-local behavior change. See [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md#confidence-model).
+
+Fix principles:
+
+- Preserve intended visual and runtime behavior.
+- Fix the real semantic owner: component root, inner element via `elementProps`, or shared base.
+- Follow established Editor React Component patterns: route ARIA through `a11y`, use `constants.ts` for required labels, and never hardcode string literals.
+- Before adding `role`, `tabIndex`, or keyboard handlers to a non-interactive element, run the [pre-fix checks](A11Y-REVIEW-REFERENCE.md#pre-fix-checks-for-adding-button-semantics-to-a-non-interactive-element).
+
+### Phase 5: Verify
+
+If any `.tsx` / `.jsx` file was edited:
+
+1. Re-run both scanners on the modified files.
+2. Run `npx wix build && npx wix generate manifest` so the manifest reflects any JSX changes.
+3. Run the project's TypeScript check (`npx tsc --noEmit`), which is already part of the wix-app validation flow.
+
+Verification is mandatory after edits. Continue directly from fixes to verification, and do not consider the workflow complete while a required check remains unrun.
+
+## References
+
+- [`A11Y-REVIEW-REFERENCE.md`](A11Y-REVIEW-REFERENCE.md) - triage, confidence, semantic resolution, Tier 2 checks, and pre-fix safeguards
+- [`ACCESSIBILITY.md`](ACCESSIBILITY.md) - ARIA conventions for Editor React Components

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

@@ -34,6 +34,7 @@ implementation detail.
 2. **Playback state** — `isPlaying` + `handlePause` / `handleResume`
 3. **Play/pause button** — overlay `<button>` with inline SVG icon + CSS positioning and optional hover-only visibility
 4. **Modify `component.preview.tsx`** — suppress autoplay in editor design mode
+5. **Respect `prefers-reduced-motion`** — suppress autoplay when the OS requests reduced motion
 
 ---
 
@@ -65,15 +66,35 @@ export interface MyAnimationProps {
 
 ## 2. Playback state
 
-Track play/pause state with `useState`, initialized from the `autoPlay` prop:
+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:
 
 ```tsx
-const [isPlaying, setIsPlaying] = React.useState(autoPlay ?? true);
+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]);
+
+// when reduced motion is enabled, suppress playback; never re-enable on its own
+// (visitor may have manually paused — don't restart against their will)
+React.useEffect(() => {
+  if (reducedMotion) {
+    setIsPlaying(false);
+  }
+}, [reducedMotion]);
 
 const handlePause = () => setIsPlaying(false);
 const handleResume = () => setIsPlaying(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.
+
 Pass `isPlaying` to the animation renderer and toggle between `handlePause` / `handleResume` on button click.
 
 ---

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

@@ -0,0 +1,29 @@
+# Branded / Themed Components
+
+Apply automatically — without being asked — whenever the user requests a
+**branded**, **themed**, or **brand-aware** component.
+
+---
+
+Import theme tokens from `@wix/react-component-schema/theme-variables.module.css`
+using CSS Modules `@value`, then consume with `var()`.
+
+```css
+@value wst-primary-background-color from "@wix/react-component-schema/theme-variables.module.css";
+@value wst-heading-3-font, wst-heading-3-color from "@wix/react-component-schema/theme-variables.module.css";
+@value wst-paragraph-1-font, wst-paragraph-1-color from "@wix/react-component-schema/theme-variables.module.css";
+
+.root    { background: var(wst-primary-background-color); }
+.heading { font: var(wst-heading-3-font); color: var(wst-heading-3-color); }
+.body    { font: var(wst-paragraph-1-font); color: var(wst-paragraph-1-color); }
+```
+
+**Colors:** `wst-primary-background-color`, `wst-secondary-background-color`, `wst-base-1-color`, `wst-base-2-color`, `wst-shade-1/2/3-color`, `wst-accent-1/2/3/4-color`, `wst-links-and-actions-color`
+
+**Headings:** `wst-heading-1..6-font` / `wst-heading-1..6-color`
+
+**Body:** `wst-paragraph-1..3-font` / `wst-paragraph-1..3-color`
+
+❌ Don't use `var(--wst-*)` directly — import the `@value` alias first.  
+❌ Don't use `@import` — CSS Modules doesn't process `@value` aliases from `@import`; `@value` is the only mechanism that resolves them at build time.  
+❌ Don't use `wst-base-1-color` for text — it typically resolves to white and is invisible on the default white background. Use `wst-heading-*-color` / `wst-paragraph-*-color` for text, or `wst-base-2-color` if you need a base contrast color.  

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

@@ -102,7 +102,7 @@ exists because the element is a named part.
 
 ### What Qualifies as a Part
 
-See [`PARTS.md`](PARTS.md) for the mandatory filter and full rules.
+See [`PARTS.md`](PARTS.md) for root election (Step 0), the mandatory filter, and full rules. The root gets no `elementProps` entry — its `className`, `a11y`, and `direction` arrive as top-level props.
 
 ### Derived values are not props
 

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

@@ -19,7 +19,7 @@ There are two kinds of classes, determined by whether the element is a named par
 | Named part | `classNames('profile-card-heading', styles.heading)` | Global string → zeroConfig creates an editor element; module class → applies the component's own CSS |
 | Non-part (layout/structural) | `styles.contentWrapper` | Module class only — invisible to zeroConfig, no spurious editor element created |
 
-**Named parts** get both a global plain string and a module class. The global string is what zeroConfig scans: use `'<component-name>'` for the root and **`'<component-name>-<part-name>'` for every inner part** (kebab-case) — always prefix inner parts with the component name. The module class is what carries the component's structural CSS for that element; it stays short (`styles.heading`) because module classes are hashed and scoped, so they never need the prefix.
+**Named parts** get both a global plain string and a module class. The global string is what zeroConfig scans: use `'<component-name>'` for the root and **`'<component-name>-<part-name>'` for every inner part** (kebab-case) — always prefix inner parts with the component name. The root here is the element elected per [`PARTS.md`](PARTS.md) Step 0, which is the component's own semantic element (`<button>`, `<a>`, `<ul>`) when the component reduces to one. The module class is what carries the component's structural CSS for that element; it stays short (`styles.heading`) because module classes are hashed and scoped, so they never need the prefix.
 
 **Why prefix inner parts:** the global string is a literal class that ends up on the live page, and its design-state variants are derived from it (`<component-name>-<part>--<state>`, e.g. `profile-card-cta--hover`). Those state classes are applied at runtime as global literals, so they must be unique across every component that can share a page — a bare `cta--hover` would collide between two different components. Prefixing with the component name guarantees uniqueness.
 
@@ -27,18 +27,24 @@ There are two kinds of classes, determined by whether the element is a named par
 
 The root also merges the consumer-provided `className` prop via the `classnames` helper.
 
-**Why:** zeroConfig creates one editor element per global class. A global class on a non-part produces a spurious editor element with no meaningful surface.
+**Why:** zeroConfig creates one editor element per global class. A global class on a non-part produces a spurious editor element with no meaningful surface. The root's global class is unavoidable, which is why the root must be an element that deserves it.
 
 ```tsx
 import classNames from 'classnames';
 import styles from './ProfileCard.module.css';
 
 // ✅ Root: global string + module class + consumer className
+// (a <div> here only because this component lays out several sibling parts)
 <div className={classNames(className, 'profile-card', styles.root)} id={id}>
 
   {/* ✅ Named part: prefixed global string + short module class */}
   <h2 className={classNames('profile-card-heading', styles.heading)}>{heading}</h2>
 
+  {/* ✅ Named part: interactive elements always get both classes */}
+  <button type="button" className={classNames('profile-card-cta', styles.cta)}>
+    {ctaLabel}
+  </button>
+
   {/* ✅ Non-part layout wrapper: module class only */}
   <div className={styles.contentWrapper}>
     <span className={classNames('profile-card-label', styles.label)}>{label}</span>
@@ -51,6 +57,25 @@ import styles from './ProfileCard.module.css';
 </CardHeader>
 ```
 
+A component that reduces to one control is the other shape, and it has exactly one
+part — its root ([`PARTS.md`](PARTS.md) Step 0). The text it renders and any decoration
+stay inside that root, on module classes:
+
+```tsx
+// ✅ The <button> is the root: unprefixed global string, no elementProps entry
+<button
+  type="button"
+  id={id}
+  dir={direction}
+  className={classNames('like-button', styles.root, className, styles.fallbackDirection)}
+>
+  {label}
+
+  {/* ✅ Decoration: module class only, out of the a11y tree, not a part */}
+  <span className={styles.burst} aria-hidden="true" />
+</button>
+```
+
 ### Use single-class selectors
 
 Every selector is exactly one class, written as a flat top-level

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

@@ -31,7 +31,9 @@ nested (`card__row--selected`).
 Put the resting value in the bare class; put only the state override in the
 state selector.
 
-- **Native** — pair the pseudo-class with the `:global` modifier.
+- **Native** — pair the pseudo-class with the `:global` modifier. Every native
+  state needs both selectors in the same rule; do not split the pair across
+  states (for example, pseudo-only `hover` plus global-only `disabled`).
 - **Custom** — the `:global` modifier alone.
 
 The bare selector is the short **module** class (`.cta`); the `:global(...)`
@@ -45,7 +47,8 @@ state class is the **prefixed** global one.
 .cta:hover {
   background: #4f46e5;
 }
-.cta:global(.pricing-card-cta--disabled) {
+.cta:global(.pricing-card-cta--disabled),
+.cta:disabled {
   opacity: 0.5;
 }
 .plan-row:global(.pricing-card-plan-row--selected) {
@@ -124,4 +127,3 @@ 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.
-

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

@@ -42,12 +42,29 @@ Use logical CSS properties — never physical `left`/`right`-only layouts. See
 
 ### Root Element Pattern
 
-Apply on main component only:
+Apply on main component only. `dir` and the fallback class go on whatever element is the root — never add a wrapper `<div>` to host them (see [`PARTS.md`](PARTS.md) Step 0).
 
 ```typescript
 <div
+  id={id}
   dir={direction}
   className={classNames(
+    'profile-card',
+    styles.root,
+    className,
+    styles.fallbackDirection,
+  )}
+>
+```
+
+```typescript
+/* Root is the component's own semantic element — same attribute, same classes */
+<button
+  type="button"
+  id={id}
+  dir={direction}
+  className={classNames(
+    'like-button',
     styles.root,
     className,
     styles.fallbackDirection,

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

@@ -1,5 +1,16 @@
 # What Qualifies as a Part
 
+## Step 0 — Elect the root element
+
+The root always becomes the component's editor element: it carries the `'<component-name>'` global class and gets a name and design capabilities either way. So elect a root that deserves them, before enumerating inner parts.
+
+- ✅ **The component reduces to one meaningful element** (a single control, link, media surface, or list) — that element **is** the root. It takes `id`, `dir`, the `fallbackDirection` class, the merged `className`, the `a11y` spread, `'<component-name>'`, and the root CSS rule. All of these are attributes and classes, so they sit on a `<button>` or `<a>` exactly as on a `<div>` — needing them is never a reason to add a wrapper.
+- ✅ **The elected root is the root, not an inner part** — it carries the **unprefixed** `'<component-name>'` class and gets no `elementProps` entry. A single-control component therefore has exactly one named part: its root.
+- ❌ **Wrapper `<div>` holding only root plumbing** — the editor element is then a transparent box and the real element is demoted to a nested part. A root wrapper is justified only when it lays out two or more sibling parts, is the sizing/scroll/clipping container, or hosts a root-level prop-triggered state ([`DESIGN-STATES.md`](DESIGN-STATES.md) §5). Anchoring absolutely positioned decoration is not a justification — `position: relative` works on any element.
+- **Stutter test** — a part class repeating the component's own noun (`confetti-button-button`) means the wrapper took the root's name. Collapse it and promote the real element.
+
+## Inner parts
+
 A **named part** is an element that a site owner would plausibly want to control independently in the editor. Zero config scans global class names and creates an editor element for each one. Each editor element can surface:
 
 - **CSS properties** — styling controls (fill, typography, border, etc.)
@@ -12,7 +23,7 @@ An element deserves its own named part if a site owner would plausibly need to i
 - ❌ **State or variant** (`active`, `selected`, `current`, `disabled`, `open`, `checked`) — not a part, it's a **design state** of a part. Implement it per [`DESIGN-STATES.md`](DESIGN-STATES.md): native states from interactive markup; custom states as a flat global modifier on the element's own (component-name-prefixed) class (e.g. `carousel-slide--active`, toggled in JSX) plus a `:global(.carousel-slide--active)` CSS rule. The modifier is a state, not a named part.
 - ❌ **Hidden/shown state of an existing part** — the hidden and shown states of a part are not separate parts. The element itself should be a named part (so the editor can control its visibility per breakpoint); creating an additional part to represent its hidden or shown variant is wrong.
 - ❌ **Pure grouping wrapper** — not a part. A `<div>` whose only role is to hold already-named siblings has no independent editor surface; let layout live in the parent's CSS.
-- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs.
+- ❌ **Child with no independent editor surface** — not a part if its styling and data are already fully owned by the parent. This applies regardless of how many siblings it has. Two ways a child's editor surface can already be covered by the parent: (1) its CSS properties are inherited or set via the parent's rule; (2) its data is defined on the parent. **Canonical example:** an `<img>` inside a carousel slide whose `src` and `alt` come from the parent slide's data, and whose visual properties (object-fit, border-radius) could equally be set on the slide's own CSS rule — the slide already owns both data and styling, so the `<img>` is not a named part. Use a CSS module class for any structural CSS it needs. **Exception — interactive HTML elements (`<button>`, `<a>`, `<input>`) are never excluded by this criterion.** They always carry an independent styling surface: background, border, border-radius, hover/focus states, color, and typography are all meaningfully tunable per element in the editor. Apply this exclusion only to purely static structural elements (layout wrappers, grouping containers, decorative dividers). This makes an interactive element a named part **when it is an inner element** — if it is the elected root (Step 0), it is already named by `'<component-name>'` and must not be given a prefixed inner-part class as well.
 - ❌ **Positional duplicate** — not separate parts. Elements that are semantically identical and differ only in position (e.g. prev/next buttons) are one part; differentiate position with CSS (`:first-of-type` / `:last-of-type`, `data-` attribute, or `:nth-child`).
 - ✅ **Passes all checks** — a named part. Classify as **Semantic** (needs `elementProps`: data, behavior, direction, event handlers) or **Styling-only** (CSS class is sufficient).
 
@@ -22,5 +33,7 @@ Before finalising, verify each proposed part against its parent:
 
 > Would the editor controls generated for this part be a strict subset of its parent's controls?
 
-If yes — the part adds no independent editor surface and should be removed. This catches rationalisation after-the-fact ("the parent *could* expose this CSS property too, but so could the child separately"). When in doubt, fewer parts is usully better.
+If yes — the part adds no independent editor surface and should be removed. This catches rationalisation after-the-fact ("the parent *could* expose this CSS property too, but so could the child separately"). When in doubt, fewer parts is usually better.
+
+Then run the same question in reverse, on the root: if the root has exactly one child part and no editor surface of its own, it is a plumbing wrapper — delete it and promote the child per Step 0.
 

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

@@ -10,7 +10,6 @@ This guide defines rules and guidance on **how to implement** production-quality
 - [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — What should be a React prop vs CSS
 - [`COMPONENT-API.md`](COMPONENT-API.md) — Props structure, elementProps, data types, file splitting, containers, array props
 - [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) — Play/pause control and autoplay for animated/playable components
-- [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) — `component.preview.tsx` patterns and `useIsEditMode()` usage
 - [`REACT-PATTERNS.md`](REACT-PATTERNS.md) — SSR-safe patterns, CSS rules, common mistakes
 
 ## React 18 features are not supported
@@ -24,7 +23,7 @@ React 18 features.
 Understand the component and infer its behavior. Extract what is provided; use reasonable defaults for anything not specified.
 
 1. **Identity** — Component name.
-2. **Structure** — Identify named parts by applying the mandatory filter in [`PARTS.md`](PARTS.md) to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
+2. **Structure** — Elect the root element per [`PARTS.md`](PARTS.md) Step 0, then identify named inner parts by applying the mandatory filter in [`PARTS.md`](PARTS.md) to every candidate element before accepting it as a part. Include content/data props (labels, items, types, required vs optional) and configuration (toggles, choices, ranges, modes).
 3. **Interactions** — Clicks, hover/focus; what is exposed as event props vs handled internally. If the component's primary content is a **playable animation** (Lottie/JSON, animated GIF/SVG, canvas/WebGL loop, video-like surface), it gets a play/pause control — follow [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md).
 4. **States** — For every part, decide which design states it supports (native: `hover`/`focus`/`disabled`/`invalid`; custom: `selected`/`active`/`open`/… ) by applying the heuristic in [`DESIGN-STATES.md`](DESIGN-STATES.md), and record them in the plan. These become the editor's per-element state styling controls.
 
@@ -170,5 +169,5 @@ See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and [`COMPONENT-API.md`](COMPONENT-API.
 
 **Phase 2: Component File** — Apply all §1.1 mandatory features and §1.2 implementation standards; toggle custom-state classes from data ([`DESIGN-STATES.md`](DESIGN-STATES.md))
 
-**Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md))
+**Phase 3: Styles** — Apply Part 2 SCSS rules, including state styles ([`DESIGN-STATES.md`](DESIGN-STATES.md)). If the request uses the words **branded**, **themed**, or **brand-aware**, also apply [`BRANDED-COMPONENTS.md`](BRANDED-COMPONENTS.md) before writing CSS.
 

package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md

@@ -31,27 +31,31 @@ This example sorts staff members to balance workload by prioritizing those with
 ```typescript
 import { staffSorting } from "@wix/bookings/service-plugins";
 import { auth } from "@wix/essentials";
-import { bookings } from "@wix/bookings";
+import { extendedBookings } from "@wix/bookings";
 
 staffSorting.provideHandlers({
   sortStaffMembers: async (payload) => {
     const { request } = payload;
     const { availableResourceIds, slot } = request;
 
-    // Query recent bookings for each available staff member
-    const elevatedQuery = auth.elevate(bookings.queryBookings);
-    const recentBookings = await elevatedQuery()
-      .eq("resource.id", availableResourceIds)
-      .ge("start.timestamp", new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString())
-      .find();
+    const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const elevatedQuery = auth.elevate(extendedBookings.query);
+    const result = await elevatedQuery({
+      filter: {
+        "bookedEntity.item.slot.resource.id": { "$in": availableResourceIds },
+        "startDate": { "$gte": sevenDaysAgo },
+      },
+      cursorPaging: { limit: 100 },
+    });
+    const recentBookings = result.extendedBookings ?? [];
 
     // Count bookings per staff member
     const bookingCounts = new Map<string, number>();
     for (const id of availableResourceIds) {
       bookingCounts.set(id, 0);
     }
-    for (const booking of recentBookings.items) {
-      const resourceId = booking.resource?.id;
+    for (const booking of recentBookings) {
+      const resourceId = booking.booking?.bookedEntity?.slot?.resource?._id;
       if (resourceId && bookingCounts.has(resourceId)) {
         bookingCounts.set(resourceId, (bookingCounts.get(resourceId) ?? 0) + 1);
       }

package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md

@@ -69,6 +69,10 @@ customTriggers.provideHandlers({
 });
 ```
 
+## Singular Constraint
+
+`ECOM_DISCOUNTS_TRIGGER` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Discount Triggers service plugins in the same app.
+
 ## Key Implementation Notes
 
 1. **Trigger IDs must match** - The `customTriggerId` in `getEligibleTriggers` must match an `_id` from `listTriggers`

package/skills/wix-app/references/service-plugin/GIFT-CARDS.md

@@ -67,6 +67,10 @@ giftVouchersProvider.provideHandlers({
 });
 ```
 
+## Singular Constraint
+
+`GIFT_CARDS_PROVIDER` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Gift Cards service plugins in the same app.
+
 ## Key Implementation Notes
 
 1. **All three handlers required** - You must implement `redeem`, `getBalance`, and `_void`

package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md

@@ -26,7 +26,7 @@ paymentSettings.provideHandlers({
   getPaymentSettings: async ({ request, metadata }) => {
     try {
       // Get the order total
-      const orderTotal = request.order?.totals?.total || 0;
+      const orderTotal = Number(request.order?.priceSummary?.total?.amount) || 0;
 
       // Determine if 3DS is required based on order value
       const require3DS = orderTotal >= HIGH_VALUE_THRESHOLD;
@@ -45,6 +45,7 @@ paymentSettings.provideHandlers({
       };
     }
   },
+  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 
@@ -83,6 +84,7 @@ paymentSettings.provideHandlers({
       };
     }
   },
+  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 

package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md

@@ -53,6 +53,10 @@ shippingRates.provideHandlers({
 });
 ```
 
+## Singular Constraint
+
+`ECOM_SHIPPING_RATES` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Shipping Rates service plugins in the same app.
+
 ## Key Implementation Notes
 
 1. **Price as string** - All price values must be strings, not numbers

package/skills/wix-app/references/service-plugin/TOOLS_PROVIDER.md

@@ -0,0 +1,54 @@
+# Tools Provider Service Plugin Reference
+
+## Overview
+
+The Tools Provider SPI lets your app handle tool invocations from the Wix AI assistant. Implement the `runTool` handler — it receives the tool's `methodName` and a JSON `payload`, runs your business logic, and returns a response the AI assistant uses to answer the user.
+
+This is the execution side of the App Tools feature. The declaration side lives in the `APP_TOOLS` extension. See [APP_TOOLS.md](../APP_TOOLS.md) for the full picture.
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `runTool` | https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/run-tool?apiView=SDK |
+
+## Example: Routing Tool Calls by methodName
+
+```typescript
+import { toolsProvider } from '@wix/app-tools/service-plugins';
+
+toolsProvider.provideHandlers({
+  runTool: async ({ request, metadata }) => {
+    const { methodName, payload } = request;
+
+    switch (methodName) {
+      case 'get-order-status': {
+        const orderId = payload?.['orderId'];
+        if (typeof orderId !== 'string' || !orderId) {
+          throw new Error('orderId is required');
+        }
+        // fetch order status...
+        return {
+          response: {
+            status: 'shipped',
+            trackingNumber: 'TRACK123'
+          }
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${methodName}`);
+    }
+  }
+});
+```
+
+## Key Implementation Notes
+
+1. **Route on `methodName`** — use a `switch` or map to dispatch to the right handler logic
+2. **Validate inputs defensively** — `requestSchema` is advisory for the AI assistant; Wix does not validate the payload before calling your handler
+3. **Handle all activated tools** — cover every `methodName` with `activated: true` in your `APP_TOOLS` declaration; unhandled names should throw a clear error
+4. **Respond quickly** — the AI assistant is waiting; slow responses degrade the user experience
+5. **Elevate permissions for Wix API calls** — wrap SDK methods with `auth.elevate` from `@wix/essentials`

package/skills/wix-app/references/stores/QUERY.md

@@ -60,6 +60,38 @@ export async function listProductsPage(
 
 ---
 
+## Search products by name
+
+V3 `queryProducts` filters only on `_id`, `slug`, `options.id` and `handle` — `name` is a
+compile error. Use `productsV3.searchProducts()`, a direct call rather than a builder. V1 has
+no search method; its builder accepts `name` via `startsWith` (prefix match only, no `fuzzy`).
+
+Imports come from the first example in this file.
+
+```typescript
+// `v` comes from getVersion() — see STORES_VERSIONING.md.
+export async function searchByName(
+  term: string,
+  limit: number,
+  v: 'V1_CATALOG' | 'V3_CATALOG' | 'STORES_NOT_INSTALLED',
+) {
+  if (v === 'V3_CATALOG') {
+    const res = await productsV3.searchProducts({
+      cursorPaging: { limit },
+      // `fields` is required for free-text search. Searchable: 'name', 'description',
+      // 'variantsInfo.variants.sku', 'minVariantPriceInfo.sku'.
+      search: { expression: term, fields: ['name'], fuzzy: true },
+    });
+    // Note `products` (not `items`) and `pagingMetadata.hasNext` (a property, not a method).
+    return res.products ?? [];
+  }
+  const res = await products.queryProducts().startsWith('name', term).limit(limit).find();
+  return res.items;
+}
+```
+
+---
+
 ## Display price/stock without fetching variants
 
 V3 `queryProducts` does not return variants. Read product-level rollup fields instead: