@wix/interact 2.0.3 → 2.1.0

package/rules/full-lean.md

@@ -30,6 +30,25 @@ const config: InteractConfig = {
 Interact.create(config);
 ```
 
+### Using `namedEffect` presets (`registerEffects`)
+
+Before using `namedEffect`, you must register the presets with the `Interact` instance. Without this, `namedEffect` types will not resolve.
+
+```ts
+import { Interact } from '@wix/interact/web'; // or /react
+import * as presets from '@wix/motion-presets';
+
+Interact.registerEffects(presets);
+Interact.create(config);
+```
+
+Or register only what you need:
+
+```ts
+import { FadeIn, ParallaxScroll } from '@wix/motion-presets';
+Interact.registerEffects({ FadeIn, ParallaxScroll });
+```
+
 - Without Node/build tools: add a `<script type="module">` and import from the CDN.
 
 ```html
@@ -97,7 +116,7 @@ This configuration declares what user/system triggers occur on which source elem
 
 ### Global rules
 
-- **Required/Optional**: You MUST provide an `interactions` array. You SHOULD provide an `effects` registry when you want to reference reusable effects by id. `conditions` are OPTIONAL.
+- **Required/Optional**: You MUST provide an `interactions` array. You SHOULD provide an `effects` registry when you want to reference reusable effects by id. `conditions` and `sequences` are OPTIONAL.
 - **Cross-references**: All cross-references (by id) MUST point to existing entries (e.g., an `EffectRef.effectId` MUST exist in `effects`).
 - **Element keys**: All element keys (`key` fields) refer to the element path string (e.g., the value used in `data-interact-key`) and MUST be stable for the lifetime of the configuration.
 - **List context**: Where both a list container and list item selector are provided, they MUST describe the same list context across an interaction and its effects. Mismatched list contexts will be ignored by the system.
@@ -111,6 +130,11 @@ This configuration declares what user/system triggers occur on which source elem
   - **Key (string)**: The effect id. MUST be unique across the registry.
   - **Value (Effect)**: A full effect definition. See Effect rules below.
 
+- **sequences?: Record<string, SequenceConfig>**
+  - **Purpose**: A registry of reusable sequence definitions that can be referenced from interactions via `SequenceConfigRef`.
+  - **Key (string)**: The sequence id. MUST be unique across the registry.
+  - **Value (SequenceConfig)**: A full sequence definition. See Sequences section below.
+
 - **conditions?: Record<string, Condition>**
   - **Purpose**: Named predicates that gate interactions/effects by runtime context.
   - **Key (string)**: The condition id. MUST be unique across the registry.
@@ -195,8 +219,67 @@ This configuration declares what user/system triggers occur on which source elem
       - OPTIONAL. Additional CSS selector to refine element selection:
         - Without `listContainer`: Uses `querySelectorAll` to match all elements within the root element as separate items.
         - With `listContainer`: Uses `querySelectorAll` within the container to find matching elements as list items. For dynamically added list items, uses `querySelector` within each item to find a single matching element.
-    - **effects: Array<Effect | EffectRef>**
-      - REQUIRED. The effects to apply when the trigger fires. Ordering is significant: the first array entry is applied first. The system may reverse internal storage to preserve this application order.
+    - **effects?: Array<Effect | EffectRef>**
+      - The effects to apply when the trigger fires. Ordering is significant: the first array entry is applied first. The system may reverse internal storage to preserve this application order.
+      - At least one of `effects` or `sequences` MUST be provided.
+    - **sequences?: Array<SequenceConfig | SequenceConfigRef>**
+      - OPTIONAL. Sequences to play when the trigger fires. Each sequence coordinates multiple effects with staggered timing. See Sequences section below.
+
+### Sequences (coordinated multi-effect stagger)
+
+Sequences let you group multiple effects into a single coordinated timeline with staggered delays. Instead of manually setting `delay` on each effect, you define `offset` (ms between items) and `offsetEasing` (how that offset is distributed).
+
+**Prefer sequences over manual delay stagger** for any multi-element entrance or orchestration pattern.
+
+- **SequenceConfig** type:
+  - `effects: (Effect | EffectRef)[]` — REQUIRED. The effects in this sequence, applied in array order.
+  - `delay?: number` — Base delay (ms) before the entire sequence starts. Default `0`.
+  - `offset?: number` — Stagger offset (ms) between consecutive effects. Default `0`.
+  - `offsetEasing?: string | ((p: number) => number)` — Easing function for stagger distribution. Named easings: `'linear'`, `'quadIn'`, `'quadOut'`, `'sineOut'`, `'cubicIn'`, `'cubicOut'`, `'cubicInOut'`. Also accepts `'cubic-bezier(...)'` strings or a JS function `(p: number) => number`. Default `'linear'`.
+  - `sequenceId?: string` — Id for caching and referencing. Auto-generated if omitted.
+  - `conditions?: string[]` — Condition ids that MUST all pass for this sequence to be active.
+
+- **SequenceConfigRef** type (referencing a reusable sequence):
+  - `sequenceId: string` — REQUIRED. MUST match a key in `InteractConfig.sequences`.
+  - `delay?`, `offset?`, `offsetEasing?`, `conditions?` — OPTIONAL overrides merged on top of the referenced sequence.
+
+- Effects within a sequence follow the same rules as standalone effects. Each effect can:
+  - Target a different element via `key` (cross-element sequences).
+  - Use `listContainer` to target list children (each child becomes a separate effect in the sequence).
+  - Reference the effects registry via `effectId`.
+
+- A sequence is treated as a single animation unit by the trigger handler—it plays, reverses, and alternates as one.
+
+**Example — viewEnter staggered list using `listContainer`**:
+
+```typescript
+{
+  interactions: [
+    {
+      key: 'card-grid',
+      trigger: 'viewEnter',
+      params: { type: 'once', threshold: 0.3 },
+      sequences: [
+        {
+          offset: 100,
+          offsetEasing: 'quadIn',
+          effects: [
+            {
+              effectId: 'card-entrance',
+              listContainer: '.card-grid',
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  effects: {
+    'card-entrance': {
+      // ...
+    },
+  },
+}
+```
 
 ### Working with elements
 
@@ -363,7 +446,7 @@ The config remains the same for both integrations—only the HTML/JSX setup diff
      - `transitionDelay?`: number
      - `transitionEasing?`: `ScrubTransitionEasing`
      - One of `keyframeEffect | namedEffect | customEffect` (see above)
-     - For mouse-effects driven by the `pointerMove` trigger, do NOT use `keyframeEffect` (pointer progress is two‑dimensional and cannot be mapped to linear keyframes). Use `namedEffect` mouse presets instead, or `customEffect` for custom‑made animations.
+     - For mouse-effects driven by the `pointerMove` trigger, avoid `keyframeEffect` unless using `params: { axis: 'x' | 'y' }` to map a single pointer axis to linear 0–1 progress. For 2D effects, use `namedEffect` mouse presets or `customEffect` instead.
      - For scroll `namedEffect` presets (e.g., `*Scroll`) used with a `viewProgress` trigger, include `range: 'in' | 'out' | 'continuous'` in the `namedEffect` options; prefer `'continuous'` for simplicity.
      - RangeOffset (used by `rangeStart`/`rangeEnd`):
        - Type: `{ name: 'entry' | 'exit' | 'contain' | 'cover' | 'entry-crossing' | 'exit-crossing'; offset: LengthPercentage }`
@@ -396,11 +479,14 @@ The config remains the same for both integrations—only the HTML/JSX setup diff
 
 - **namedEffect (Preferred)**: Use first for best performance. These are pre-built presets from `@wix/motion-presets` that are GPU-friendly and tuned.
   - Structure: `namedEffect: { type: '<PresetName>', /* optional preset options like direction (bottom|top|left|right), etc. do not use those without having proper documentation of which options exist and of what types. */ }`
-  - Short list of common preset names: - Entrance: `FadeIn`, `BounceIn`, `SlideIn`, `F
-lipIn`, `ArcIn` - Ongoing: `Pulse`, `Spin`, `Wiggle`, `Bounce` - Scroll: `ParallaxScroll`, `FadeScroll`, `RevealScroll`, `TiltScroll` - For scroll-effects used with the `viewProgress` trigger, the `namedEffect` options MUST include `range: 'in' | 'out' | 'continuous'`. Prefer `range: 'continuous'` for simplicity. - Mouse: For `pointerMove` (mouse-effects), prefer `namedEffect` presets (e.g., `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse`); avoid `keyframeEffect` with `pointerMove` since progress is two‑dimensional. - Mouse: `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse`
+  - Short list of common preset names:
+    - Entrance: `FadeIn`, `BounceIn`, `SlideIn`, `FlipIn`, `ArcIn`
+    - Ongoing: `Pulse`, `Spin`, `Wiggle`, `Bounce`
+    - Scroll: `ParallaxScroll`, `FadeScroll`, `RevealScroll`, `TiltScroll` — for `viewProgress`, `namedEffect` options MUST include `range: 'in' | 'out' | 'continuous'`; prefer `'continuous'`
+    - Mouse: `TrackMouse`, `Tilt3DMouse`, `ScaleMouse`, `BlurMouse` — for `pointerMove`; prefer over `keyframeEffect` for 2D pointer effects
 - **keyframeEffect (Default for custom animations)**: Prefer this when you need a custom-made animation.
   - Structure: `keyframeEffect: { name: string; keyframes: Keyframe[] }` (keyframes use standard CSS/WAAPI properties).
-  - Not compatible with `pointerMove` (mouse-effects) because pointer progress is two‑dimensional; use `customEffect` for custom pointer‑driven animations.
+  - When used with `pointerMove`, requires `params: { axis: 'x' | 'y' }` to select which pointer coordinate maps to linear progress. Without `axis`, pointer progress is two-dimensional and cannot drive keyframe animations. For 2D pointer effects, use `namedEffect` or `customEffect`.
 - **customEffect (Last resort)**: Use only when you must perform DOM manipulation or produce randomized/non-deterministic visuals that cannot be expressed as keyframes or presets.
   - Structure: `customEffect: (element: Element, progress: any) => void`
 

package/rules/hover.md

@@ -1,4 +1,4 @@
-# Hover Trigger Rules
+# Hover Trigger Rules for @wix/interact
 
 This document contains rules for generating hover trigger interactions in `@wix/interact`. These rules cover all hover behavior patterns and common use cases.
 
@@ -10,11 +10,11 @@ This document contains rules for generating hover trigger interactions in `@wix/
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'hover',
     effects: [
         {
-            key: '[TARGET_IDENTIFIER]',
+            key: '[TARGET_KEY]',
             [EFFECT_TYPE]: [EFFECT_DEFINITION],
             fill: 'both',
             duration: [DURATION_MS],
@@ -26,8 +26,8 @@ This document contains rules for generating hover trigger interactions in `@wix/
 
 **Variables**:
 
-- `[SOURCE_IDENTIFIER]`: Unique identifier for hoverable element (e.g., '#menu-button', '#accordion-header'). Should equal the value of the data-interact-key attribute on the wrapping interact-element.
-- `[TARGET_IDENTIFIER]`: Unique identifier for animated element (can be same as trigger or different). Should equal the value of the data-interact-key attribute on the wrapping interact-element.
+- `[SOURCE_KEY]`: Unique identifier for hoverable element. Should equal the value of the `data-interact-key` attribute on the wrapping `<interact-element>`.
+- `[TARGET_KEY]`: Unique identifier for animated element (can be same as `[SOURCE_KEY]` for self-targeting, or different for cross-targeting).
 - `[EFFECT_TYPE]`: Either `namedEffect` or `keyframeEffect`
 - `[EFFECT_DEFINITION]`: Named effect object (e.g., { type: 'SlideIn', ...params }, { type: 'FadeIn', ...params }) or keyframe object (e.g., { name: 'custom-fade', keyframes: [{ opacity: 0 }, { opacity: 1 }] }, { name: 'custom-slide', keyframes: [{ transform: 'translateX(-100%)' }, { transform: 'translateX(0)' }] })
 - `[DURATION_MS]`: Animation duration in milliseconds (typically 200-500ms for micro-interactions)
@@ -38,7 +38,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
 
 - `DURATION_MS`: 300 (for micro-interactions)
 - `EASING_FUNCTION`: 'ease-out' (for smooth feel)
-- `TARGET_IDENTIFIER`: Same as source key (self-targeting)
+- `[TARGET_KEY]`: Same as `[SOURCE_KEY]` for self-targeting
 
 **Common Use Cases**:
 
@@ -93,26 +93,25 @@ This document contains rules for generating hover trigger interactions in `@wix/
 }
 ```
 
-## Rule 2: Hover Enter/Leave Animations with Named Effects
+## Rule 2: Hover Alternate Animations (namedEffect / keyframeEffect)
 
-**Purpose**: Generate hover interactions using pre-built named effects from @wix/motion-presets
+**Purpose**: Hover interactions that play forward on mouse enter and reverse on mouse leave (`type: 'alternate'`).
 
 **Pattern**:
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'hover',
     params: {
         type: 'alternate'
     },
     effects: [
         {
-            key: '[TARGET_IDENTIFIER]',
-            namedEffect: {
-                type: '[NAMED_EFFECT_TYPE]',
-                [EFFECT_PROPERTIES]
-            },
+            key: '[TARGET_KEY]',
+            // Use namedEffect OR keyframeEffect:
+            namedEffect: { type: '[NAMED_EFFECT_TYPE]' },
+            // keyframeEffect: { name: '[EFFECT_NAME]', keyframes: [{ ... }, { ... }] },
             fill: 'both',
             reversed: [REVERSED_BOOL],
             duration: [DURATION_MS],
@@ -124,143 +123,56 @@ This document contains rules for generating hover trigger interactions in `@wix/
 
 **Variables**:
 
-- `[REVERSED_BOOL]`: Optional boolean value indicating whether the mouse enter animation is reversed (and mouse leave is forwards).
-- `[NAMED_EFFECT_TYPE]`: Name of the pre-built named effect from @wix/motion-presets to use.
-- `[EFFECT_PROPERTIES]`: Named effect specific properties (distance, angle, perspective, etc.)
+- `[REVERSED_BOOL]`: Optional. `true` to reverse the enter direction (mouse enter plays backwards, leave plays forwards).
+- `[NAMED_EFFECT_TYPE]`: Pre-built effect from `@wix/motion-presets`. Available hover presets:
+  - Size: `ExpandIn`, `Pulse`, `GrowIn`
+  - Fade/Blur: `FadeIn`, `Flash`, `BlurIn`
+  - Translate: `SlideIn`, `GlideIn`, `FloatIn`, `BounceIn`, `GlitchIn`
+  - Rotate: `SpinIn`, `TiltIn`, `ArcIn`, `TurnIn`, `FlipIn`, `Spin`, `Swing`
+  - Attention: `Bounce`, `DropIn`, `Rubber`, `Jello`, `Cross`, `Wiggle`, `Poke`
 - Other variables same as Rule 1
 
-**Available Named Effects for Hover**:
-
-- **Size Changes**: `ExpandIn`, `Pulse`, `GrowIn`
-- **Opacity/Blur Changes**: `FadeIn`, `Flash`, `BlurIn`
-- **Translation Effects**: `SlideIn`, `GlideIn`, `FloatIn`, `BounceIn`, `GlitchIn`
-- **Rotation Effects**: `SpinIn`, `TiltIn`, `ArcIn`, `TurnIn`, `FlipIn`, `Spin`, `Swing`
-- **Special Attention Effects**: `Bounce`, `DropIn`, `Rubber`, `Jello`, `Cross`, `Wiggle`, `Poke`
-
-**Important**: Spatial effects that change the hit-area considerably (translation, rotation) should use different source and target keys to avoid unwanted flickering on hover enter/leave.
+**Important**: Spatial effects (translation, rotation) that change the hit-area considerably should use different source and target keys to avoid flickering on enter/leave.
 
 **Default Values**:
 
-- `type`: 'alternate' (plays forward on enter, reverses on leave)
-- `DURATION_MS`: 250
+- `DURATION_MS`: 250–300
 - `EASING_FUNCTION`: 'ease-out'
 
-**Example Generations**:
+**Example — namedEffect (card scale)**:
 
 ```typescript
-// Card scale effect
 {
     key: 'feature-card',
     trigger: 'hover',
-    params: {
-        type: 'alternate'
-    },
+    params: { type: 'alternate' },
     effects: [
         {
             key: 'feature-card',
-            namedEffect: {
-                type: 'Pulse'
-            },
+            namedEffect: { type: 'Pulse' },
             fill: 'both',
             duration: 250,
             easing: 'ease-out'
         }
     ]
 }
-
-// Icon rotation effect (different source/target to avoid flickering)
-{
-    key: 'button',
-    trigger: 'hover',
-    params: {
-        type: 'alternate'
-    },
-    effects: [
-        {
-            key: 'button-icon',
-            namedEffect: {
-                type: 'SpinIn',
-                direction: 'clockwise'
-            },
-            fill: 'both',
-            duration: 200,
-            easing: 'ease-out'
-        }
-    ]
-}
 ```
 
-## Rule 3: Hover Interactions with Alternate Pattern
-
-**Purpose**: Generate hover interactions that play forward on mouse enter and reverse on mouse leave
-
-**Pattern**:
+**Example — keyframeEffect (card lift)**:
 
 ```typescript
-{
-    key: '[SOURCE_IDENTIFIER]',
-    trigger: 'hover',
-    params: {
-        type: 'alternate'
-    },
-    effects: [
-        {
-            key: '[TARGET_IDENTIFIER]',
-            keyframeEffect: {
-                name: '[UNIQUE_KEYFRAME_EFFECT_NAME]',
-                keyframes: [
-                    { [PROPERTY_1]: '[START_VALUE]', [PROPERTY_2]: '[START_VALUE]' },
-                    { [PROPERTY_1]: '[END_VALUE]', [PROPERTY_2]: '[END_VALUE]' }
-                ]
-            },
-            fill: 'both',
-            duration: [DURATION_MS],
-            easing: '[EASING_FUNCTION]'
-        }
-    ]
-}
-```
-
-**Variables**:
-
-- `[UNIQUE_KEYFRAME_EFFECT_NAME]`: unique name for the keyframeEffect.
-- `[PROPERTY_N]`: animatable CSS property.
-- `[START/END_VALUE]`: values for the animated CSS properties in the start/end frame.
-- Other variables same as Rule 1
-
-**Best Properties for Hover Effects**:
-
-- `transform`: scale, translate, rotate transformations
-- `opacity`: fade effects
-- `box-shadow`: elevation changes
-- `filter`: blur, brightness, hue-rotate
-- `background-color`: color transitions
-- Spatial effects that change the hit-area of the animated element considerably (e.g. Translation effects, Rotation effects, etc.) should have different source and target to avoid unwanted flickering.
-
-**Default Values**:
-
-- `type`: 'alternate'
-- `DURATION_MS`: 300
-- `EASING_FUNCTION`: 'ease-out'
-
-**Example Generations**:
-
-```typescript
-// Card hover with multiple properties
 {
     key: 'portfolio-item',
     trigger: 'hover',
-    params: {
-        type: 'alternate'
-    },
+    params: { type: 'alternate' },
     effects: [
         {
             key: 'portfolio-item',
             keyframeEffect: {
-                name: 'portfolio',
+                name: 'portfolio-lift',
                 keyframes: [
-                    { transform: 'translateY(0)', boxShadow: '0 4px 6px rgba(0,0,0,0.1)', filter: 'brightness(1)' },
-                    { transform: 'translateY(-8px)', boxShadow: '0 20px 25px rgba(0,0,0,0.15)', filter: 'brightness(1.1)' }
+                    { transform: 'translateY(0)', boxShadow: '0 4px 6px rgba(0,0,0,0.1)' },
+                    { transform: 'translateY(-8px)', boxShadow: '0 20px 25px rgba(0,0,0,0.15)' }
                 ]
             },
             fill: 'both',
@@ -269,33 +181,9 @@ This document contains rules for generating hover trigger interactions in `@wix/
         }
     ]
 }
-
-// Image overlay reveal
-{
-    key: 'gallery-image',
-    trigger: 'hover',
-    params: {
-        type: 'alternate'
-    },
-    effects: [
-        {
-            key: 'image-overlay',
-            keyframeEffect: {
-                name: 'image-overlay-slide',
-                keyframes: [
-                    { opacity: '0', transform: 'translateY(100%)' },
-                    { opacity: '1', transform: 'translateY(0)' }
-                ]
-            },
-            fill: 'both',
-            duration: 250,
-            easing: 'ease-out'
-        }
-    ]
-}
 ```
 
-## Rule 4: Hover Interactions with Repeat Pattern
+## Rule 3: Hover Interactions with Repeat Pattern
 
 **Purpose**: Generate hover interactions that restart animation each time mouse enters
 
@@ -303,14 +191,14 @@ This document contains rules for generating hover trigger interactions in `@wix/
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'hover',
     params: {
         type: 'repeat'
     },
     effects: [
         {
-            key: '[TARGET_IDENTIFIER]',
+            key: '[TARGET_KEY]',
             [EFFECT_TYPE]: [EFFECT_DEFINITION],
             duration: [DURATION_MS],
             easing: '[EASING_FUNCTION]'
@@ -384,7 +272,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
 }
 ```
 
-## Rule 5: Hover Interactions with Play/Pause Pattern
+## Rule 4: Hover Interactions with Play/Pause Pattern
 
 **Purpose**: Generate hover interactions that pause/resume on hover (state-based control)
 
@@ -392,14 +280,14 @@ This document contains rules for generating hover trigger interactions in `@wix/
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'hover',
     params: {
         type: 'state'
     },
     effects: [
         {
-            key: '[TARGET_IDENTIFIER]',
+            key: '[TARGET_KEY]',
             [EFFECT_TYPE]: [EFFECT_DEFINITION],
             duration: [DURATION_MS],
             iterations: Infinity,
@@ -475,7 +363,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
 }
 ```
 
-## Rule 6: Multi-Target Hover Effects
+## Rule 5: Multi-Target Hover Effects
 
 **Purpose**: Generate hover interactions that affect multiple elements from a single source
 
@@ -483,7 +371,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
 
 ```typescript
 {
-    key: '[SOURCE_IDENTIFIER]',
+    key: '[SOURCE_KEY]',
     trigger: 'hover',
     params: {
         type: '[BEHAVIOR_TYPE]'
@@ -512,7 +400,7 @@ This document contains rules for generating hover trigger interactions in `@wix/
 **Variables**:
 
 - `[BEHAVIOR_TYPE]`: type of behavior for the effect. use `alternate`, `repeat`, or `state` according to the previous rules.
-- `[FILL_N]`: Optional fill value for the Nth effect - same ass CSS animation-fill-mode (e.g. 'both', 'forwards', 'backwards').
+- `[FILL_N]`: Optional fill value for the Nth effect - same as CSS animation-fill-mode (e.g. 'both', 'forwards', 'backwards').
 - `[REVERSED_BOOL_N]`: Same as `[REVERSED_BOOL]` from Rule 2 only for the Nth effect.
 - `[DURATION_N]`: Same as `[DURATION_MS]` from Rule 1 only for the Nth effect.
 - `[DELAY_N]`: Delay in milliseconds of the Nth effect.
@@ -596,12 +484,85 @@ This document contains rules for generating hover trigger interactions in `@wix/
 }
 ```
 
+## Rule 6: Hover with Sequence (Staggered Multi-Target)
+
+**Purpose**: Hover interactions that stagger animations across multiple targets using a sequence instead of manual delays.
+
+**When to Apply**:
+
+- When hovering a container should stagger-animate its children
+- For list item hover effects with coordinated timing
+- When you want easing-controlled stagger on hover
+
+**Pattern**:
+
+```typescript
+{
+    key: '[SOURCE_KEY]',
+    trigger: 'hover',
+    params: {
+        type: 'repeat'
+    },
+    sequences: [
+        {
+            offset: [OFFSET_MS],
+            offsetEasing: '[OFFSET_EASING]',
+            effects: [
+                {
+                    effectId: '[EFFECT_ID]',
+                    listContainer: '[LIST_CONTAINER_SELECTOR]'
+                }
+            ]
+        }
+    ]
+}
+```
+
+**Example - Hover Card Grid Stagger**:
+
+```typescript
+{
+    key: 'card-grid',
+    trigger: 'hover',
+    params: { type: 'repeat' },
+    sequences: [
+        {
+            offset: 80,
+            offsetEasing: 'sineOut',
+            effects: [
+                {
+                    effectId: 'item-pop',
+                    listContainer: '.card-grid-items'
+                }
+            ]
+        }
+    ]
+}
+```
+
+```typescript
+effects: {
+    'item-pop': {
+        duration: 400,
+        easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+        keyframeEffect: {
+            name: 'item-pop',
+            keyframes: [
+                { transform: 'translateY(16px) scale(0.95)', opacity: 0 },
+                { transform: 'translateY(0) scale(1)', opacity: 1 }
+            ]
+        }
+    }
+}
+```
+
+---
+
 ## Best Practices for Hover Rules
 
-### Performance Guidelines
+### Timing and Pattern Guidelines
 
 1. **Keep durations short** (100-400ms) for responsiveness
-2. **Avoid animating layout properties**: width, height, margin, padding
 
 ### User Experience Guidelines
 
@@ -623,3 +584,31 @@ This document contains rules for generating hover trigger interactions in `@wix/
 - **Interactive elements**: 'ease-in-out' (smooth both ways)
 - **Attention effects**: 'ease-in-out' (natural feel)
 - **Continuous motion**: 'linear' (consistent speed)
+
+## Accessibility
+
+Use `@wix/interact`'s `conditions` API to skip hover animations for users who prefer reduced motion. Define a `prefers-motion` condition and reference it on any interaction that should be suppressed:
+
+```typescript
+{
+  conditions: {
+    'prefers-motion': { type: 'media', predicate: '(prefers-reduced-motion: no-preference)' }
+  },
+  interactions: [
+    {
+      key: 'card',
+      trigger: 'hover',
+      conditions: ['prefers-motion'],  // skipped when reduced-motion is preferred
+      effects: [/* ... */]
+    }
+  ]
+}
+```
+
+For pointer-primary devices only, also consider adding a `hover-capable` condition:
+
+```typescript
+'hover-capable': { type: 'media', predicate: '(hover: hover)' }
+```
+
+Use `trigger: 'interest'` instead of `'hover'` to also handle keyboard focus, which is the accessible equivalent of hover.