@wix/agent-skills 1.16.2 → 1.17.0

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

@@ -1,139 +1,222 @@
-# Accessibility (ARIA)
+# Accessibility Implementation and Review
 
-Rules and patterns for ARIA accessibility support in Editor React components.
+Use this reference while authoring Editor React Component props and JSX and
+after every JSX edit.
 
----
+## Contents
 
-## Rules
+- [Implementation Contract](#implementation-contract)
+- [Review Scope](#review-scope)
+- [Automated Scanners](#automated-scanners)
+- [Finding Triage](#finding-triage)
+- [Manual Review](#manual-review)
+- [Pre-Fix Checks for Non-Interactive Controls](#pre-fix-checks-for-non-interactive-controls)
+- [Completion Criteria](#completion-criteria)
 
-### All ARIA Attributes Through the `a11y` Prop
+## Implementation Contract
 
-- **NEVER** add individual ARIA properties like `ariaLabel?: string`, `ariaDescribedBy?: string`, `role?: string`, etc. to a component's props interface.
-- **ALL** accessibility attributes MUST come through the `a11y?: A11y` prop.
-- The `A11y` type includes: `ariaLabel`, `ariaDescribedBy`, `ariaLabelledBy`, `role`, `ariaHidden`, `ariaLive`, and all other ARIA attributes.
-- Users provide ARIA values through the `a11y` prop: `<Component a11y={{ ariaLabel: "..." }} />`
+### Route ARIA Through `a11y`
 
-### ARIA Label Rules
+Do not add individual public props such as `ariaLabel`, `ariaDescribedBy`, or
+`role`. Use the platform `A11y` type and convert it at the semantic target.
 
-ARIA labels are user-facing content and must NEVER be hardcoded as string literals in JSX.
+```tsx
+import type { A11y, Direction } from '@wix/editor-react-types';
+import { convertA11yKeysToHtmlFormat } from '@wix/react-component-utils';
 
-**Three patterns (in order of preference):**
+export type TabsProps = {
+  id?: string;
+  className?: string;
+  direction?: Direction;
+  a11y?: A11y;
+};
 
-1. **No aria-label (preferred)** — Visible text content is sufficient:
+<nav {...(a11y && convertA11yKeysToHtmlFormat(a11y))}>{tabs}</nav>;
+```
 
-   ```tsx
-   <Button>Play</Button> // Visible text ✅
-   ```
+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.
 
-2. **User-configurable** — Via a11y prop (for root or element-specific labels, per requirements):
+### Provide Accessible Names
 
-   ```tsx
-   // User provides: <ComponentName a11y={{ ariaLabel: "Background music" }} />
-   // Component applies to root (using the a11y-to-HTML conversion utility):
-   {...(a11y && convertA11yKeysToHtmlFormat(a11y))}
+Use this priority order:
 
-   // Or for inner elements (if requirements specify):
-   // elementProps.button.a11y gets passed to the button element
-   ```
+1. Prefer visible text that already names the control.
+2. Use user-configurable `a11y` when the name depends on site-owner content.
+3. Use the project's translation mechanism or a `constants.ts` value only for a
+   stable system-owned label required by the component contract.
 
-3. **System-required** — Via constants.ts (when requirements specify non-configurable label):
+Never hardcode an `aria-label` string directly in JSX.
 
-   ```tsx
-   // constants.ts
-   export const ARIA_LABELS = {
-     playButton: 'Play audio',
-     muteButton: 'Mute audio',
-   } as const;
+```tsx
+// constants.ts
+export const ARIA_LABELS = {
+  playButton: 'Play animation',
+  pauseButton: 'Pause animation',
+} as const;
 
-   // component.tsx
-   import { ARIA_LABELS } from './constants';
-   <Button aria-label={ARIA_LABELS.playButton}>▶</Button>;
-   ```
+// component JSX
+<button
+  aria-label={isPlaying ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton}
+>
+  {isPlaying ? <PauseIcon /> : <PlayIcon />}
+</button>;
+```
 
-**❌ NEVER hardcode string literals:**
+Icon-only controls require an accessible name. Controls with visible text,
+including an icon plus visible text, usually do not need another ARIA label.
 
-```tsx
-// ❌ WRONG - hardcoded strings
-<Button aria-label="Play">▶</Button>
-<Button aria-label={isPlaying ? "Pause" : "Play"}>▶</Button>
-<Slider aria-label="Volume" />
+### Preserve Semantic Ownership
+
+- Put roles, labels, descriptions, keyboard handling, and focusability on the
+  element that owns the behavior, not on a layout wrapper.
+- Prefer native elements over recreating their semantics with `role`.
+- Hide decorative-only output with `aria-hidden="true"` when appropriate.
+- Preserve heading, list, navigation, and landmark semantics through wrappers.
+- Keep hidden or collapsed state consistent across visuals, focusability, and
+  the accessibility tree.
+
+## Review Scope
+
+Run this review after creating or editing JSX.
+
+| Request | Scan and inspect |
+| --- | --- |
+| 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 |
+
+Exclude `*.generated.ts`; it is regenerated from JSX and CSS.
+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
+
+`<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.
+
+```bash
+node <SKILL_ROOT>/scripts/scan-a11y-eslint.cjs <file1> [file2] ...
+node <SKILL_ROOT>/scripts/scan-a11y-code.cjs <file1> [file2] ...
 ```
 
-**Why this matters:**
+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.
 
-- Hardcoded strings cannot be translated or customized
-- User-provided labels take precedence when available
-- Constants allow centralized management and potential future translation
+## Finding Triage
 
-### Detecting Icon-Only Interactive Elements
+For every finding:
 
-**Icon-only elements require aria-labels.** Detect with this checklist:
+1. Trace the rendered semantic element through local and shared components.
+2. Deduplicate findings for the same issue and location; keep the finding with
+   stronger evidence.
+3. Assign `confirmed`, `false-positive`, or `not-relevant`.
+4. Fix only confirmed findings.
 
-| Element Content       | Needs aria-label? | Example                                   |
-| --------------------- | ----------------- | ----------------------------------------- |
-| Visible text only     | ❌ No             | `<Button>Play</Button>`                   |
-| Icon component + text | ❌ No             | `<Button><PlayIcon />Play</Button>`       |
-| Icon/emoji only       | ✅ YES            | `<Button>▶</Button>`                     |
-| Image only            | ✅ YES            | `<Button><img src="play.png" /></Button>` |
-| SVG only              | ✅ YES            | `<Button><svg>...</svg></Button>`         |
+Scanner output is a lead, not permission to edit blindly.
 
-**Critical:** If button/link contains ONLY visual elements (icons, emojis, images, SVG) with NO text node, it MUST have aria-label from constants.
+### Confidence and Action
 
-**Pattern for dynamic labels:**
+| Confidence | Evidence | Action |
+| --- | --- | --- |
+| High | The rendered element and static props directly establish the issue. | Confirm and fix when the change is safe and local. |
+| Medium | Props or partial component resolution strongly imply the semantics. | Inspect surrounding code, then confirm or discard. |
+| Low | Heuristics or unresolved runtime spreads are the main evidence. | Trace further and fix only after confirmation. |
+| Unknown | The semantic target cannot be resolved. | Leave unchanged and report the ambiguity when material. |
 
-```tsx
-// constants.ts
-export const ARIA_LABELS = {
-  playButton: 'Play audio',
-  pauseButton: 'Pause audio',
-} as const;
+Confidence establishes whether a finding is real, not whether its fix is safe.
+Apply confirmed local, behavior-preserving fixes. Leave a confirmed issue
+unchanged only when product intent is unknowable or the fix requires risky,
+non-local behavior changes.
 
-// component.tsx
-<Button
-  aria-label={isPlaying ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton}
->
-  {isPlaying ? '⏸' : '▶'}
-</Button>;
-```
+### Semantic Resolution Order
 
----
+Resolve rendered behavior in this order:
 
-## Common Mistake: Individual ARIA Properties Instead of A11y Type
+1. Flagged JSX element and static props
+2. Explicit polymorphic props such as `as="a"` or `component="button"`
+3. Local component implementation
+4. Installed package source or declarations
+5. Prop evidence such as `href`, `to`, `src`, `alt`, and `role`
+6. Component-name heuristics
 
-**❌ Wrong:**
+Follow local imports to their rendered root. For package imports, inspect the
+resolved package entry when available. Do not assign more confidence than the
+evidence supports.
 
-```typescript
-import type { Direction } from '@wix/editor-react-types';
+## Manual Review
 
-export interface TabsProps {
-  id?: string;
-  className?: string;
-  direction?: Direction;
-  ariaLabel?: string; // ❌ Individual ARIA prop
-  ariaDescribedBy?: string; // ❌ Individual ARIA prop
-  role?: string; // ❌ Individual ARIA prop
-}
-```
+Verify all of the following after triaging scanner output.
 
-**✅ Correct:**
+### Semantic Targeting
 
-```typescript
-import type { A11y, Direction } from '@wix/editor-react-types';
-import { convertA11yKeysToHtmlFormat } from '@wix/react-component-utils';
+- `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.
 
-export interface TabsProps {
-  id?: string;
-  className?: string;
-  direction?: Direction;
-  a11y?: A11y;  // ✅ All ARIA attributes through this prop
-}
+### Names and Visual Content
 
-// Usage:
-<Tabs a11y={{ ariaLabel: "Navigation", role: "navigation" }} />
+- 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.
 
-// In component:
-{...(a11y && convertA11yKeysToHtmlFormat(a11y))}
-```
+### 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.
+- The root implements the direction contract, and every `ReactNode` slot
+  isolates nested content with `dir="ltr"`.
+
+## Pre-Fix Checks for Non-Interactive Controls
+
+Before adding `role="button"`, `tabIndex`, and keyboard handlers to a non-native
+control, verify:
+
+1. **Interactive children:** it cannot contain a link, button, input, or another
+   interactive component in the active branch.
+2. **Focus ownership:** existing `tabIndex` or accessibility spreads have a
+   clear merge order and one authoritative source.
+3. **Interaction condition:** the same condition gates pointer, focus, and
+   keyboard behavior and excludes disabled or editor-controlled states when
+   needed.
+4. **Accessible-name scope:** the label intentionally names the component or
+   action and persists in every state where it is needed.
+
+Prefer a native element when it preserves product behavior.
+
+## Completion Criteria
+
+The accessibility review is complete only when:
 
-**Why:** The `A11y` type from `@wix/editor-react-types` provides a standardized way to handle ALL ARIA attributes (ariaLabel, ariaDescribedBy, ariaLabelledBy, role, ariaHidden, ariaLive, etc.). Individual ARIA props fragment the API and make it harder to use.
+- 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.
 
+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

@@ -1,14 +1,22 @@
-# Animated Components (Play/Pause Control)
+# Animated Components
 
-Rules and patterns for components whose primary content is a **playable
-animation** — a Lottie/JSON animation, an animated GIF/SVG, a canvas/WebGL
-loop, or a video-like surface.
+Use this reference when the component's primary content is a **playable
+animation**—a Lottie/JSON animation, an animated GIF/SVG, a canvas/WebGL loop,
+or a video-like surface.
 
-Every such component MUST ship an on-stage **play/pause button**.
+Every such component must ship an on-stage **play/pause button**.
 
----
+## Contents
 
-## When this applies
+- [Apply When](#apply-when)
+- [Required Contract](#required-contract)
+- [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)
+- [Checklist](#checklist)
+
+## Apply When
 
 Apply automatically — without being asked — whenever the component has an
 `autoPlay` prop **or** its primary content is a **startable / loopable**
@@ -22,25 +30,28 @@ animation a visitor would reasonably want to start or stop:
 
 **Key rule:** If the component accepts an `autoPlay` prop — even if the
 underlying mechanism is a `setInterval` advancing an index rather than a media
-player — it MUST expose a play/pause button so visitors can stop the
+player, it must expose a play/pause button so visitors can stop the
 auto-advancing behavior. "Autoplay" is a behavior contract, not an
 implementation detail.
 
----
-
-## What to add (checklist)
+## Required Contract
 
-1. **Props** — `autoPlay`, `loop`, `pauseButtonVisibility`
+1. **Props** — for a new component, use `autoPlay` when it can start
+   automatically, `loop` only when repeat behavior is supported, and
+   `pauseButtonVisibility` for the on-stage control. When editing, preserve
+   existing playback prop names and add only the missing safety contract.
 2. **Playback state** — `isPlaying` + `handlePause` / `handleResume`
-3. **Play/pause button** — overlay `<button>` with inline SVG icon + CSS positioning and optional hover-only visibility; **must be a named part** (`classNames('component-name-play-button', styles.playButton)`) with hover/focus design-state selectors
+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
 
----
-
-## 1. Props
+## 1. Define Props
 
-Playback controls are **behavior** props (see [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md)):
+Playback controls are behavior props. `pauseButtonVisibility` is the documented
+exception to the usual visual-visibility rule because editor preview must be
+able to force the safety control visible.
 
 ```typescript
 import type { A11y, Direction } from '@wix/editor-react-types';
@@ -59,12 +70,17 @@ export interface MyAnimationProps {
 
   /** Show play/pause button. Default `'showOnHover'`. */
   pauseButtonVisibility?: 'showAlways' | 'showOnHover';
+
+  elementProps?: {
+    playButton?: { className?: string };
+  };
 }
 ```
 
----
+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.
 
-## 2. Playback state
+## 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:
 
@@ -97,9 +113,7 @@ const handleResume = () => setIsPlaying(true);
 
 Pass `isPlaying` to the animation renderer and toggle between `handlePause` / `handleResume` on button click.
 
----
-
-## 3. Play/pause button
+## 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, stroke, and fill should feel native to the component's design.
 
@@ -126,30 +140,54 @@ Position the button absolutely so it overlays the content without pushing other
   /* e.g. background: rgba(255, 255, 255, 1); */
 }
 
-.playButton:global(.my-animation-play-button--focus),
+/* Keyboard indicator only: focus is not an editor design state on a non-input
+   control unless editable focus styling was explicitly requested. */
 .playButton:focus-visible {
   outline: 2px solid currentColor;
   outline-offset: 2px;
 }
 ```
 
+Define stable system-owned labels outside JSX:
+
+```ts
+// constants.ts
+export const ARIA_LABELS = {
+  playButton: 'Play animation',
+  pauseButton: 'Pause animation',
+} as const;
+```
+
+Set the visibility data attribute on the existing elected root, preserving its
+full root contract:
+
+```tsx
+data-pause-button-visibility={pauseButtonVisibility ?? 'showOnHover'}
+```
+
+Wire the named part completely:
+
 ```tsx
-{/* ✅ Named part: play/pause is always a named part — site owners can style it independently */}
 <button
   type="button"
-  className={classNames('my-animation-play-button', styles.playButton)}
+  {...elementProps?.playButton}
+  className={classNames(
+    'my-animation-play-button',
+    styles.playButton,
+    elementProps?.playButton?.className,
+  )}
   onClick={isPlaying ? handlePause : handleResume}
-  aria-label={isPlaying ? 'Pause' : 'Play'}
+  aria-label={
+    isPlaying ? ARIA_LABELS.pauseButton : ARIA_LABELS.playButton
+  }
 >
   {isPlaying ? <PauseIcon /> : <PlayIcon />}
 </button>
 ```
 
 ```css
-/* pauseButtonVisibility visibility behavior — descendant CSS is allowed here
-   because these rules control the button's *visibility*, not its styling surface.
-   The button itself is a named part (classNames('...-play-button', styles.playButton))
-   and must carry both a global class and design-state selectors (see above). */
+/* Narrow behavior-only exception documented in CSS-GUIDELINES.md. Keep editable
+   appearance on .playButton and use this relationship only for visibility. */
 
 /* showOnHover (default) */
 .root[data-pause-button-visibility="showOnHover"] .playButton {
@@ -165,37 +203,44 @@ Position the button absolutely so it overlays the content without pushing other
 /* showAlways — no extra CSS needed; button is visible by default */
 ```
 
----
-
-## 4. Modify `component.preview.tsx` for autoplay suppression
+## 4. Suppress Autoplay in `component.preview.tsx`
 
-For animated components, modify the generated `component.preview.tsx` to suppress autoplay in editor design mode. See [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) for how the preview file works.
+The Wix CLI scaffold generates `component.preview.tsx`. For animated components,
+modify its passthrough preview component without replacing the generated
+defaults or fallback-placeholder wiring.
 
-### Target state of `component.preview.tsx`
+### Adapt the generated `component.preview.tsx`
 
-Replace the generated passthrough with the following. Replace `MyComponent` with the real component name.
+Add `useIsEditMode` to the existing `@wix/react-component-utils` import. In the
+generated preview component, replace only the passthrough return with the gated
+props below. Keep the generated `withFallbackPlaceholder`, required-data fields,
+root class, and `withDefaults` export unchanged.
 
 ```tsx
-import React from 'react';
-import MyComponent from './component';
-import { useIsEditMode } from '@wix/react-component-utils';
-
-export default function MyComponentPreview(
-  props: React.ComponentProps<typeof MyComponent>,
-) {
+const MyAnimationPreview: FC<ComponentProps<typeof Component>> = (props) => {
   const isEditMode = useIsEditMode();
 
   return (
-    <MyComponent
+    <Component
       {...props}
       autoPlay={isEditMode ? false : props.autoPlay}
       pauseButtonVisibility={isEditMode ? 'showAlways' : props.pauseButtonVisibility}
     />
   );
-}
+};
 ```
 
-In editor design mode (`isEditMode` is `true`) → `autoPlay` is forced to `false` and `pauseButtonVisibility` is forced to `'showAlways'` so the site owner can always see and interact with the button.  
+In editor design mode (`isEditMode` is `true`) → `autoPlay` is forced to `false` and `pauseButtonVisibility` is forced to `'showAlways'` so the site owner can always see and interact with the button.
 In preview mode (`isEditMode` is `false`) → both use the user's configured values.
 
----
+## Checklist
+
+- [ ] Autoplaying or loopable primary content has an on-stage play/pause control.
+- [ ] Autoplay and pause-control props use the documented contract; `loop` is
+      present only when repeat behavior is supported.
+- [ ] Reduced motion starts paused and never restarts playback automatically.
+- [ ] The play/pause button is a fully wired named part with a stable accessible name.
+- [ ] Hover has a paired editor design state; `:focus-visible` remains a
+      standalone keyboard indicator.
+- [ ] Hover-only visibility changes behavior, not the button's editable styling surface.
+- [ ] The preview preserves generated wrappers and forces autoplay off in design mode.

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

@@ -1,9 +1,10 @@
 # Branded / Themed Components
 
-Apply automatically — without being asked — whenever the user requests a
-**branded**, **themed**, or **brand-aware** component.
+Use this reference only when the prompt explicitly requests a **branded**,
+**themed**, or **brand-aware** component. Do not infer this requirement from a
+generic request for polished styling.
 
----
+## Rules
 
 Import theme tokens from `@wix/react-component-schema/theme-variables.module.css`
 using CSS Modules `@value`, then consume with `var()`.
@@ -24,6 +25,14 @@ using CSS Modules `@value`, then consume with `var()`.
 
 **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.  
+- Do not use `var(--wst-*)` directly; import the `@value` alias first.
+- 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.
+
+## Checklist
+
+- [ ] Theme values are imported from `theme-variables.module.css` with `@value`.
+- [ ] Imported aliases are consumed through `var()`.
+- [ ] Typography uses heading/paragraph font and color token pairs.
+- [ ] Text colors remain legible on the selected background token.