From c38e05209f7e8ad75295da3e622bf6605851a217 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Tue, 20 Jan 2026 11:40:50 +0200 Subject: [PATCH 01/20] Add LLM rules for motion presets (pilot batch) Generate structured rule files to help LLMs understand and recommend motion presets. Includes 15 pilot files across all 5 categories for format validation: - entrance: FadeIn, ArcIn, BounceIn - scroll: ParallaxScroll, FadeScroll, ArcScroll - ongoing: Pulse, Bounce, Spin - mouse: Tilt3DMouse, TrackMouse, BounceMouse - background-scroll: BgParallax, BgZoom, BgFade Each rule contains: synonyms, visual description, when to use/not use, TypeScript parameters with constraints, minimal examples, and related presets. --- packages/motion-presets/rules/presets/PLAN.md | 457 ++++++++++++++++++ .../presets/background-scroll/bg-fade.md | 101 ++++ .../presets/background-scroll/bg-parallax.md | 102 ++++ .../presets/background-scroll/bg-zoom.md | 106 ++++ .../rules/presets/entrance/arc-in.md | 107 ++++ .../rules/presets/entrance/bounce-in.md | 114 +++++ .../rules/presets/entrance/fade-in.md | 97 ++++ .../rules/presets/mouse/bounce-mouse.md | 108 +++++ .../rules/presets/mouse/tilt-3d-mouse.md | 115 +++++ .../rules/presets/mouse/track-mouse.md | 118 +++++ .../rules/presets/ongoing/bounce.md | 110 +++++ .../rules/presets/ongoing/pulse.md | 109 +++++ .../rules/presets/ongoing/spin.md | 113 +++++ .../rules/presets/scroll/arc-scroll.md | 105 ++++ .../rules/presets/scroll/fade-scroll.md | 106 ++++ .../rules/presets/scroll/parallax-scroll.md | 105 ++++ 16 files changed, 2073 insertions(+) create mode 100644 packages/motion-presets/rules/presets/PLAN.md create mode 100644 packages/motion-presets/rules/presets/background-scroll/bg-fade.md create mode 100644 packages/motion-presets/rules/presets/background-scroll/bg-parallax.md create mode 100644 packages/motion-presets/rules/presets/background-scroll/bg-zoom.md create mode 100644 packages/motion-presets/rules/presets/entrance/arc-in.md create mode 100644 packages/motion-presets/rules/presets/entrance/bounce-in.md create mode 100644 packages/motion-presets/rules/presets/entrance/fade-in.md create mode 100644 packages/motion-presets/rules/presets/mouse/bounce-mouse.md create mode 100644 packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md create mode 100644 packages/motion-presets/rules/presets/mouse/track-mouse.md create mode 100644 packages/motion-presets/rules/presets/ongoing/bounce.md create mode 100644 packages/motion-presets/rules/presets/ongoing/pulse.md create mode 100644 packages/motion-presets/rules/presets/ongoing/spin.md create mode 100644 packages/motion-presets/rules/presets/scroll/arc-scroll.md create mode 100644 packages/motion-presets/rules/presets/scroll/fade-scroll.md create mode 100644 packages/motion-presets/rules/presets/scroll/parallax-scroll.md diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md new file mode 100644 index 00000000..e7dc2840 --- /dev/null +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -0,0 +1,457 @@ +--- +name: Generate LLM Preset Rules +overview: Create concise, structured rule files for all 83 motion presets to help LLMs understand when to use each preset and generate appropriate implementation code. +todos: + - id: setup + content: Create directory structure and copy plan to rules/presets/ + status: in_progress + - id: pilot-entrance + content: "PILOT: Generate 2-3 entrance rules (FadeIn, ArcIn, BounceIn) for review" + status: pending + - id: pilot-scroll + content: "PILOT: Generate 2-3 scroll rules (ParallaxScroll, FadeScroll, ArcScroll)" + status: pending + - id: pilot-ongoing + content: "PILOT: Generate 2-3 ongoing rules (Pulse, Bounce, Spin)" + status: pending + - id: pilot-mouse + content: "PILOT: Generate 2-3 mouse rules (Tilt3DMouse, TrackMouse, BounceMouse)" + status: pending + - id: pilot-background + content: "PILOT: Generate 2-3 background-scroll rules (BgParallax, BgZoom, BgFade)" + status: pending + - id: review + content: Review pilot files with user, adjust format if needed + status: pending + - id: generate-remaining + content: Generate remaining ~70 preset rule files + status: pending + - id: create-index + content: Create master index/README in rules/presets/ + status: pending +--- + +# Generate LLM Rules for Motion Presets + +## Execution Phases + +### Phase 1: Pilot (Current) + +Generate 2-3 sample rule files per category to validate format: + +| Category | Pilot Presets | + +|----------|---------------| + +| entrance | FadeIn, ArcIn, BounceIn | + +| scroll | ParallaxScroll, FadeScroll, ArcScroll | + +| ongoing | Pulse, Bounce, Spin | + +| mouse | Tilt3DMouse, TrackMouse, BounceMouse | + +| background-scroll | BgParallax, BgZoom, BgFade | + +**Total pilot files: ~14 files** + +### Phase 2: Review + +Review pilot files, adjust format based on feedback. + +### Phase 3: Complete Generation + +Generate remaining ~70 preset rule files + master index. + +--- + +## Structure Overview + +Create rule markdown files mirroring the docs structure: + +- `rules/presets/entrance/` (24 presets) +- `rules/presets/scroll/` (20 presets) +- `rules/presets/ongoing/` (14 presets) +- `rules/presets/mouse/` (13 presets) +- `rules/presets/background-scroll/` (12 presets) + +## Rule File Format + +Each rule file will be optimized for LLM token efficiency. + +--- + +### 1. Header (YAML frontmatter) + +```yaml +name: PresetName +category: entrance | scroll | ongoing | mouse | backgroundScroll +tags: [tag1, tag2, tag3, ...] # Semantic search keywords +``` + +Tags are searchable intent keywords to help LLM match user requests: + +- Motion type: `fade`, `slide`, `rotate`, `scale`, `3d`, `blur` +- Tone: `subtle`, `dramatic`, `playful`, `professional` +- Context: `entrance`, `hero`, `modal`, `cards`, `list-items` + +--- + +### 2. Synonyms + +Natural language variations to help LLM match user intent (3-7 alternatives): + +```markdown +## Synonyms +fade in, appear, materialize, opacity transition, gentle reveal +``` + +--- + +### 3. Visual Description (Human-written) + +**This section requires manual writing.** Describe exactly what the user SEES with specific cues: + +- **Opacity**: Does it fade? From what to what? +- **Movement**: Direction, distance, path (straight, curved, arc) +- **Rotation**: Axis (X, Y, Z), degrees, perspective +- **Scale**: Grows, shrinks, from what size? +- **Timing feel**: Smooth, bouncy, snappy, elastic + +Example for ArcIn: + +> Element swings into view along a curved 3D arc path. Starts rotated on an axis (determined by direction), then rotates back to flat while moving along the arc. Includes a fade from transparent to opaque during the first 70% of the animation. Creates a dramatic, cinematic reveal with depth. + +--- + +### 4. When to Use + +Bulleted decision criteria for LLM to recommend this preset: + +- User intent keywords (what they might ask for) +- Content type suitability (hero, cards, text, images) +- Design context (landing page, modal, dashboard) +- Emotional/brand tone match + +Include **confidence scenarios** inline: + +```markdown +- Hero sections requiring dramatic entrance (high confidence) +- Modal content reveal (medium confidence - consider FadeIn for subtler effect) +``` + +--- + +### 5. When NOT to Use + +Anti-patterns and limitations: + +- Accessibility concerns (vestibular, motion sensitivity) +- Performance issues (many elements, mobile) +- Design mismatches (too dramatic for subtle UI) +- Better alternatives (suggest specific presets) + +--- + +### 6. Parameters + +**Use TypeScript notation.** Pull min/max/step/enum from `@wix/effects-kit` ([wix-private/wow-libs/effects-kit](https://github.com/wix-private/wow-libs/tree/master/packages/effects-kit)). + +**IMPORTANT: Parameter Subsets Vary Per Preset** + +Different presets support different subsets of enum values: + +**Direction variants:** + +- `EffectFourDirections`: `'top' | 'right' | 'bottom' | 'left'` +- `EffectFiveDirections`: adds `'center'` +- `EffectEightDirections`: adds diagonals `'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'` +- `EffectNineDirections`: eight + `'center'` +- `EffectFourCorners`: `'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'` +- `EffectTwoDirections`: `'left' | 'right'` +- `EffectTwoAxes`: `'horizontal' | 'vertical'` + +**Easing variants:** + +- Full easing set available for most presets +- **Clipped/masked animations** (ShapeIn, RevealIn, ShuttersIn, etc.) exclude `backOut`, `backIn`, `backInOut` because overshoot breaks the clip boundary +- Some presets have preset-specific easing maps tied to `power` levels + +Always document the **exact subset** supported by each preset, not the base type. + +Example: + +```typescript +interface ArcIn { + direction: 'top' | 'right' | 'bottom' | 'left'; // EffectFourDirections, default: 'left' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + // Inherited from base + duration?: number; // min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // min: 0, max: 8000, step: 100, default: 0 + easing?: Easing; // default: 'quintInOut' +} +``` + +Add brief impact notes: + +- `direction`: Determines rotation axis and arc path origin +- `power`: Controls rotation intensity (soft: 15°, medium: 30°, hard: 45°) + +--- + +### 7. Minimal Examples + +2-3 terse, copy-paste ready snippets: + +```typescript +// Basic - minimal config +{ type: 'ArcIn', direction: 'bottom' } + +// Dramatic hero entrance +{ type: 'ArcIn', direction: 'bottom', power: 'hard' } +// with: duration: 1400, easing: 'quintOut' + +// Subtle side panel +{ type: 'ArcIn', direction: 'left', power: 'soft' } +// with: duration: 800 +``` + +--- + +### 8. Related Presets + +**Specifically highlight parallel presets across triggers:** + +```markdown +## Related Presets + +### Same Category (Entrance) +- **FlipIn** - Simpler 3D flip without arc motion +- **TurnIn** - Corner-based 3D rotation, more complex + +### Parallel in Other Triggers +- **ArcScroll** (scroll) - Same arc motion, scroll-driven +- **TiltScroll** (scroll) - Similar 3D tilt, scroll-driven + +### Alternatives +- **FadeIn** - When subtle is needed over dramatic +- **SlideIn** - When 2D motion is preferred over 3D +``` + +--- + +### 9. Decision Hints (Optional) + +Help LLM navigate similar presets: + +```yaml +choose_this_when: + - "user wants 3D dramatic entrance" + - "hero section needs cinematic reveal" + - "premium/luxury brand feel" + +choose_alternative_when: + - "subtle needed" → FadeIn, BlurIn + - "2D motion preferred" → SlideIn, GlideIn + - "playful/bouncy" → BounceIn + - "scroll-driven" → ArcScroll +``` + +--- + +## Data Sources + +### From `motion-presets/src/types.ts` + +- TypeScript interface definitions +- Parameter types and optionality + +### From `motion-presets/src/library/{category}/{Preset}.ts` + +- Default values in implementation +- Keyframe analysis for visual description cues +- Easing maps + +### From `effects-kit/src/effects/{category}/{preset}.ts` + +- `min`, `max`, `step` constraints +- `enum` options (check each preset - they override base enums!) +- `default` and `mobileDefault` values +- `units` for number-with-unit types +- Preset-specific schema overrides + +### From `effects-kit/src/effects/baseParams.ts` + +Common parameters (but presets may use subsets): + +- `duration`: min: 0, max: 4000, step: 100 +- `delay`: min: 0, max: 8000, step: 100 +- `power`: enum: `['soft', 'medium', 'hard']` +- `easing`: full set (but clipped animations exclude `back*` easings) + +**Direction base types:** + +- `directionFourSides`: `['left', 'right', 'top', 'bottom']` +- `directionFiveSides`: four + `'center'` +- `directionEightSides`: four + diagonals +- `directionNineSides`: eight + `'center'` +- `directionFourCorners`: `['top-left', 'top-right', 'bottom-left', 'bottom-right']` +- `directionTwoSides`: `['left', 'right']` +- `directionTwoAxes`: `['horizontal', 'vertical']` + +**Easing base types:** + +- `easing`: full set including `backIn`, `backOut`, `backInOut` +- `easingExcludingBackOut`: for clipped/masked animations + +--- + +## Sample Rule File + +> **See**: [rules/presets/entrance/arc-in.md](rules/presets/entrance/arc-in.md) after generation + +
+ +Click to expand full sample: arc-in.md + +**Frontmatter:** + +```yaml +name: ArcIn +category: entrance +tags: [3d, arc, curved, dramatic, cinematic, perspective, rotation, entrance] +``` + +**Synonyms:** + +> arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective reveal + +**Visual Description:** + +> Element swings into view along a curved 3D arc path. Starts rotated on an axis (X for top/bottom, Y for left/right) then rotates back to flat while moving along the arc. Includes opacity fade from 0 to 1 during the first 70% of animation. The perspective (800px) creates depth. Power level controls rotation intensity: soft ~15°, medium ~30°, hard ~45°. Movement feels smooth and cinematic with quintInOut easing. + +**When to Use:** + +- Hero sections requiring dramatic, cinematic entrance (high confidence) +- Premium product showcases where depth and drama matter +- Portfolio pieces and creative presentations +- Featured content that needs to stand out +- Modal content reveal (medium confidence - consider FadeIn for subtler effect) + +**When NOT to Use:** + +- Multiple simultaneous elements (performance concern) +- Users with vestibular sensitivity (reduced-motion alternative: FadeIn) +- Subtle, professional interfaces where drama is inappropriate +- Mobile with many animated elements +- When 2D motion would suffice (use SlideIn, GlideIn instead) + +**Parameters:** + +```typescript +interface ArcIn { + direction: 'top' | 'right' | 'bottom' | 'left'; // EffectFourDirections, default: 'left' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + duration?: number; // min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // min: 0, max: 8000, step: 100, default: 0 + easing?: Easing; // full set supported, default: 'quintInOut' +} +``` + +**Parameter Impact:** + +- `direction`: Determines rotation axis (top/bottom = X-axis, left/right = Y-axis) and arc origin +- `power`: Rotation intensity - soft: subtle tilt, medium: noticeable arc, hard: dramatic swing + +**Minimal Examples:** + +```typescript +// Basic +{ type: 'ArcIn', direction: 'bottom' } + +// Dramatic hero +{ type: 'ArcIn', direction: 'bottom', power: 'hard' } +// duration: 1400, easing: 'quintOut' + +// Subtle side entry +{ type: 'ArcIn', direction: 'left', power: 'soft' } +// duration: 800 +``` + +**Related Presets:** + +| Category | Preset | Comparison | + +|----------|--------|------------| + +| Same (Entrance) | FlipIn | Simpler 3D flip, no arc path | + +| Same (Entrance) | TurnIn | Corner-based 3D rotation | + +| Same (Entrance) | CurveIn | Alternative curved 3D motion | + +| Parallel (Scroll) | ArcScroll | Arc motion driven by scroll position | + +| Parallel (Scroll) | TiltScroll | 3D tilt on scroll | + +| Alternative | FadeIn | When subtle is needed | + +| Alternative | SlideIn | When 2D motion preferred | + +| Alternative | GlideIn | Smooth 2D glide with direction control | + +**Decision Hints:** + +```yaml +choose_this_when: + - "dramatic 3D entrance needed" + - "hero/featured content" + - "cinematic feel" + - "premium brand" + +choose_alternative_when: + - subtle_needed: FadeIn, BlurIn + - 2d_preferred: SlideIn, GlideIn + - playful_bouncy: BounceIn + - scroll_driven: ArcScroll +``` + +
+ +--- + +## File Organization + +``` +rules/presets/ +├── README.md # Master index +├── entrance/ # 24 files +│ ├── fade-in.md +│ ├── arc-in.md +│ ├── blur-in.md +│ └── ... +├── scroll/ # 20 files +│ ├── parallax-scroll.md +│ ├── arc-scroll.md +│ └── ... +├── ongoing/ # 14 files +│ ├── pulse.md +│ ├── bounce.md +│ └── ... +├── mouse/ # 13 files +│ ├── tilt-3d-mouse.md +│ └── ... +└── background-scroll/ # 12 files + ├── bg-parallax.md + └── ... +``` + +--- + +## Implementation Notes + +1. **Visual Description**: Requires human writing - analyze keyframes in implementation files for cues about opacity, rotation axes, movement paths, and timing +2. **Parameters**: Combine TypeScript types from `motion-presets` with constraints from `effects-kit`. **Always check each preset's specific file** - they override base params with different enum subsets +3. **Direction/Easing subsets**: Document the exact subset each preset supports, not the base type. Clipped animations (ShapeIn, RevealIn, ShuttersIn, WinkIn) exclude back easings +4. **Cross-trigger mapping**: Map entrance presets to their scroll/mouse equivalents where they exist (e.g., ArcIn ↔ ArcScroll) +5. **Tags**: Derive from visual characteristics, use cases, and motion type \ No newline at end of file diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md new file mode 100644 index 00000000..ccfe23ac --- /dev/null +++ b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md @@ -0,0 +1,101 @@ +--- +name: BgFade +category: backgroundScroll +tags: [fade, background, scroll, opacity, reveal, transition] +--- + +# BgFade + +## Synonyms + +background fade, bg fade, fade background, background opacity, background reveal + +## Visual Description + +Background layer opacity transitions as user scrolls through the section. In `in` range, background fades from transparent (0) to fully visible (1) as element enters viewport and reaches center. In `out` range, background fades from visible to transparent as element exits. Targets the `BG_LAYER` element specifically. Uses `sineIn` easing for fade in, `sineOut` for fade out. Covers the scroll range from element entering viewport to center (in) or center to leaving (out). + +## When to Use + +- Section transitions with background change (high confidence) +- Progressive background reveals +- Layered backgrounds that appear/disappear +- Storytelling with background reveals +- Section dividers with visual transitions +- Creating focus on/off content areas + +## When NOT to Use + +- When background must always be visible +- Critical visual information in background +- Fast-scrolling interfaces +- When abrupt transitions are acceptable +- Mobile with color-only backgrounds (no benefit) + +## Parameters + +```typescript +interface BgFade { + range: 'in' | 'out'; // EffectRangeInOut, required + // Scroll range params + start?: number; // min: 0, max: 100, default: 0 (in) or 50 (out) + end?: number; // min: 0, max: 100, default: 50 (in) or 100 (out) +} +``` + +**Parameter Impact:** + +- `range`: Fade direction + - `in`: Fades from transparent to visible (0→1) on entry + - `out`: Fades from visible to transparent (1→0) on exit +- `start`/`end`: Scroll position range for fade + - For `in`: Default 0-50 (fade completes by viewport center) + - For `out`: Default 50-100 (fade starts from viewport center) + +## Minimal Examples + +```typescript +// Basic - fade in on entry +{ type: 'BgFade', range: 'in' } + +// Fade out on exit +{ type: 'BgFade', range: 'out' } + +// Custom scroll range for earlier fade +{ type: 'BgFade', range: 'in', start: 0, end: 30 } +``` + +## Related Presets + +### Same Category (Background Scroll) + +- **BgFadeBack** - Fade with different layer targeting +- **BgParallax** - Movement without fade +- **BgZoom** - Zoom effect on background + +### Parallel in Other Triggers + +- **FadeScroll** (scroll) - Fade for regular elements +- **FadeIn** (entrance) - Time-based fade entrance + +### Alternatives + +- **BgParallax** - When movement preferred over opacity +- **BgZoom** - When zoom effect preferred +- **FadeScroll** - For regular (non-background) elements + +## Decision Hints + +```yaml +choose_this_when: + - "background reveal/hide" + - "section transitions" + - "layered background effects" + - "focus control via background" + - "progressive disclosure" + +choose_alternative_when: + - movement_based: BgParallax + - zoom_effect: BgZoom + - regular_elements: FadeScroll + - time_based: FadeIn +``` diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md new file mode 100644 index 00000000..f894a32f --- /dev/null +++ b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md @@ -0,0 +1,102 @@ +--- +name: BgParallax +category: backgroundScroll +tags: [parallax, background, scroll, depth, continuous, vertical] +--- + +# BgParallax + +## Synonyms + +background parallax, bg parallax, background scroll, parallax background, depth background + +## Visual Description + +Background media (image or video) moves vertically at a different rate than content scroll, creating depth illusion. Uses `translateY` on the `BG_MEDIA` element. With default speed (0.2), background moves slowly relative to scroll - positive values move background in scroll direction, creating effect of background being "further away". Runs continuously through entire element visibility (`cover` timeline). More subtle than element parallax due to lower default speed. + +## When to Use + +- Hero sections with depth (high confidence) +- Full-width section backgrounds +- Landing pages with visual richness +- Storytelling pages with immersive feel +- Section separators with visual interest +- Photography portfolio backgrounds + +## When NOT to Use + +- Content-heavy sections (distracting) +- Mobile with performance concerns +- Backgrounds with important visual details (may be cropped) +- When background position precision matters +- Accessibility-focused sites (motion concerns) +- Color-only backgrounds (no visual benefit) + +## Parameters + +```typescript +interface BgParallax { + speed?: number; // min: 0.05, max: 0.95, step: 0.01, default: 0.2 + range?: 'continuous'; // only continuous supported +} +``` + +**Parameter Impact:** + +- `speed`: Rate of background movement (0.05-0.95) + - Lower values (0.1-0.2): Subtle, barely noticeable parallax + - Medium values (0.3-0.5): Noticeable depth effect + - Higher values (0.6-0.95): Dramatic, pronounced parallax + - Default 0.2 is subtle and safe for most uses + +## Minimal Examples + +```typescript +// Basic - subtle parallax +{ type: 'BgParallax' } + +// Noticeable depth effect +{ type: 'BgParallax', speed: 0.4 } + +// Very subtle (barely moves) +{ type: 'BgParallax', speed: 0.1 } + +// Dramatic parallax +{ type: 'BgParallax', speed: 0.7 } +``` + +## Related Presets + +### Same Category (Background Scroll) + +- **BgZoom** - Zoom effect on background +- **BgFade** - Fade effect on background +- **BgPan** - Horizontal/vertical pan on background +- **ImageParallax** - For regular images (non-background) + +### Parallel in Other Triggers + +- **ParallaxScroll** (scroll) - Parallax for regular elements + +### Alternatives + +- **ParallaxScroll** - When animating regular elements +- **BgZoom** - When zoom effect preferred +- **BgFade** - When opacity transition preferred + +## Decision Hints + +```yaml +choose_this_when: + - "background depth effect" + - "hero section immersion" + - "section visual interest" + - "landing page polish" + - "image/video backgrounds" + +choose_alternative_when: + - regular_elements: ParallaxScroll + - zoom_effect: BgZoom + - fade_effect: BgFade + - horizontal_pan: BgPan +``` diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md new file mode 100644 index 00000000..e3446d04 --- /dev/null +++ b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md @@ -0,0 +1,106 @@ +--- +name: BgZoom +category: backgroundScroll +tags: [zoom, background, scroll, scale, depth, 3d, perspective] +--- + +# BgZoom + +## Synonyms + +background zoom, bg zoom, zoom scroll, dolly zoom, zoom effect background, ken burns scroll + +## Visual Description + +Background image zooms in or out as user scrolls, creating dramatic depth effect. Uses `perspective` and `translateZ` transforms for true 3D zoom rather than scale. In `in` direction, background starts normal and zooms in (moves towards viewer) as scroll progresses. In `out` direction, background zooms out (moves away). Uses different starting Y positions and easing per direction: `in` starts at 20svh with `sineIn`, `out` starts at 0 with `sineInOut`. Creates cinematic dolly/zoom effect. + +## When to Use + +- Cinematic hero sections (high confidence) +- Dramatic section reveals +- Photography/portfolio showcases +- Landing pages with high visual impact +- Storytelling with depth emphasis +- Single featured image sections + +## When NOT to Use + +- Text-heavy backgrounds (hard to read during zoom) +- Multiple sections with zoom (overwhelming) +- Mobile with performance concerns +- When background details must stay sharp +- Vestibular sensitivity concerns +- Precise background positioning needed + +## Parameters + +```typescript +interface BgZoom { + direction: 'in' | 'out'; // EffectRangeInOut, default: 'in' + zoom?: number; // min: 0.1, max: 10, step: 0.1, default: 10 + range?: 'continuous'; // only continuous supported +} +``` + +**Parameter Impact:** + +- `direction`: Zoom behavior + - `in`: Background zooms in (towards viewer) as scroll progresses + - `out`: Background zooms out (away from viewer), uses 0.375x factor +- `zoom`: Maximum zoom amount (0.1-10) + - Lower values (1-3): Subtle zoom + - Medium values (5-7): Noticeable cinematic zoom + - Higher values (8-10): Dramatic, pronounced zoom + +## Minimal Examples + +```typescript +// Basic - zoom in effect +{ type: 'BgZoom', direction: 'in' } + +// Zoom out as scroll +{ type: 'BgZoom', direction: 'out' } + +// Subtle zoom +{ type: 'BgZoom', direction: 'in', zoom: 3 } + +// Dramatic zoom +{ type: 'BgZoom', direction: 'in', zoom: 10 } +``` + +## Related Presets + +### Same Category (Background Scroll) + +- **BgParallax** - Movement without zoom +- **BgFade** - Opacity-based transition +- **BgCloseUp** - Similar zoom with different implementation +- **BgPullBack** - Reverse zoom effect + +### Parallel in Other Triggers + +- **GrowScroll** (scroll) - Scale effect for regular elements +- **ShrinkScroll** (scroll) - Shrink effect for regular elements + +### Alternatives + +- **BgParallax** - When subtle movement preferred +- **BgCloseUp** - Alternative zoom implementation +- **BgFade** - When opacity transition preferred + +## Decision Hints + +```yaml +choose_this_when: + - "cinematic background effect" + - "dramatic section reveal" + - "hero with depth" + - "photography showcase" + - "dolly zoom feel" + +choose_alternative_when: + - subtle_movement: BgParallax + - opacity_transition: BgFade + - alternative_zoom: BgCloseUp + - regular_elements: GrowScroll +``` diff --git a/packages/motion-presets/rules/presets/entrance/arc-in.md b/packages/motion-presets/rules/presets/entrance/arc-in.md new file mode 100644 index 00000000..11007228 --- /dev/null +++ b/packages/motion-presets/rules/presets/entrance/arc-in.md @@ -0,0 +1,107 @@ +--- +name: ArcIn +category: entrance +tags: [3d, arc, curved, dramatic, cinematic, perspective, rotation, entrance, premium] +--- + +# ArcIn + +## Synonyms + +arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective reveal, dramatic arc + +## Visual Description + +Element swings into view along a curved 3D arc path. Starts rotated on an axis (X-axis for top/bottom directions, Y-axis for left/right) at approximately 80 degrees, then rotates back to flat (0 degrees) while moving along the arc. Uses `perspective(800px)` to create depth. Includes an opacity fade from 0 to 1 during the first 70% of the animation (separate fade animation with `sineIn` easing). The main arc motion uses `quintInOut` easing by default, creating smooth acceleration and deceleration. Power level controls the rotation intensity through different easing curves: soft uses `cubicInOut`, medium uses `quintInOut`, hard uses `backOut` for slight overshoot. + +## When to Use + +- Hero sections requiring dramatic, cinematic entrance (high confidence) +- Premium product showcases where depth and drama matter +- Portfolio pieces and creative presentations +- Featured content that needs to stand out +- Landing page hero elements +- Single focal point elements (not for lists) + +## When NOT to Use + +- Multiple simultaneous elements (performance concern with 3D transforms) +- Users with vestibular sensitivity (provides reduced-motion alternative: FadeIn) +- Subtle, professional interfaces where drama is inappropriate +- Mobile with many animated elements (3D transforms are expensive) +- When 2D motion would suffice (use SlideIn, GlideIn instead) +- List items or repeated content + +## Parameters + +```typescript +interface ArcIn { + direction: 'top' | 'right' | 'bottom' | 'left'; // EffectFourDirections, default: 'left' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + duration?: number; // min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // min: 0, max: 8000, step: 100, default: 0 + easing?: Easing; // full set supported, default: 'quintInOut' +} +``` + +**Parameter Impact:** + +- `direction`: Determines rotation axis and arc origin + - `top`/`bottom`: Rotates on X-axis (tilts forward/backward) + - `left`/`right`: Rotates on Y-axis (tilts sideways) +- `power`: Controls easing curve and perceived intensity + - `soft`: `cubicInOut` - gentle, subtle arc + - `medium`: `quintInOut` - balanced, noticeable arc + - `hard`: `backOut` - dramatic with slight overshoot + +## Minimal Examples + +```typescript +// Basic - element arcs in from the left +{ type: 'ArcIn', direction: 'bottom' } + +// Dramatic hero entrance with overshoot +{ type: 'ArcIn', direction: 'bottom', power: 'hard' } +// with: duration: 1400 + +// Subtle side panel entrance +{ type: 'ArcIn', direction: 'left', power: 'soft' } +// with: duration: 800 +``` + +## Related Presets + +### Same Category (Entrance) + +- **FlipIn** - Simpler 3D flip without arc path, just rotation +- **TurnIn** - Corner-based 3D rotation, more complex pivot point +- **CurveIn** - Alternative curved 3D motion, different path + +### Parallel in Other Triggers + +- **ArcScroll** (scroll) - Arc motion driven by scroll position +- **TiltScroll** (scroll) - 3D tilt on scroll, similar perspective + +### Alternatives + +- **FadeIn** - When subtle is needed, reduced motion fallback +- **SlideIn** - When 2D motion preferred, less dramatic +- **GlideIn** - Smooth 2D glide with angle control + +## Decision Hints + +```yaml +choose_this_when: + - "dramatic 3D entrance needed" + - "hero/featured content" + - "cinematic feel" + - "premium brand" + - "single focal element" + +choose_alternative_when: + - subtle_needed: FadeIn, BlurIn + - 2d_preferred: SlideIn, GlideIn + - playful_bouncy: BounceIn + - scroll_driven: ArcScroll + - simpler_3d: FlipIn +``` diff --git a/packages/motion-presets/rules/presets/entrance/bounce-in.md b/packages/motion-presets/rules/presets/entrance/bounce-in.md new file mode 100644 index 00000000..d6bd6e6d --- /dev/null +++ b/packages/motion-presets/rules/presets/entrance/bounce-in.md @@ -0,0 +1,114 @@ +--- +name: BounceIn +category: entrance +tags: [bounce, playful, energetic, fun, elastic, entrance, attention, spring] +--- + +# BounceIn + +## Synonyms + +bounce entrance, bouncy reveal, spring in, elastic entrance, playful appear, jump in, hop in + +## Visual Description + +Element bounces into view from a specified direction with multiple decreasing bounces before settling. Starts with opacity 0 and full translation (distance based on power), then performs a series of bounces: first bounce reaches 100% distance, then progressively smaller bounces at ~35%, ~21%, ~9%, ~2% of original distance. Each bounce alternates between `sineIn` and `sineOut` easing for realistic physics. The opacity fades in during the first ~54% of the animation with `quadOut` easing. For `center` direction, uses `perspective(800px)` and bounces on Z-axis (towards/away from viewer). Creates a fun, energetic, attention-grabbing entrance. + +## When to Use + +- Playful, fun brand interfaces (high confidence) +- Gamification elements and rewards +- Notification badges or indicators +- Call-to-action buttons that need attention +- Success states and confirmations +- Child-friendly interfaces +- Marketing landing pages with energetic tone + +## When NOT to Use + +- Professional/corporate interfaces (too playful) +- Serious content like error messages or warnings +- Forms and data entry interfaces +- Multiple simultaneous elements (visual noise) +- Users with vestibular sensitivity (bouncing motion) +- When subtle entrance is appropriate + +## Parameters + +```typescript +interface BounceIn { + direction: 'top' | 'right' | 'bottom' | 'left' | 'center'; // EffectFiveDirections, default: 'top' + power?: 'soft' | 'medium' | 'hard'; // default: 'soft' + distanceFactor?: number; // min: 1, max: 4, step: 0.1, default: 1 (responsive only) + duration?: number; // min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // min: 0, max: 8000, step: 100, default: 0 +} +``` + +**Parameter Impact:** + +- `direction`: Origin of the bounce movement + - `top`: Bounces down from above + - `bottom`: Bounces up from below + - `left`/`right`: Bounces horizontally + - `center`: Bounces on Z-axis with 3D perspective (towards viewer) +- `power`: Controls bounce amplitude + - `soft`: Factor 1 - subtle bounces + - `medium`: Factor 2 - noticeable bounces + - `hard`: Factor 3 - dramatic, large bounces +- `distanceFactor`: Fine-grained control over bounce distance (1-4) + +## Minimal Examples + +```typescript +// Basic - bounces down from top +{ type: 'BounceIn', direction: 'top' } + +// Energetic CTA button +{ type: 'BounceIn', direction: 'bottom', power: 'hard' } +// with: duration: 1000 + +// Subtle notification badge +{ type: 'BounceIn', direction: 'center', power: 'soft' } +// with: duration: 800 + +// Custom distance factor +{ type: 'BounceIn', direction: 'left', distanceFactor: 2.5 } +``` + +## Related Presets + +### Same Category (Entrance) + +- **PunchIn** - Similar energy but with scale, corner-based +- **DropIn** - Single drop with scale, no bounce +- **SpinIn** - Rotation-based energetic entrance + +### Parallel in Other Triggers + +- **Bounce** (ongoing) - Continuous bouncing animation +- **BounceMouse** (mouse) - Bouncy response to mouse movement + +### Alternatives + +- **FadeIn** - When subtle is needed, reduced motion fallback +- **SlideIn** - Same directional entrance without bounce +- **DropIn** - Single drop motion, more subtle than bounce + +## Decision Hints + +```yaml +choose_this_when: + - "playful/fun interface" + - "attention-grabbing element" + - "gamification/rewards" + - "energetic brand tone" + - "notification/badge appearance" + +choose_alternative_when: + - professional_tone: FadeIn, SlideIn + - subtle_needed: FadeIn, DropIn + - rotation_based: SpinIn + - scale_emphasis: PunchIn, GrowIn + - continuous_bounce: Bounce (ongoing) +``` diff --git a/packages/motion-presets/rules/presets/entrance/fade-in.md b/packages/motion-presets/rules/presets/entrance/fade-in.md new file mode 100644 index 00000000..ae23b6d2 --- /dev/null +++ b/packages/motion-presets/rules/presets/entrance/fade-in.md @@ -0,0 +1,97 @@ +--- +name: FadeIn +category: entrance +tags: [fade, opacity, subtle, simple, professional, minimal, entrance, appear] +--- + +# FadeIn + +## Synonyms + +fade in, appear, materialize, opacity transition, gentle reveal, soft entrance, dissolve in + +## Visual Description + +Element transitions from fully transparent (opacity 0) to fully visible (opacity 1). No movement, rotation, or scale changes occur - purely an opacity transition. Uses `sineInOut` easing for a smooth, natural feel. The simplest and most universally applicable entrance animation. + +## When to Use + +- Subtle content reveals in professional interfaces (high confidence) +- Modal and overlay appearances where movement would be distracting +- Loading state transitions - content appearing after load +- Progressive disclosure in forms and wizards +- Image galleries revealing loaded images +- Any element requiring gentle, non-distracting introduction +- Fallback for `prefers-reduced-motion` accessibility + +## When NOT to Use + +- When user needs attention drawn to specific element (use more dramatic preset) +- When spatial relationship matters (use SlideIn, GlideIn to show direction) +- Hero sections where impact is needed (use ArcIn, BounceIn) +- When element position context is important + +## Parameters + +```typescript +interface FadeIn { + // No preset-specific parameters + duration?: number; // min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // min: 0, max: 8000, step: 100, default: 0 +} +``` + +**Parameter Impact:** + +- `duration`: Controls how quickly opacity transitions. Shorter (300-500ms) feels snappy, longer (800-1200ms) feels gentle +- `delay`: Useful for staggered reveals in sequences + +## Minimal Examples + +```typescript +// Basic - minimal config +{ type: 'FadeIn' } + +// Quick snappy fade +{ type: 'FadeIn' } +// with: duration: 300 + +// Slow dramatic fade +{ type: 'FadeIn' } +// with: duration: 1500, delay: 200 +``` + +## Related Presets + +### Same Category (Entrance) + +- **BlurIn** - Adds blur-to-focus effect alongside fade +- **DropIn** - Combines fade with subtle scale effect + +### Parallel in Other Triggers + +- **FadeScroll** (scroll) - Opacity transition driven by scroll position +- **BgFade** (background-scroll) - Background-specific fade on scroll + +### Alternatives + +- **BlurIn** - When you want more visual interest than pure fade +- **SlideIn** - When directional context matters +- **GrowIn** - When scale emphasis is needed + +## Decision Hints + +```yaml +choose_this_when: + - "subtle entrance needed" + - "professional/minimal UI" + - "reduced motion fallback" + - "multiple elements appearing" + - "modal/overlay appearance" + +choose_alternative_when: + - attention_needed: BounceIn, PunchIn + - direction_matters: SlideIn, GlideIn + - more_visual_interest: BlurIn, DropIn + - dramatic_hero: ArcIn, FlipIn +``` diff --git a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md new file mode 100644 index 00000000..6f0df8ab --- /dev/null +++ b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md @@ -0,0 +1,108 @@ +--- +name: BounceMouse +category: mouse +tags: [bounce, elastic, mouse, spring, playful, follow, interactive] +--- + +# BounceMouse + +## Synonyms + +bouncy mouse, elastic follow, spring mouse, bouncy cursor effect, elastic tracking + +## Visual Description + +Element follows mouse position with elastic/bouncy easing, creating spring-like motion. Built on TrackMouse foundation but with `elastic` or `bounce` transition easing. When mouse moves, element overshoots its target position then bounces back to settle. Creates playful, game-like interaction feel. Same translation behavior as TrackMouse but with springy physics. + +## When to Use + +- Playful/fun interface elements (high confidence) +- Game-like interactions +- Child-friendly interfaces +- Mascot/character elements following cursor +- Energetic brand interactions +- Interactive easter eggs +- Engaging decorative elements + +## When NOT to Use + +- Professional/corporate interfaces +- Precise interactions needed +- Multiple elements (chaotic) +- Performance-constrained +- Accessibility-focused (motion sensitivity) +- When smooth following is preferred + +## Parameters + +```typescript +interface BounceMouse { + distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // min: 5, max: 800, default: { value: 80, type: 'px' } + axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' + inverted?: boolean; // default: false + transitionDuration?: number; // min: 0, max: 5000, step: 20, default: 500 + transitionEasing?: 'elastic' | 'bounce'; // default: 'elastic' +} +``` + +**Parameter Impact:** + +- `distance`: Maximum translation distance (default 80px, smaller than TrackMouse) +- `axis`: Movement constraint (horizontal, vertical, or both) +- `transitionEasing`: Spring behavior + - `elastic`: Smooth spring with overshoot and settle + - `bounce`: Multiple bounces before settling +- `inverted`: Element bounces away from mouse instead of towards + +## Minimal Examples + +```typescript +// Basic - elastic bounce following +{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } + +// Bounce easing variant +{ type: 'BounceMouse', distance: { value: 100, type: 'px' }, axis: 'both' } +// with: transitionEasing: 'bounce' + +// Horizontal only bounce +{ type: 'BounceMouse', distance: { value: 60, type: 'px' }, axis: 'horizontal' } + +// Inverted bounce (moves away) +{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both', inverted: true } +``` + +## Related Presets + +### Same Category (Mouse) + +- **TrackMouse** - Same tracking without bounce easing +- **ScaleMouse** - Scale-based mouse response +- **Tilt3DMouse** - 3D tilt mouse response + +### Parallel in Other Triggers + +- **BounceIn** (entrance) - Bouncy entrance animation +- **Bounce** (ongoing) - Continuous bounce animation + +### Alternatives + +- **TrackMouse** - When smooth following preferred +- **Tilt3DMouse** - When 3D effect preferred +- **ScaleMouse** - When scale response preferred + +## Decision Hints + +```yaml +choose_this_when: + - "playful mouse interaction" + - "game-like interface" + - "elastic/springy feel" + - "character/mascot following" + - "fun/energetic brand" + +choose_alternative_when: + - smooth_following: TrackMouse + - 3d_effect: Tilt3DMouse + - scale_based: ScaleMouse + - professional_interface: TrackMouse (with easeOut) +``` diff --git a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md new file mode 100644 index 00000000..88e72dee --- /dev/null +++ b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md @@ -0,0 +1,115 @@ +--- +name: Tilt3DMouse +category: mouse +tags: [3d, tilt, mouse, perspective, interactive, hover, rotation] +--- + +# Tilt3DMouse + +## Synonyms + +3d tilt, mouse tilt, perspective tilt, interactive tilt, hover tilt, card tilt, gyroscope effect + +## Visual Description + +Element tilts in 3D space following mouse position within the tracking area. Uses `perspective` and `rotateX`/`rotateY` transforms to create depth. When mouse is at center, element is flat (0° rotation). Moving mouse left/right tilts element on Y-axis; moving up/down tilts on X-axis. Maximum tilt angle controlled by power/angle parameter. Perspective distance affects depth perception. Optional smooth transition easing when mouse moves. Inverted mode reverses tilt direction. + +## When to Use + +- Interactive cards and product displays (high confidence) +- Hero sections with depth effect +- Image galleries with hover enhancement +- Portfolio thumbnails +- Call-to-action buttons with premium feel +- Game-like interfaces +- 3D showcase elements + +## When NOT to Use + +- Text-heavy content (readability issues during tilt) +- Mobile devices (no mouse, use device orientation instead) +- Accessibility-focused interfaces +- Multiple overlapping elements +- When precise click targeting is needed +- Performance-constrained environments + +## Parameters + +```typescript +interface Tilt3DMouse { + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + angle?: number; // min: 5, max: 85, step: 1, default: 50 (responsive) + perspective?: number; // min: 200, max: 1000, step: 50, default: 1000 (base) / 800 (impl) + inverted?: boolean; // default: false + transitionDuration?: number; // min: 0, max: 5000, step: 20, default: 500 + transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' +} +``` + +**Parameter Impact:** + +- `power`: Preset combinations of angle + perspective + easing + - `soft`: 25° angle, 1000px perspective - subtle tilt + - `medium`: 50° angle, 500px perspective - noticeable tilt + - `hard`: 85° angle, 200px perspective - dramatic tilt +- `angle`: Maximum rotation degrees (5-85) +- `perspective`: 3D depth perception (lower = more dramatic) +- `inverted`: Reverses tilt direction (element tilts away from mouse) +- `transitionDuration`: Smoothing delay for tilt changes +- `transitionEasing`: Easing curve for transitions + +## Minimal Examples + +```typescript +// Basic - medium tilt +{ type: 'Tilt3DMouse' } + +// Subtle card tilt +{ type: 'Tilt3DMouse', power: 'soft' } +// with: transitionDuration: 300 + +// Dramatic interactive element +{ type: 'Tilt3DMouse', power: 'hard' } +// with: transitionDuration: 200 + +// Custom angle with inverted +{ type: 'Tilt3DMouse', angle: 30, inverted: true } +// with: perspective: 600 +``` + +## Related Presets + +### Same Category (Mouse) + +- **Track3DMouse** - Translation + rotation, different effect +- **SwivelMouse** - Rotation following mouse angle + +### Parallel in Other Triggers + +- **TiltScroll** (scroll) - 3D tilt driven by scroll +- **ArcScroll** (scroll) - Arc rotation on scroll +- **TiltIn** (entrance) - One-time tilt entrance + +### Alternatives + +- **TrackMouse** - When translation preferred over rotation +- **ScaleMouse** - When scale effect preferred +- **SwivelMouse** - When rotation around Z-axis preferred + +## Decision Hints + +```yaml +choose_this_when: + - "interactive 3D card effect" + - "product hover enhancement" + - "premium/gaming interface" + - "depth/perspective on hover" + - "gyroscope-like effect" + +choose_alternative_when: + - translation_preferred: TrackMouse + - scale_effect: ScaleMouse + - z_rotation: SwivelMouse + - scroll_driven: TiltScroll + - mobile_device: (use device orientation) +``` diff --git a/packages/motion-presets/rules/presets/mouse/track-mouse.md b/packages/motion-presets/rules/presets/mouse/track-mouse.md new file mode 100644 index 00000000..2cd246c9 --- /dev/null +++ b/packages/motion-presets/rules/presets/mouse/track-mouse.md @@ -0,0 +1,118 @@ +--- +name: TrackMouse +category: mouse +tags: [track, follow, mouse, movement, translate, interactive, cursor] +--- + +# TrackMouse + +## Synonyms + +mouse tracking, follow cursor, cursor follow, mouse movement, parallax mouse, floating follow + +## Visual Description + +Element translates (moves) to follow mouse position within tracking area. Mouse at center = element at original position. Moving mouse towards edges translates element in same (or opposite if inverted) direction. Distance parameter controls maximum translation distance. Axis parameter limits movement to horizontal, vertical, or both. Optional transition smoothing creates fluid following effect rather than instant tracking. + +## When to Use + +- Parallax-like mouse effects (high confidence) +- Interactive backgrounds with depth layers +- Floating elements that follow cursor +- Decorative elements responding to mouse +- Interactive hero sections +- Game-like cursor interactions +- Creating depth with multiple layers at different distances + +## When NOT to Use + +- Elements that need precise positioning +- Interactive/clickable elements (confusing hit targets) +- Text content (hard to read while moving) +- Mobile devices (no mouse) +- Performance-constrained with many elements +- When accessibility is priority + +## Parameters + +```typescript +interface TrackMouse { + distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // min: 5, max: 800, default: { value: 250, type: 'px' } + axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + inverted?: boolean; // default: false + transitionDuration?: number; // min: 0, max: 5000, step: 20, default: 500 + transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' +} +``` + +**Parameter Impact:** + +- `distance`: Maximum translation distance from center + - Higher values = element moves further + - Different units for responsive behavior +- `axis`: Movement constraint + - `both`: Moves in 2D following cursor + - `horizontal`: Only left/right movement + - `vertical`: Only up/down movement +- `power`: Affects easing + - `soft`: Linear easing + - `medium`: `easeOut` + - `hard`: `hardBackOut` (slight overshoot) +- `inverted`: Element moves opposite to mouse direction + +## Minimal Examples + +```typescript +// Basic - follows mouse +{ type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } + +// Horizontal only parallax +{ type: 'TrackMouse', distance: { value: 100, type: 'px' }, axis: 'horizontal' } +// with: transitionDuration: 300 + +// Inverted (moves away from mouse) +{ type: 'TrackMouse', distance: { value: 150, type: 'px' }, axis: 'both', inverted: true } + +// Large range with smooth transition +{ type: 'TrackMouse', distance: { value: 400, type: 'px' }, axis: 'both' } +// with: transitionDuration: 600, transitionEasing: 'easeOut' +``` + +## Related Presets + +### Same Category (Mouse) + +- **Tilt3DMouse** - 3D rotation instead of translation +- **Track3DMouse** - Combined translation + rotation +- **BounceMouse** - Tracking with elastic easing + +### Parallel in Other Triggers + +- **ParallaxScroll** (scroll) - Parallax on scroll instead of mouse +- **MoveScroll** (scroll) - Movement on scroll +- **GlideIn** (entrance) - Directional entrance animation + +### Alternatives + +- **Tilt3DMouse** - When 3D rotation preferred +- **BounceMouse** - When bouncy/elastic feel wanted +- **ScaleMouse** - When scale effect preferred + +## Decision Hints + +```yaml +choose_this_when: + - "element follows cursor" + - "parallax mouse effect" + - "floating/hovering elements" + - "depth layers on mouse" + - "decorative cursor interaction" + +choose_alternative_when: + - 3d_tilt: Tilt3DMouse + - bouncy_elastic: BounceMouse + - scale_effect: ScaleMouse + - z_rotation: SwivelMouse + - scroll_based: ParallaxScroll +``` diff --git a/packages/motion-presets/rules/presets/ongoing/bounce.md b/packages/motion-presets/rules/presets/ongoing/bounce.md new file mode 100644 index 00000000..170b77fb --- /dev/null +++ b/packages/motion-presets/rules/presets/ongoing/bounce.md @@ -0,0 +1,110 @@ +--- +name: Bounce +category: ongoing +tags: [bounce, vertical, movement, playful, continuous, attention, jump] +--- + +# Bounce + +## Synonyms + +bouncing, jumping, hopping, vertical bounce, continuous bounce, bouncy animation + +## Visual Description + +Element continuously bounces up and down with realistic physics-based motion. Keyframe sequence simulates gravity: rises quickly to peak (-98px at highest), falls back, bounces smaller (-55px), repeats with decreasing amplitude (-23px, -5px, -2px) before settling and restarting. Uses `sineOut` easing for natural acceleration/deceleration. Power/intensity controls the bounce height multiplier (factor 1-3). Creates playful, energetic continuous motion. + +## When to Use + +- Playful/fun interface elements (high confidence) +- Gamification indicators +- "Jump here" attention indicators +- Waiting states with personality +- Interactive elements in games +- Child-friendly interfaces +- Mascots or character elements + +## When NOT to Use + +- Professional/corporate interfaces (too playful) +- Text content (hard to read) +- Multiple simultaneous elements (chaotic) +- Serious contexts (warnings, errors) +- Accessibility concerns (motion sensitivity) +- When subtle attention is needed + +## Parameters + +```typescript +interface Bounce { + power?: 'soft' | 'medium' | 'hard'; // default: 'soft' + intensity?: number; // min: 0, max: 1, step: 0.1, default: 0.3 (responsive) + duration?: number; // min: 100, max: 4000, step: 100, default: 1200 + delay?: number; // min: 0, max: 8000, step: 100, default: 1000 +} +``` + +**Parameter Impact:** + +- `power`: Preset bounce height multipliers + - `soft`: Factor 1 - subtle bounces (~49px max height) + - `medium`: Factor 2 - noticeable bounces (~98px) + - `hard`: Factor 3 - dramatic bounces (~147px) +- `intensity`: Fine-grained control (0-1), maps to factor 1-3 +- `delay`: Pause before bounce cycle starts +- `duration`: Full bounce cycle time + +## Minimal Examples + +```typescript +// Basic - gentle bounce +{ type: 'Bounce' } + +// Energetic bounce +{ type: 'Bounce', power: 'medium' } +// with: duration: 1000 + +// Dramatic attention bounce +{ type: 'Bounce', power: 'hard' } +// with: duration: 1500 + +// Custom intensity +{ type: 'Bounce', intensity: 0.6 } +``` + +## Related Presets + +### Same Category (Ongoing) + +- **Pulse** - Scale-based instead of movement +- **Swing** - Rotation-based oscillation +- **Wiggle** - Horizontal movement oscillation + +### Parallel in Other Triggers + +- **BounceIn** (entrance) - One-time bounce entrance +- **BounceMouse** (mouse) - Bouncy response to mouse + +### Alternatives + +- **Pulse** - When scale-based attention preferred +- **Swing** - When rotation preferred +- **Wiggle** - When horizontal movement preferred + +## Decision Hints + +```yaml +choose_this_when: + - "playful/fun interface" + - "gamification element" + - "energetic attention" + - "character/mascot animation" + - "vertical movement needed" + +choose_alternative_when: + - scale_based: Pulse + - rotation_based: Swing, Spin + - horizontal: Wiggle + - subtle_attention: Pulse (soft) + - one_time: BounceIn +``` diff --git a/packages/motion-presets/rules/presets/ongoing/pulse.md b/packages/motion-presets/rules/presets/ongoing/pulse.md new file mode 100644 index 00000000..b1c89c8d --- /dev/null +++ b/packages/motion-presets/rules/presets/ongoing/pulse.md @@ -0,0 +1,109 @@ +--- +name: Pulse +category: ongoing +tags: [pulse, scale, attention, heartbeat, throb, continuous, subtle] +--- + +# Pulse + +## Synonyms + +pulse effect, heartbeat, throb, breathing, scale pulse, attention pulse, pulsing + +## Visual Description + +Element continuously scales down and back up in a heartbeat-like pattern. Keyframe sequence: starts at scale 1, shrinks to ~0.96 at 27%, returns to 1 at 45%, shrinks further to ~0.93 at 72%, returns to 1 at 100%. The shrink amount is controlled by power/intensity - higher values create more pronounced shrinking. Uses linear easing overall with calculated offsets based on duration/delay ratio. Creates subtle, continuous attention-drawing effect without being distracting. + +## When to Use + +- Drawing attention to important elements (high confidence) +- Live/active status indicators +- Notification badges that need visibility +- Call-to-action buttons (subtle) +- "Heartbeat" effect for health/life indicators +- Breathing/living element feel +- Waiting/processing states + +## When NOT to Use + +- Multiple elements simultaneously (overwhelming) +- Primary content areas (distracting) +- Fast-paced interfaces (adds visual noise) +- When user needs to focus on content +- Accessibility concerns (repetitive motion) +- Professional/minimal interfaces (can feel gimmicky) + +## Parameters + +```typescript +interface Pulse { + power?: 'soft' | 'medium' | 'hard'; // default: 'soft' + intensity?: number; // min: 0, max: 1, step: 0.1, default: 0 (responsive) + duration?: number; // min: 100, max: 4000, step: 100, default: 1300 + delay?: number; // min: 0, max: 8000, step: 100, default: 1000 +} +``` + +**Parameter Impact:** + +- `power`: Preset intensity levels + - `soft`: Offset 0 - very subtle pulse + - `medium`: Offset 0.06 - noticeable pulse + - `hard`: Offset 0.12 - pronounced pulse +- `intensity`: Fine-grained control (0-1), overrides power +- `delay`: Time before animation starts (useful for staggering) +- `duration`: Full cycle time (includes delay in calculation) + +## Minimal Examples + +```typescript +// Basic - subtle pulse +{ type: 'Pulse' } + +// Noticeable attention pulse +{ type: 'Pulse', power: 'medium' } +// with: duration: 1500 + +// Strong pulse for urgent attention +{ type: 'Pulse', power: 'hard' } +// with: duration: 1000 + +// Custom intensity +{ type: 'Pulse', intensity: 0.5 } +``` + +## Related Presets + +### Same Category (Ongoing) + +- **Breathe** - Scale-based but different timing pattern +- **Flash** - Opacity-based attention effect + +### Parallel in Other Triggers + +- **GrowScroll** (scroll) - Scale change on scroll +- **DropIn** (entrance) - Scale-based entrance + +### Alternatives + +- **Flash** - When opacity-based attention preferred +- **Bounce** - When vertical movement preferred +- **Breathe** - When different rhythm needed + +## Decision Hints + +```yaml +choose_this_when: + - "subtle continuous attention" + - "heartbeat/living effect" + - "status indicator" + - "notification badge" + - "gentle CTA emphasis" + +choose_alternative_when: + - opacity_based: Flash + - vertical_movement: Bounce + - rotation: Spin + - different_rhythm: Breathe + - one_time_attention: BounceIn, PunchIn +``` diff --git a/packages/motion-presets/rules/presets/ongoing/spin.md b/packages/motion-presets/rules/presets/ongoing/spin.md new file mode 100644 index 00000000..94745903 --- /dev/null +++ b/packages/motion-presets/rules/presets/ongoing/spin.md @@ -0,0 +1,113 @@ +--- +name: Spin +category: ongoing +tags: [spin, rotation, continuous, loading, circular, rotate] +--- + +# Spin + +## Synonyms + +spinning, rotating, rotation, circular motion, revolve, turn continuously + +## Visual Description + +Element continuously rotates 360 degrees around its center. Direction determines clockwise (default) or counter-clockwise rotation. Power level affects the easing: soft uses linear (constant speed), medium uses `quintInOut` (accelerate/decelerate), hard uses `backOut` (slight overshoot at end). Rotation preserves any existing component rotation (`--comp-rotate-z`). Creates smooth, continuous circular motion. + +## When to Use + +- Loading indicators (high confidence) +- Processing/waiting states +- Refresh icons during action +- Decorative spinning elements +- Gear/mechanical animations +- Fan/propeller effects +- Abstract decorative motion + +## When NOT to Use + +- Text elements (unreadable) +- Interactive elements during spin +- Multiple simultaneous spins (dizzying) +- Vestibular sensitivity concerns +- When spin direction is semantically meaningful but not clear +- Professional interfaces (can feel amateurish if overused) + +## Parameters + +```typescript +interface Spin { + direction: 'clockwise' | 'counter-clockwise'; // EffectSpinDirections, default: 'clockwise' + power?: 'soft' | 'medium' | 'hard'; // default: 'soft' + duration?: number; // min: 100, max: 50000, step: 100, default: 7000 + delay?: number; // min: 0, max: 8000, step: 100, default: 0 + easing?: Easing; // default: 'linear' (responsive) +} +``` + +**Parameter Impact:** + +- `direction`: Rotation direction + - `clockwise`: Rotates right (default, natural feeling) + - `counter-clockwise`: Rotates left +- `power`: Controls easing curve + - `soft`: Linear - constant speed, mechanical feel + - `medium`: `quintInOut` - accelerates then decelerates + - `hard`: `backOut` - slight overshoot, more dynamic +- `duration`: One full rotation time (default 7000ms = 7 seconds, slow) + +## Minimal Examples + +```typescript +// Basic - slow constant spin +{ type: 'Spin', direction: 'clockwise' } + +// Loading indicator (faster) +{ type: 'Spin', direction: 'clockwise' } +// with: duration: 1000, easing: 'linear' + +// Dynamic spin with overshoot +{ type: 'Spin', direction: 'counter-clockwise', power: 'hard' } +// with: duration: 2000 + +// Very slow decorative spin +{ type: 'Spin', direction: 'clockwise', power: 'soft' } +// with: duration: 15000 +``` + +## Related Presets + +### Same Category (Ongoing) + +- **Swing** - Oscillating rotation (back and forth) +- **Flip** - 180° flips, not continuous + +### Parallel in Other Triggers + +- **SpinIn** (entrance) - Spin into view (one-time) +- **SpinScroll** (scroll) - Rotation driven by scroll +- **SpinMouse** (mouse) - Rotation following mouse + +### Alternatives + +- **Swing** - When oscillation preferred over full rotation +- **Pulse** - When scale-based attention preferred +- **Flip** - When flip effect preferred + +## Decision Hints + +```yaml +choose_this_when: + - "loading/processing indicator" + - "refresh icon animation" + - "decorative rotation" + - "mechanical/gear effect" + - "continuous circular motion" + +choose_alternative_when: + - oscillation_needed: Swing + - scale_based: Pulse + - entrance_spin: SpinIn + - scroll_driven: SpinScroll + - mouse_driven: SpinMouse +``` diff --git a/packages/motion-presets/rules/presets/scroll/arc-scroll.md b/packages/motion-presets/rules/presets/scroll/arc-scroll.md new file mode 100644 index 00000000..ecb30bdd --- /dev/null +++ b/packages/motion-presets/rules/presets/scroll/arc-scroll.md @@ -0,0 +1,105 @@ +--- +name: ArcScroll +category: scroll +tags: [3d, arc, scroll, rotation, perspective, tilt, depth] +--- + +# ArcScroll + +## Synonyms + +scroll arc, 3d scroll, tilt scroll, rotation scroll, perspective scroll, scroll rotation + +## Visual Description + +Element rotates in 3D space along an arc path as user scrolls. Uses `perspective(500px)` with `translateZ(-300px)` to create depth, then rotates on X-axis (vertical direction) or Y-axis (horizontal direction) through 68 degrees. In `in` range, rotates from -68° to 0°. In `out` range, rotates from 0° to 68°. In `continuous` range, rotates full -68° to +68° throughout scroll. Fill mode set automatically based on range. Linear easing ensures smooth, predictable rotation mapped to scroll position. + +## When to Use + +- Dramatic scroll-based reveals (high confidence) +- Portfolio or showcase pages +- Storytelling with cinematic feel +- Hero sections with 3D depth +- Single featured elements per viewport +- Creative/artistic page designs + +## When NOT to Use + +- Multiple simultaneous elements (performance, visual noise) +- Text-heavy content (readability during rotation) +- Mobile devices with performance concerns +- Vestibular sensitivity concerns +- Data-dense interfaces +- When subtle scroll effect is needed + +## Parameters + +```typescript +interface ArcScroll { + direction: 'horizontal' | 'vertical'; // EffectTwoAxes, default: 'vertical' + range?: 'in' | 'out' | 'continuous'; // default: 'continuous' (wix) or 'in'/'out' (responsive) + // Scroll range params + start?: number; // varies by range + end?: number; // varies by range +} +``` + +**Parameter Impact:** + +- `direction`: Rotation axis + - `vertical`: Rotates on X-axis (tilts forward/backward) + - `horizontal`: Rotates on Y-axis (tilts left/right) +- `range`: When rotation occurs + - `in`: Rotates from tilted to flat as enters viewport + - `out`: Rotates from flat to tilted as exits viewport + - `continuous`: Full rotation throughout scroll + +## Minimal Examples + +```typescript +// Basic - continuous horizontal arc +{ type: 'ArcScroll', direction: 'horizontal' } + +// Vertical arc on entry +{ type: 'ArcScroll', direction: 'vertical', range: 'in' } + +// Arc out as exits +{ type: 'ArcScroll', direction: 'horizontal', range: 'out' } +``` + +## Related Presets + +### Same Category (Scroll) + +- **TiltScroll** - Similar 3D tilt, different implementation +- **FlipScroll** - Full flip rotation on scroll +- **Spin3dScroll** - Continuous spin on scroll + +### Parallel in Other Triggers + +- **ArcIn** (entrance) - Time-based arc entrance +- **FlipIn** (entrance) - Time-based 3D flip + +### Alternatives + +- **TiltScroll** - Alternative 3D tilt approach +- **FadeScroll** - When subtle effect needed +- **ParallaxScroll** - When 2D depth preferred + +## Decision Hints + +```yaml +choose_this_when: + - "dramatic 3D scroll effect" + - "cinematic reveal" + - "portfolio/showcase" + - "single focal element" + - "creative/artistic design" + +choose_alternative_when: + - subtle_needed: FadeScroll, ParallaxScroll + - full_flip: FlipScroll + - continuous_spin: SpinScroll + - 2d_depth: ParallaxScroll + - time_based: ArcIn +``` diff --git a/packages/motion-presets/rules/presets/scroll/fade-scroll.md b/packages/motion-presets/rules/presets/scroll/fade-scroll.md new file mode 100644 index 00000000..3d46dd7f --- /dev/null +++ b/packages/motion-presets/rules/presets/scroll/fade-scroll.md @@ -0,0 +1,106 @@ +--- +name: FadeScroll +category: scroll +tags: [fade, opacity, scroll, reveal, in, out, transition] +--- + +# FadeScroll + +## Synonyms + +scroll fade, fade on scroll, opacity scroll, scroll reveal, scroll disappear, fade in scroll, fade out scroll + +## Visual Description + +Element opacity transitions from transparent to opaque (or vice versa) as it scrolls through the viewport. In `in` range, element fades from specified opacity (default 0) to full visibility as it enters and reaches viewport center. In `out` range, element fades from full visibility to target opacity as it exits. Uses linear easing during scroll for smooth, predictable opacity mapping to scroll position. Fill mode automatically set: `backwards` for `in` (invisible before entering), `forwards` for `out` (stays faded after leaving). + +## When to Use + +- Content reveal as user scrolls down (high confidence) +- Section transitions and visual hierarchy +- Storytelling pages with progressive disclosure +- De-emphasizing content as user scrolls past +- Creating focus on currently visible content +- Smooth transitions between page sections + +## When NOT to Use + +- Critical content that must always be visible +- Navigation or persistent UI elements +- When abrupt transitions are acceptable +- Interactive elements during transition (click targets) +- Accessibility concerns with disappearing content + +## Parameters + +```typescript +interface FadeScroll { + range: 'in' | 'out'; // EffectRangeInOut, default: 'in' + opacity?: number; // min: 0, max: 1, step: 0.01, default: 0 + // Scroll range params + start?: number; // min: 0, max: 100, default: 0 (in) or 50 (out) + end?: number; // min: 0, max: 100, default: 50 (in) or 100 (out) +} +``` + +**Parameter Impact:** + +- `range`: Direction of the fade + - `in`: Fades from `opacity` to 1 as element enters viewport + - `out`: Fades from 1 to `opacity` as element leaves viewport +- `opacity`: Target opacity value (what it fades from/to) + - 0 (default): Fully transparent + - 0.5: Semi-transparent +- `start`/`end`: Scroll position range (0-100% of element visibility) + +## Minimal Examples + +```typescript +// Basic - fade in as enters viewport +{ type: 'FadeScroll', range: 'in' } + +// Fade out as leaves viewport +{ type: 'FadeScroll', range: 'out' } + +// Fade to semi-transparent +{ type: 'FadeScroll', range: 'out', opacity: 0.3 } + +// Custom scroll range +{ type: 'FadeScroll', range: 'in', start: 0, end: 30 } +``` + +## Related Presets + +### Same Category (Scroll) + +- **BlurScroll** - Blur effect on scroll, can combine with fade +- **RevealScroll** - Clip-based reveal on scroll + +### Parallel in Other Triggers + +- **FadeIn** (entrance) - Time-based fade, not scroll-driven +- **BgFade** (background-scroll) - Fade specifically for backgrounds + +### Alternatives + +- **BlurScroll** - When blur effect is preferred over pure opacity +- **RevealScroll** - When directional reveal is needed +- **GrowScroll** - When scale change is preferred + +## Decision Hints + +```yaml +choose_this_when: + - "content reveal on scroll" + - "section transitions" + - "progressive disclosure" + - "de-emphasize passed content" + - "simple opacity transition" + +choose_alternative_when: + - blur_effect: BlurScroll + - directional_reveal: RevealScroll, SlideScroll + - scale_change: GrowScroll, ShrinkScroll + - background_specific: BgFade + - time_based: FadeIn +``` diff --git a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md new file mode 100644 index 00000000..267cfc68 --- /dev/null +++ b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md @@ -0,0 +1,105 @@ +--- +name: ParallaxScroll +category: scroll +tags: [parallax, scroll, depth, layered, continuous, vertical, movement] +--- + +# ParallaxScroll + +## Synonyms + +parallax effect, scroll parallax, depth scroll, layered scroll, differential scroll, scroll movement + +## Visual Description + +Element moves vertically at a different rate than the scroll, creating depth illusion. Uses `translateY` to shift element position relative to scroll progress. With default speed (0.5), element moves half the distance of scroll - negative speed moves opposite direction. Animation runs continuously through the entire scroll range (`cover` timeline). Movement is linear without easing for smooth, constant-rate parallax. Creates layered depth effect when multiple elements have different speeds. + +## When to Use + +- Landing pages with layered depth effect (high confidence) +- Hero sections with background/foreground separation +- Storytelling pages with cinematic scroll +- Creating depth hierarchy between page sections +- Decorative elements that should feel "behind" or "in front" +- Modern, visually rich marketing pages + +## When NOT to Use + +- Text-heavy content (readability issues) +- Data-dense interfaces (distracting) +- Accessibility-focused interfaces (motion sensitivity) +- Mobile with performance concerns +- When precise element positioning matters +- Forms or interactive elements + +## Parameters + +```typescript +interface ParallaxScroll { + speed?: number; // min: -1, max: 1, step: 0.05, default: 0.5 + range?: 'continuous'; // only continuous supported + // Scroll range params (from base) + start?: number; // min: 0, max: 0, default: 0 (screen enter) + end?: number; // min: 100, max: 100, default: 100 (screen leave) +} +``` + +**Parameter Impact:** + +- `speed`: Rate of movement relative to scroll + - Positive (0.1-1): Element moves same direction as scroll, but slower + - Negative (-1 to -0.1): Element moves opposite to scroll direction + - Higher absolute value = more pronounced effect + - 0.5 (default): Element moves at half scroll speed +- `range`: Only `continuous` - runs throughout entire scroll range + +## Minimal Examples + +```typescript +// Basic - gentle parallax +{ type: 'ParallaxScroll' } + +// Strong parallax effect +{ type: 'ParallaxScroll', speed: 0.8 } + +// Reverse parallax (moves opposite) +{ type: 'ParallaxScroll', speed: -0.3 } + +// Subtle depth layer +{ type: 'ParallaxScroll', speed: 0.2 } +``` + +## Related Presets + +### Same Category (Scroll) + +- **MoveScroll** - General movement on scroll, more control +- **PanScroll** - Horizontal/vertical panning on scroll + +### Parallel in Other Triggers + +- **BgParallax** (background-scroll) - Parallax specifically for backgrounds + +### Alternatives + +- **FadeScroll** - When opacity change is preferred over movement +- **MoveScroll** - When more movement control needed +- **BgParallax** - When animating background media specifically + +## Decision Hints + +```yaml +choose_this_when: + - "depth/layered effect needed" + - "elements at different scroll rates" + - "cinematic scroll experience" + - "decorative elements" + - "hero section depth" + +choose_alternative_when: + - background_specific: BgParallax + - horizontal_movement: PanScroll + - opacity_based: FadeScroll + - more_control: MoveScroll + - 3d_rotation: ArcScroll, TiltScroll +``` From a47a1be123726cac3c8015302b70562abb5548ed Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Tue, 20 Jan 2026 13:48:24 +0200 Subject: [PATCH 02/20] Refine visual descriptions and usage guidelines for motion presets - Updated visual descriptions to use plain language, focusing on user experience rather than technical details. - Streamlined "When to Use" and "When NOT to Use" sections for clarity and brevity. - Enhanced examples to demonstrate meaningful differences in behavior. - Removed unnecessary technical jargon and emphasized user-centric language across multiple preset files. --- packages/motion-presets/rules/presets/PLAN.md | 105 +++++++++--------- .../presets/background-scroll/bg-fade.md | 19 +--- .../presets/background-scroll/bg-parallax.md | 24 +--- .../presets/background-scroll/bg-zoom.md | 23 +--- .../rules/presets/entrance/arc-in.md | 31 ++---- .../rules/presets/entrance/bounce-in.md | 32 ++---- .../rules/presets/entrance/fade-in.md | 29 ++--- .../rules/presets/mouse/bounce-mouse.md | 25 +---- .../rules/presets/mouse/tilt-3d-mouse.md | 30 ++--- .../rules/presets/mouse/track-mouse.md | 27 +---- .../rules/presets/ongoing/bounce.md | 28 +---- .../rules/presets/ongoing/pulse.md | 30 +---- .../rules/presets/ongoing/spin.md | 28 +---- .../rules/presets/scroll/arc-scroll.md | 25 ++--- .../rules/presets/scroll/fade-scroll.md | 22 +--- .../rules/presets/scroll/parallax-scroll.md | 21 +--- 16 files changed, 142 insertions(+), 357 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index e7dc2840..9cb3fc2f 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -110,46 +110,48 @@ fade in, appear, materialize, opacity transition, gentle reveal ### 3. Visual Description (Human-written) -**This section requires manual writing.** Describe exactly what the user SEES with specific cues: +**This section requires manual writing.** Describe what the user SEES in plain, non-technical language. Focus on the visual experience, not implementation details. -- **Opacity**: Does it fade? From what to what? -- **Movement**: Direction, distance, path (straight, curved, arc) -- **Rotation**: Axis (X, Y, Z), degrees, perspective -- **Scale**: Grows, shrinks, from what size? -- **Timing feel**: Smooth, bouncy, snappy, elastic +**DO describe:** +- What the element looks like during the animation (fades, moves, rotates, scales) +- The path or direction of movement (straight, curved, from where to where) +- The overall feeling (smooth, bouncy, snappy, dramatic, subtle) -Example for ArcIn: +**DO NOT reference:** +- CSS properties (translateY, perspective, rotateX) +- Keyframe percentages or offsets +- Easing function names +- Implementation details (800px perspective, 70% of animation) -> Element swings into view along a curved 3D arc path. Starts rotated on an axis (determined by direction), then rotates back to flat while moving along the arc. Includes a fade from transparent to opaque during the first 70% of the animation. Creates a dramatic, cinematic reveal with depth. +**Good example for ArcIn:** +> Element swings into view along a curved path, like a door opening towards you. It starts tilted away and gradually flattens as it settles into place. Fades in while moving. Creates a dramatic, cinematic reveal with depth. + +**Bad example (too technical):** +> Uses perspective(800px) with rotateX/Y transforms. Opacity fades from 0 to 1 during first 70% with sineIn easing. Main arc uses quintInOut. --- ### 4. When to Use -Bulleted decision criteria for LLM to recommend this preset: - -- User intent keywords (what they might ask for) -- Content type suitability (hero, cards, text, images) -- Design context (landing page, modal, dashboard) -- Emotional/brand tone match - -Include **confidence scenarios** inline: +**Keep it short: 3-5 bullet points max.** Focus on the most common and confident use cases. ```markdown -- Hero sections requiring dramatic entrance (high confidence) -- Modal content reveal (medium confidence - consider FadeIn for subtler effect) +- Hero sections needing dramatic reveal +- Featured/premium content +- Single focal elements ``` --- ### 5. When NOT to Use -Anti-patterns and limitations: +**Keep it short: 2-4 bullet points max.** Only the most important anti-patterns. -- Accessibility concerns (vestibular, motion sensitivity) -- Performance issues (many elements, mobile) -- Design mismatches (too dramatic for subtle UI) -- Better alternatives (suggest specific presets) +```markdown +- Multiple simultaneous elements +- Subtle/professional interfaces +- Mobile with performance concerns +``` --- @@ -201,21 +203,21 @@ Add brief impact notes: ### 7. Minimal Examples -2-3 terse, copy-paste ready snippets: +**Only include examples that show fundamentally different configurations.** Don't add examples just for variety. + +- Include basic/default usage +- Only add more examples if they demonstrate meaningfully different behavior (e.g., different direction that changes the visual, inverted mode, etc.) ```typescript -// Basic - minimal config +// Basic { type: 'ArcIn', direction: 'bottom' } -// Dramatic hero entrance -{ type: 'ArcIn', direction: 'bottom', power: 'hard' } -// with: duration: 1400, easing: 'quintOut' - -// Subtle side panel -{ type: 'ArcIn', direction: 'left', power: 'soft' } -// with: duration: 800 +// Only add if meaningfully different: +{ type: 'ArcIn', direction: 'left', power: 'hard' } ``` +**Skip examples that only differ by duration, delay, or minor parameter tweaks.** + --- ### 8. Related Presets @@ -328,23 +330,19 @@ tags: [3d, arc, curved, dramatic, cinematic, perspective, rotation, entrance] **Visual Description:** -> Element swings into view along a curved 3D arc path. Starts rotated on an axis (X for top/bottom, Y for left/right) then rotates back to flat while moving along the arc. Includes opacity fade from 0 to 1 during the first 70% of animation. The perspective (800px) creates depth. Power level controls rotation intensity: soft ~15°, medium ~30°, hard ~45°. Movement feels smooth and cinematic with quintInOut easing. +> Element swings into view along a curved path, like a door opening towards you. It starts tilted away and gradually flattens as it settles into place. Fades in while moving. The effect feels dramatic and cinematic, with a sense of depth. **When to Use:** -- Hero sections requiring dramatic, cinematic entrance (high confidence) -- Premium product showcases where depth and drama matter -- Portfolio pieces and creative presentations -- Featured content that needs to stand out -- Modal content reveal (medium confidence - consider FadeIn for subtler effect) +- Hero sections needing dramatic reveal +- Premium/featured content +- Single focal elements requiring attention **When NOT to Use:** -- Multiple simultaneous elements (performance concern) -- Users with vestibular sensitivity (reduced-motion alternative: FadeIn) -- Subtle, professional interfaces where drama is inappropriate +- Multiple simultaneous elements +- Subtle, professional interfaces - Mobile with many animated elements -- When 2D motion would suffice (use SlideIn, GlideIn instead) **Parameters:** @@ -366,16 +364,11 @@ interface ArcIn { **Minimal Examples:** ```typescript -// Basic +// Basic - swings in from bottom { type: 'ArcIn', direction: 'bottom' } -// Dramatic hero -{ type: 'ArcIn', direction: 'bottom', power: 'hard' } -// duration: 1400, easing: 'quintOut' - -// Subtle side entry -{ type: 'ArcIn', direction: 'left', power: 'soft' } -// duration: 800 +// Side entry (rotates on different axis) +{ type: 'ArcIn', direction: 'left' } ``` **Related Presets:** @@ -450,8 +443,10 @@ rules/presets/ ## Implementation Notes -1. **Visual Description**: Requires human writing - analyze keyframes in implementation files for cues about opacity, rotation axes, movement paths, and timing -2. **Parameters**: Combine TypeScript types from `motion-presets` with constraints from `effects-kit`. **Always check each preset's specific file** - they override base params with different enum subsets -3. **Direction/Easing subsets**: Document the exact subset each preset supports, not the base type. Clipped animations (ShapeIn, RevealIn, ShuttersIn, WinkIn) exclude back easings -4. **Cross-trigger mapping**: Map entrance presets to their scroll/mouse equivalents where they exist (e.g., ArcIn ↔ ArcScroll) -5. **Tags**: Derive from visual characteristics, use cases, and motion type \ No newline at end of file +1. **Visual Description**: Write in plain language describing what the user sees. NO technical terms (CSS properties, keyframe percentages, easing names). Use analogies and natural descriptions. +2. **When to Use / When NOT to Use**: Keep short (3-5 and 2-4 bullets respectively). Focus on high-confidence, common cases. +3. **Examples**: Only include if they show fundamentally different behavior. Skip examples that only differ by duration/delay. +4. **Parameters**: Combine TypeScript types from `motion-presets` with constraints from `effects-kit`. **Always check each preset's specific file** - they override base params with different enum subsets +5. **Direction/Easing subsets**: Document the exact subset each preset supports, not the base type. Clipped animations (ShapeIn, RevealIn, ShuttersIn, WinkIn) exclude back easings +6. **Cross-trigger mapping**: Map entrance presets to their scroll/mouse equivalents where they exist (e.g., ArcIn ↔ ArcScroll) +7. **Tags**: Derive from visual characteristics, use cases, and motion type \ No newline at end of file diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md index ccfe23ac..e5ab93bf 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md @@ -12,24 +12,18 @@ background fade, bg fade, fade background, background opacity, background reveal ## Visual Description -Background layer opacity transitions as user scrolls through the section. In `in` range, background fades from transparent (0) to fully visible (1) as element enters viewport and reaches center. In `out` range, background fades from visible to transparent as element exits. Targets the `BG_LAYER` element specifically. Uses `sineIn` easing for fade in, `sineOut` for fade out. Covers the scroll range from element entering viewport to center (in) or center to leaving (out). +Background gradually appears or disappears as you scroll through a section. In "in" mode, background fades from invisible to visible. In "out" mode, it fades away. Creates smooth transitions between sections. ## When to Use -- Section transitions with background change (high confidence) +- Section transitions with background change - Progressive background reveals -- Layered backgrounds that appear/disappear -- Storytelling with background reveals -- Section dividers with visual transitions -- Creating focus on/off content areas +- Creating focus on content areas ## When NOT to Use - When background must always be visible - Critical visual information in background -- Fast-scrolling interfaces -- When abrupt transitions are acceptable -- Mobile with color-only backgrounds (no benefit) ## Parameters @@ -54,14 +48,11 @@ interface BgFade { ## Minimal Examples ```typescript -// Basic - fade in on entry +// Fade in as section enters { type: 'BgFade', range: 'in' } -// Fade out on exit +// Fade out as section exits { type: 'BgFade', range: 'out' } - -// Custom scroll range for earlier fade -{ type: 'BgFade', range: 'in', start: 0, end: 30 } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md index f894a32f..e58c1e34 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md @@ -12,25 +12,18 @@ background parallax, bg parallax, background scroll, parallax background, depth ## Visual Description -Background media (image or video) moves vertically at a different rate than content scroll, creating depth illusion. Uses `translateY` on the `BG_MEDIA` element. With default speed (0.2), background moves slowly relative to scroll - positive values move background in scroll direction, creating effect of background being "further away". Runs continuously through entire element visibility (`cover` timeline). More subtle than element parallax due to lower default speed. +Background image or video moves slower than page scroll, creating an illusion of depth. Like the background is further away than the content in front of it. Subtle effect that adds visual richness without being distracting. ## When to Use -- Hero sections with depth (high confidence) +- Hero sections with depth - Full-width section backgrounds - Landing pages with visual richness -- Storytelling pages with immersive feel -- Section separators with visual interest -- Photography portfolio backgrounds ## When NOT to Use -- Content-heavy sections (distracting) - Mobile with performance concerns -- Backgrounds with important visual details (may be cropped) -- When background position precision matters -- Accessibility-focused sites (motion concerns) -- Color-only backgrounds (no visual benefit) +- Color-only backgrounds (no benefit) ## Parameters @@ -52,17 +45,8 @@ interface BgParallax { ## Minimal Examples ```typescript -// Basic - subtle parallax +// Basic { type: 'BgParallax' } - -// Noticeable depth effect -{ type: 'BgParallax', speed: 0.4 } - -// Very subtle (barely moves) -{ type: 'BgParallax', speed: 0.1 } - -// Dramatic parallax -{ type: 'BgParallax', speed: 0.7 } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md index e3446d04..621d9f06 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md @@ -12,25 +12,18 @@ background zoom, bg zoom, zoom scroll, dolly zoom, zoom effect background, ken b ## Visual Description -Background image zooms in or out as user scrolls, creating dramatic depth effect. Uses `perspective` and `translateZ` transforms for true 3D zoom rather than scale. In `in` direction, background starts normal and zooms in (moves towards viewer) as scroll progresses. In `out` direction, background zooms out (moves away). Uses different starting Y positions and easing per direction: `in` starts at 20svh with `sineIn`, `out` starts at 0 with `sineInOut`. Creates cinematic dolly/zoom effect. +Background image zooms in or out as you scroll, like a camera dolly move. Creates a cinematic, dramatic effect where the background appears to move towards or away from you. ## When to Use -- Cinematic hero sections (high confidence) +- Cinematic hero sections - Dramatic section reveals - Photography/portfolio showcases -- Landing pages with high visual impact -- Storytelling with depth emphasis -- Single featured image sections ## When NOT to Use -- Text-heavy backgrounds (hard to read during zoom) -- Multiple sections with zoom (overwhelming) +- Multiple sections with zoom - Mobile with performance concerns -- When background details must stay sharp -- Vestibular sensitivity concerns -- Precise background positioning needed ## Parameters @@ -55,17 +48,11 @@ interface BgZoom { ## Minimal Examples ```typescript -// Basic - zoom in effect +// Zoom in as you scroll { type: 'BgZoom', direction: 'in' } -// Zoom out as scroll +// Zoom out as you scroll { type: 'BgZoom', direction: 'out' } - -// Subtle zoom -{ type: 'BgZoom', direction: 'in', zoom: 3 } - -// Dramatic zoom -{ type: 'BgZoom', direction: 'in', zoom: 10 } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/entrance/arc-in.md b/packages/motion-presets/rules/presets/entrance/arc-in.md index 11007228..b035bb46 100644 --- a/packages/motion-presets/rules/presets/entrance/arc-in.md +++ b/packages/motion-presets/rules/presets/entrance/arc-in.md @@ -12,25 +12,19 @@ arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective r ## Visual Description -Element swings into view along a curved 3D arc path. Starts rotated on an axis (X-axis for top/bottom directions, Y-axis for left/right) at approximately 80 degrees, then rotates back to flat (0 degrees) while moving along the arc. Uses `perspective(800px)` to create depth. Includes an opacity fade from 0 to 1 during the first 70% of the animation (separate fade animation with `sineIn` easing). The main arc motion uses `quintInOut` easing by default, creating smooth acceleration and deceleration. Power level controls the rotation intensity through different easing curves: soft uses `cubicInOut`, medium uses `quintInOut`, hard uses `backOut` for slight overshoot. +Element swings into view along a curved path, like a door opening towards you. It starts tilted away and gradually flattens as it settles into place. Fades in while moving. The effect feels dramatic and cinematic, with a sense of depth. ## When to Use -- Hero sections requiring dramatic, cinematic entrance (high confidence) -- Premium product showcases where depth and drama matter -- Portfolio pieces and creative presentations -- Featured content that needs to stand out -- Landing page hero elements -- Single focal point elements (not for lists) +- Hero sections needing dramatic reveal +- Premium/featured content +- Single focal elements requiring attention ## When NOT to Use -- Multiple simultaneous elements (performance concern with 3D transforms) -- Users with vestibular sensitivity (provides reduced-motion alternative: FadeIn) -- Subtle, professional interfaces where drama is inappropriate -- Mobile with many animated elements (3D transforms are expensive) -- When 2D motion would suffice (use SlideIn, GlideIn instead) -- List items or repeated content +- Multiple simultaneous elements +- Subtle, professional interfaces +- Mobile with many animated elements ## Parameters @@ -57,16 +51,11 @@ interface ArcIn { ## Minimal Examples ```typescript -// Basic - element arcs in from the left +// Basic - swings in from bottom { type: 'ArcIn', direction: 'bottom' } -// Dramatic hero entrance with overshoot -{ type: 'ArcIn', direction: 'bottom', power: 'hard' } -// with: duration: 1400 - -// Subtle side panel entrance -{ type: 'ArcIn', direction: 'left', power: 'soft' } -// with: duration: 800 +// Side entry (tilts on different axis) +{ type: 'ArcIn', direction: 'left' } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/entrance/bounce-in.md b/packages/motion-presets/rules/presets/entrance/bounce-in.md index d6bd6e6d..ebdb1c26 100644 --- a/packages/motion-presets/rules/presets/entrance/bounce-in.md +++ b/packages/motion-presets/rules/presets/entrance/bounce-in.md @@ -12,26 +12,20 @@ bounce entrance, bouncy reveal, spring in, elastic entrance, playful appear, jum ## Visual Description -Element bounces into view from a specified direction with multiple decreasing bounces before settling. Starts with opacity 0 and full translation (distance based on power), then performs a series of bounces: first bounce reaches 100% distance, then progressively smaller bounces at ~35%, ~21%, ~9%, ~2% of original distance. Each bounce alternates between `sineIn` and `sineOut` easing for realistic physics. The opacity fades in during the first ~54% of the animation with `quadOut` easing. For `center` direction, uses `perspective(800px)` and bounces on Z-axis (towards/away from viewer). Creates a fun, energetic, attention-grabbing entrance. +Element bounces into view with playful, physics-like motion. It overshoots its landing spot, then bounces back smaller and smaller until it settles. Like a ball dropping and bouncing to rest. Fades in as it enters. Creates a fun, energetic, attention-grabbing entrance. ## When to Use -- Playful, fun brand interfaces (high confidence) +- Playful, fun brand interfaces - Gamification elements and rewards -- Notification badges or indicators -- Call-to-action buttons that need attention -- Success states and confirmations -- Child-friendly interfaces -- Marketing landing pages with energetic tone +- Notification badges needing attention +- Call-to-action buttons ## When NOT to Use -- Professional/corporate interfaces (too playful) -- Serious content like error messages or warnings -- Forms and data entry interfaces -- Multiple simultaneous elements (visual noise) -- Users with vestibular sensitivity (bouncing motion) -- When subtle entrance is appropriate +- Professional/corporate interfaces +- Multiple simultaneous elements +- When subtle entrance is needed ## Parameters @@ -64,16 +58,8 @@ interface BounceIn { // Basic - bounces down from top { type: 'BounceIn', direction: 'top' } -// Energetic CTA button -{ type: 'BounceIn', direction: 'bottom', power: 'hard' } -// with: duration: 1000 - -// Subtle notification badge -{ type: 'BounceIn', direction: 'center', power: 'soft' } -// with: duration: 800 - -// Custom distance factor -{ type: 'BounceIn', direction: 'left', distanceFactor: 2.5 } +// Bounces towards viewer (3D effect) +{ type: 'BounceIn', direction: 'center' } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/entrance/fade-in.md b/packages/motion-presets/rules/presets/entrance/fade-in.md index ae23b6d2..6585d5b6 100644 --- a/packages/motion-presets/rules/presets/entrance/fade-in.md +++ b/packages/motion-presets/rules/presets/entrance/fade-in.md @@ -12,24 +12,19 @@ fade in, appear, materialize, opacity transition, gentle reveal, soft entrance, ## Visual Description -Element transitions from fully transparent (opacity 0) to fully visible (opacity 1). No movement, rotation, or scale changes occur - purely an opacity transition. Uses `sineInOut` easing for a smooth, natural feel. The simplest and most universally applicable entrance animation. +Element gradually appears from invisible to fully visible. No movement or shape changes - just a smooth, gentle materialization. The simplest and most universally applicable entrance animation. ## When to Use -- Subtle content reveals in professional interfaces (high confidence) -- Modal and overlay appearances where movement would be distracting -- Loading state transitions - content appearing after load -- Progressive disclosure in forms and wizards -- Image galleries revealing loaded images -- Any element requiring gentle, non-distracting introduction -- Fallback for `prefers-reduced-motion` accessibility +- Subtle content reveals in professional interfaces +- Modal and overlay appearances +- Loading state transitions +- Reduced motion fallback ## When NOT to Use -- When user needs attention drawn to specific element (use more dramatic preset) -- When spatial relationship matters (use SlideIn, GlideIn to show direction) -- Hero sections where impact is needed (use ArcIn, BounceIn) -- When element position context is important +- When attention needs to be drawn to element +- Hero sections where impact is needed ## Parameters @@ -49,16 +44,8 @@ interface FadeIn { ## Minimal Examples ```typescript -// Basic - minimal config +// Basic { type: 'FadeIn' } - -// Quick snappy fade -{ type: 'FadeIn' } -// with: duration: 300 - -// Slow dramatic fade -{ type: 'FadeIn' } -// with: duration: 1500, delay: 200 ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md index 6f0df8ab..2263947c 100644 --- a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md @@ -12,25 +12,18 @@ bouncy mouse, elastic follow, spring mouse, bouncy cursor effect, elastic tracki ## Visual Description -Element follows mouse position with elastic/bouncy easing, creating spring-like motion. Built on TrackMouse foundation but with `elastic` or `bounce` transition easing. When mouse moves, element overshoots its target position then bounces back to settle. Creates playful, game-like interaction feel. Same translation behavior as TrackMouse but with springy physics. +Element follows the mouse with a bouncy, springy motion. Like a jelly or rubber ball that overshoots and wobbles before settling. Creates a playful, game-like interaction feel. ## When to Use -- Playful/fun interface elements (high confidence) +- Playful/fun interface elements - Game-like interactions +- Mascot/character elements - Child-friendly interfaces -- Mascot/character elements following cursor -- Energetic brand interactions -- Interactive easter eggs -- Engaging decorative elements ## When NOT to Use - Professional/corporate interfaces -- Precise interactions needed -- Multiple elements (chaotic) -- Performance-constrained -- Accessibility-focused (motion sensitivity) - When smooth following is preferred ## Parameters @@ -57,18 +50,8 @@ interface BounceMouse { ## Minimal Examples ```typescript -// Basic - elastic bounce following +// Basic { type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } - -// Bounce easing variant -{ type: 'BounceMouse', distance: { value: 100, type: 'px' }, axis: 'both' } -// with: transitionEasing: 'bounce' - -// Horizontal only bounce -{ type: 'BounceMouse', distance: { value: 60, type: 'px' }, axis: 'horizontal' } - -// Inverted bounce (moves away) -{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both', inverted: true } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md index 88e72dee..0f00b9c2 100644 --- a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md @@ -12,26 +12,19 @@ tags: [3d, tilt, mouse, perspective, interactive, hover, rotation] ## Visual Description -Element tilts in 3D space following mouse position within the tracking area. Uses `perspective` and `rotateX`/`rotateY` transforms to create depth. When mouse is at center, element is flat (0° rotation). Moving mouse left/right tilts element on Y-axis; moving up/down tilts on X-axis. Maximum tilt angle controlled by power/angle parameter. Perspective distance affects depth perception. Optional smooth transition easing when mouse moves. Inverted mode reverses tilt direction. +Element tilts towards the mouse cursor, like holding a card and angling it. Moving mouse left tilts element left, moving up tilts it back. Creates an interactive 3D feel where elements respond to cursor position. ## When to Use -- Interactive cards and product displays (high confidence) +- Interactive cards and product displays - Hero sections with depth effect -- Image galleries with hover enhancement - Portfolio thumbnails -- Call-to-action buttons with premium feel - Game-like interfaces -- 3D showcase elements ## When NOT to Use -- Text-heavy content (readability issues during tilt) -- Mobile devices (no mouse, use device orientation instead) -- Accessibility-focused interfaces -- Multiple overlapping elements -- When precise click targeting is needed -- Performance-constrained environments +- Mobile devices (no mouse) +- Text-heavy content ## Parameters @@ -61,20 +54,11 @@ interface Tilt3DMouse { ## Minimal Examples ```typescript -// Basic - medium tilt +// Basic { type: 'Tilt3DMouse' } -// Subtle card tilt -{ type: 'Tilt3DMouse', power: 'soft' } -// with: transitionDuration: 300 - -// Dramatic interactive element -{ type: 'Tilt3DMouse', power: 'hard' } -// with: transitionDuration: 200 - -// Custom angle with inverted -{ type: 'Tilt3DMouse', angle: 30, inverted: true } -// with: perspective: 600 +// Inverted (tilts away from mouse) +{ type: 'Tilt3DMouse', inverted: true } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/mouse/track-mouse.md b/packages/motion-presets/rules/presets/mouse/track-mouse.md index 2cd246c9..77fb8445 100644 --- a/packages/motion-presets/rules/presets/mouse/track-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/track-mouse.md @@ -12,26 +12,19 @@ mouse tracking, follow cursor, cursor follow, mouse movement, parallax mouse, fl ## Visual Description -Element translates (moves) to follow mouse position within tracking area. Mouse at center = element at original position. Moving mouse towards edges translates element in same (or opposite if inverted) direction. Distance parameter controls maximum translation distance. Axis parameter limits movement to horizontal, vertical, or both. Optional transition smoothing creates fluid following effect rather than instant tracking. +Element follows the mouse cursor, moving in the same direction. Like a floating object that drifts towards where you point. Can be limited to horizontal or vertical movement only. Creates an interactive, responsive feel. ## When to Use -- Parallax-like mouse effects (high confidence) -- Interactive backgrounds with depth layers +- Parallax-like mouse effects - Floating elements that follow cursor -- Decorative elements responding to mouse - Interactive hero sections -- Game-like cursor interactions -- Creating depth with multiple layers at different distances +- Creating depth with layered elements ## When NOT to Use -- Elements that need precise positioning -- Interactive/clickable elements (confusing hit targets) -- Text content (hard to read while moving) - Mobile devices (no mouse) -- Performance-constrained with many elements -- When accessibility is priority +- Interactive/clickable elements ## Parameters @@ -64,19 +57,11 @@ interface TrackMouse { ## Minimal Examples ```typescript -// Basic - follows mouse +// Basic - follows mouse in all directions { type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } -// Horizontal only parallax +// Horizontal only { type: 'TrackMouse', distance: { value: 100, type: 'px' }, axis: 'horizontal' } -// with: transitionDuration: 300 - -// Inverted (moves away from mouse) -{ type: 'TrackMouse', distance: { value: 150, type: 'px' }, axis: 'both', inverted: true } - -// Large range with smooth transition -{ type: 'TrackMouse', distance: { value: 400, type: 'px' }, axis: 'both' } -// with: transitionDuration: 600, transitionEasing: 'easeOut' ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/ongoing/bounce.md b/packages/motion-presets/rules/presets/ongoing/bounce.md index 170b77fb..74c8a6b3 100644 --- a/packages/motion-presets/rules/presets/ongoing/bounce.md +++ b/packages/motion-presets/rules/presets/ongoing/bounce.md @@ -12,26 +12,19 @@ bouncing, jumping, hopping, vertical bounce, continuous bounce, bouncy animation ## Visual Description -Element continuously bounces up and down with realistic physics-based motion. Keyframe sequence simulates gravity: rises quickly to peak (-98px at highest), falls back, bounces smaller (-55px), repeats with decreasing amplitude (-23px, -5px, -2px) before settling and restarting. Uses `sineOut` easing for natural acceleration/deceleration. Power/intensity controls the bounce height multiplier (factor 1-3). Creates playful, energetic continuous motion. +Element continuously bounces up and down like a ball on a trampoline. Bounces high, then smaller and smaller before the cycle repeats. Creates playful, energetic, attention-grabbing continuous motion. ## When to Use -- Playful/fun interface elements (high confidence) +- Playful/fun interface elements - Gamification indicators - "Jump here" attention indicators -- Waiting states with personality -- Interactive elements in games - Child-friendly interfaces -- Mascots or character elements ## When NOT to Use -- Professional/corporate interfaces (too playful) -- Text content (hard to read) -- Multiple simultaneous elements (chaotic) -- Serious contexts (warnings, errors) -- Accessibility concerns (motion sensitivity) -- When subtle attention is needed +- Professional/corporate interfaces +- Multiple simultaneous elements ## Parameters @@ -57,19 +50,8 @@ interface Bounce { ## Minimal Examples ```typescript -// Basic - gentle bounce +// Basic { type: 'Bounce' } - -// Energetic bounce -{ type: 'Bounce', power: 'medium' } -// with: duration: 1000 - -// Dramatic attention bounce -{ type: 'Bounce', power: 'hard' } -// with: duration: 1500 - -// Custom intensity -{ type: 'Bounce', intensity: 0.6 } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/ongoing/pulse.md b/packages/motion-presets/rules/presets/ongoing/pulse.md index b1c89c8d..e7b6c876 100644 --- a/packages/motion-presets/rules/presets/ongoing/pulse.md +++ b/packages/motion-presets/rules/presets/ongoing/pulse.md @@ -12,26 +12,19 @@ pulse effect, heartbeat, throb, breathing, scale pulse, attention pulse, pulsing ## Visual Description -Element continuously scales down and back up in a heartbeat-like pattern. Keyframe sequence: starts at scale 1, shrinks to ~0.96 at 27%, returns to 1 at 45%, shrinks further to ~0.93 at 72%, returns to 1 at 100%. The shrink amount is controlled by power/intensity - higher values create more pronounced shrinking. Uses linear easing overall with calculated offsets based on duration/delay ratio. Creates subtle, continuous attention-drawing effect without being distracting. +Element gently shrinks and expands in a rhythmic, heartbeat-like pattern. Like something breathing or pulsing with life. Creates subtle, continuous attention without being distracting. ## When to Use -- Drawing attention to important elements (high confidence) +- Drawing attention to important elements - Live/active status indicators -- Notification badges that need visibility -- Call-to-action buttons (subtle) -- "Heartbeat" effect for health/life indicators -- Breathing/living element feel +- Notification badges - Waiting/processing states ## When NOT to Use -- Multiple elements simultaneously (overwhelming) -- Primary content areas (distracting) -- Fast-paced interfaces (adds visual noise) -- When user needs to focus on content -- Accessibility concerns (repetitive motion) -- Professional/minimal interfaces (can feel gimmicky) +- Multiple elements simultaneously +- Professional/minimal interfaces ## Parameters @@ -57,19 +50,8 @@ interface Pulse { ## Minimal Examples ```typescript -// Basic - subtle pulse +// Basic { type: 'Pulse' } - -// Noticeable attention pulse -{ type: 'Pulse', power: 'medium' } -// with: duration: 1500 - -// Strong pulse for urgent attention -{ type: 'Pulse', power: 'hard' } -// with: duration: 1000 - -// Custom intensity -{ type: 'Pulse', intensity: 0.5 } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/ongoing/spin.md b/packages/motion-presets/rules/presets/ongoing/spin.md index 94745903..60432889 100644 --- a/packages/motion-presets/rules/presets/ongoing/spin.md +++ b/packages/motion-presets/rules/presets/ongoing/spin.md @@ -12,26 +12,19 @@ spinning, rotating, rotation, circular motion, revolve, turn continuously ## Visual Description -Element continuously rotates 360 degrees around its center. Direction determines clockwise (default) or counter-clockwise rotation. Power level affects the easing: soft uses linear (constant speed), medium uses `quintInOut` (accelerate/decelerate), hard uses `backOut` (slight overshoot at end). Rotation preserves any existing component rotation (`--comp-rotate-z`). Creates smooth, continuous circular motion. +Element continuously rotates around its center, like a wheel or loading spinner. Can spin clockwise or counter-clockwise at constant speed or with acceleration/deceleration. Creates smooth, continuous circular motion. ## When to Use -- Loading indicators (high confidence) +- Loading indicators - Processing/waiting states - Refresh icons during action - Decorative spinning elements -- Gear/mechanical animations -- Fan/propeller effects -- Abstract decorative motion ## When NOT to Use - Text elements (unreadable) -- Interactive elements during spin -- Multiple simultaneous spins (dizzying) -- Vestibular sensitivity concerns -- When spin direction is semantically meaningful but not clear -- Professional interfaces (can feel amateurish if overused) +- Multiple simultaneous spins ## Parameters @@ -59,20 +52,11 @@ interface Spin { ## Minimal Examples ```typescript -// Basic - slow constant spin +// Basic - clockwise spin { type: 'Spin', direction: 'clockwise' } -// Loading indicator (faster) -{ type: 'Spin', direction: 'clockwise' } -// with: duration: 1000, easing: 'linear' - -// Dynamic spin with overshoot -{ type: 'Spin', direction: 'counter-clockwise', power: 'hard' } -// with: duration: 2000 - -// Very slow decorative spin -{ type: 'Spin', direction: 'clockwise', power: 'soft' } -// with: duration: 15000 +// Counter-clockwise +{ type: 'Spin', direction: 'counter-clockwise' } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/scroll/arc-scroll.md b/packages/motion-presets/rules/presets/scroll/arc-scroll.md index ecb30bdd..79ce694e 100644 --- a/packages/motion-presets/rules/presets/scroll/arc-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/arc-scroll.md @@ -12,25 +12,19 @@ scroll arc, 3d scroll, tilt scroll, rotation scroll, perspective scroll, scroll ## Visual Description -Element rotates in 3D space along an arc path as user scrolls. Uses `perspective(500px)` with `translateZ(-300px)` to create depth, then rotates on X-axis (vertical direction) or Y-axis (horizontal direction) through 68 degrees. In `in` range, rotates from -68° to 0°. In `out` range, rotates from 0° to 68°. In `continuous` range, rotates full -68° to +68° throughout scroll. Fill mode set automatically based on range. Linear easing ensures smooth, predictable rotation mapped to scroll position. +Element tilts and rotates in 3D as you scroll, like a card flipping towards or away from you. Creates a dramatic, cinematic reveal with depth. The element appears to exist in 3D space, rotating on an invisible axis as scroll progresses. ## When to Use -- Dramatic scroll-based reveals (high confidence) +- Dramatic scroll-based reveals - Portfolio or showcase pages -- Storytelling with cinematic feel - Hero sections with 3D depth -- Single featured elements per viewport -- Creative/artistic page designs ## When NOT to Use -- Multiple simultaneous elements (performance, visual noise) -- Text-heavy content (readability during rotation) -- Mobile devices with performance concerns -- Vestibular sensitivity concerns -- Data-dense interfaces -- When subtle scroll effect is needed +- Multiple simultaneous elements +- Text-heavy content +- Mobile with performance concerns ## Parameters @@ -57,14 +51,11 @@ interface ArcScroll { ## Minimal Examples ```typescript -// Basic - continuous horizontal arc +// Tilts left/right as you scroll { type: 'ArcScroll', direction: 'horizontal' } -// Vertical arc on entry -{ type: 'ArcScroll', direction: 'vertical', range: 'in' } - -// Arc out as exits -{ type: 'ArcScroll', direction: 'horizontal', range: 'out' } +// Tilts forward/backward as you scroll +{ type: 'ArcScroll', direction: 'vertical' } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/scroll/fade-scroll.md b/packages/motion-presets/rules/presets/scroll/fade-scroll.md index 3d46dd7f..ae15d1ae 100644 --- a/packages/motion-presets/rules/presets/scroll/fade-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/fade-scroll.md @@ -12,24 +12,18 @@ scroll fade, fade on scroll, opacity scroll, scroll reveal, scroll disappear, fa ## Visual Description -Element opacity transitions from transparent to opaque (or vice versa) as it scrolls through the viewport. In `in` range, element fades from specified opacity (default 0) to full visibility as it enters and reaches viewport center. In `out` range, element fades from full visibility to target opacity as it exits. Uses linear easing during scroll for smooth, predictable opacity mapping to scroll position. Fill mode automatically set: `backwards` for `in` (invisible before entering), `forwards` for `out` (stays faded after leaving). +Element gradually appears or disappears as you scroll. In "in" mode, content fades from invisible to visible as it enters the viewport. In "out" mode, it fades away as you scroll past. Creates smooth, cinematic content reveals. ## When to Use -- Content reveal as user scrolls down (high confidence) -- Section transitions and visual hierarchy -- Storytelling pages with progressive disclosure -- De-emphasizing content as user scrolls past -- Creating focus on currently visible content -- Smooth transitions between page sections +- Content reveal as user scrolls +- Section transitions +- De-emphasizing passed content ## When NOT to Use - Critical content that must always be visible - Navigation or persistent UI elements -- When abrupt transitions are acceptable -- Interactive elements during transition (click targets) -- Accessibility concerns with disappearing content ## Parameters @@ -56,17 +50,11 @@ interface FadeScroll { ## Minimal Examples ```typescript -// Basic - fade in as enters viewport +// Fade in as enters viewport { type: 'FadeScroll', range: 'in' } // Fade out as leaves viewport { type: 'FadeScroll', range: 'out' } - -// Fade to semi-transparent -{ type: 'FadeScroll', range: 'out', opacity: 0.3 } - -// Custom scroll range -{ type: 'FadeScroll', range: 'in', start: 0, end: 30 } ``` ## Related Presets diff --git a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md index 267cfc68..e5039621 100644 --- a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md @@ -12,25 +12,18 @@ parallax effect, scroll parallax, depth scroll, layered scroll, differential scr ## Visual Description -Element moves vertically at a different rate than the scroll, creating depth illusion. Uses `translateY` to shift element position relative to scroll progress. With default speed (0.5), element moves half the distance of scroll - negative speed moves opposite direction. Animation runs continuously through the entire scroll range (`cover` timeline). Movement is linear without easing for smooth, constant-rate parallax. Creates layered depth effect when multiple elements have different speeds. +Element moves slower or faster than the page scroll, creating an illusion of depth. Like looking through a window where nearby objects move faster than distant ones. Different elements with different speeds create layered, dimensional feel. ## When to Use -- Landing pages with layered depth effect (high confidence) +- Landing pages with layered depth effect - Hero sections with background/foreground separation -- Storytelling pages with cinematic scroll -- Creating depth hierarchy between page sections - Decorative elements that should feel "behind" or "in front" -- Modern, visually rich marketing pages ## When NOT to Use - Text-heavy content (readability issues) -- Data-dense interfaces (distracting) -- Accessibility-focused interfaces (motion sensitivity) - Mobile with performance concerns -- When precise element positioning matters -- Forms or interactive elements ## Parameters @@ -56,17 +49,11 @@ interface ParallaxScroll { ## Minimal Examples ```typescript -// Basic - gentle parallax +// Basic { type: 'ParallaxScroll' } -// Strong parallax effect -{ type: 'ParallaxScroll', speed: 0.8 } - -// Reverse parallax (moves opposite) +// Reverse parallax (moves opposite to scroll) { type: 'ParallaxScroll', speed: -0.3 } - -// Subtle depth layer -{ type: 'ParallaxScroll', speed: 0.2 } ``` ## Related Presets From d0d2451a7830cf03929236ceb552b3f097d74012 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Tue, 20 Jan 2026 16:00:26 +0200 Subject: [PATCH 03/20] Update PLAN.md for motion presets: fix lint issues --- packages/motion-presets/rules/presets/PLAN.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 9cb3fc2f..3892e4c7 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -51,8 +51,7 @@ Generate 2-3 sample rule files per category to validate format: | mouse | Tilt3DMouse, TrackMouse, BounceMouse | -| background-scroll | BgParallax, BgZoom, BgFade | - +| background-scroll | BgParallax, BgZoom, BgFade | **Total pilot files: ~14 files** ### Phase 2: Review @@ -113,11 +112,13 @@ fade in, appear, materialize, opacity transition, gentle reveal **This section requires manual writing.** Describe what the user SEES in plain, non-technical language. Focus on the visual experience, not implementation details. **DO describe:** + - What the element looks like during the animation (fades, moves, rotates, scales) - The path or direction of movement (straight, curved, from where to where) - The overall feeling (smooth, bouncy, snappy, dramatic, subtle) **DO NOT reference:** + - CSS properties (translateY, perspective, rotateX) - Keyframe percentages or offsets - Easing function names @@ -157,8 +158,7 @@ fade in, appear, materialize, opacity transition, gentle reveal ### 6. Parameters -**Use TypeScript notation.** Pull min/max/step/enum from `@wix/effects-kit` ([wix-private/wow-libs/effects-kit](https://github.com/wix-private/wow-libs/tree/master/packages/effects-kit)). - +**Use TypeScript notation.** Pull min/max/step/enum from `@wix/effects-kit` ([wix-private/wow-libs/effects-kit](https://github.com/wix-private/wow-libs/tree/master/packages/effects-kit)). **IMPORTANT: Parameter Subsets Vary Per Preset** Different presets support different subsets of enum values: @@ -312,10 +312,6 @@ Common parameters (but presets may use subsets): > **See**: [rules/presets/entrance/arc-in.md](rules/presets/entrance/arc-in.md) after generation -
- -Click to expand full sample: arc-in.md - **Frontmatter:** ```yaml @@ -415,7 +411,7 @@ choose_alternative_when: ## File Organization -``` +```text rules/presets/ ├── README.md # Master index ├── entrance/ # 24 files @@ -449,4 +445,4 @@ rules/presets/ 4. **Parameters**: Combine TypeScript types from `motion-presets` with constraints from `effects-kit`. **Always check each preset's specific file** - they override base params with different enum subsets 5. **Direction/Easing subsets**: Document the exact subset each preset supports, not the base type. Clipped animations (ShapeIn, RevealIn, ShuttersIn, WinkIn) exclude back easings 6. **Cross-trigger mapping**: Map entrance presets to their scroll/mouse equivalents where they exist (e.g., ArcIn ↔ ArcScroll) -7. **Tags**: Derive from visual characteristics, use cases, and motion type \ No newline at end of file +7. **Tags**: Derive from visual characteristics, use cases, and motion type From a1754030fb614197c749f339e5c4d6e0e57a140c Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Tue, 20 Jan 2026 17:33:13 +0200 Subject: [PATCH 04/20] Restructure LLM preset rules with two-level hierarchy - Add 5 category files (entrance.md, scroll.md, ongoing.md, mouse.md, background-scroll.md) with decision guides - Each preset now has tags and synonyms for better LLM intent matching - Simplified preset files to focus on visual description, parameters, examples - Added accessibility considerations section to category files - Added time units (ms) to all duration/delay parameters - Updated PLAN.md with new structure and guidelines --- packages/motion-presets/rules/presets/PLAN.md | 598 +++++++++--------- .../rules/presets/background-scroll.md | 168 +++++ .../presets/background-scroll/bg-fade.md | 90 +-- .../presets/background-scroll/bg-parallax.md | 84 +-- .../presets/background-scroll/bg-zoom.md | 90 +-- .../motion-presets/rules/presets/entrance.md | 231 +++++++ .../rules/presets/entrance/arc-in.md | 111 ++-- .../rules/presets/entrance/bounce-in.md | 114 ++-- .../rules/presets/entrance/fade-in.md | 88 +-- .../motion-presets/rules/presets/mouse.md | 174 +++++ .../rules/presets/mouse/bounce-mouse.md | 95 ++- .../rules/presets/mouse/tilt-3d-mouse.md | 106 ++-- .../rules/presets/mouse/track-mouse.md | 112 ++-- .../motion-presets/rules/presets/ongoing.md | 175 +++++ .../rules/presets/ongoing/bounce.md | 95 ++- .../rules/presets/ongoing/pulse.md | 100 ++- .../rules/presets/ongoing/spin.md | 104 ++- .../motion-presets/rules/presets/scroll.md | 214 +++++++ .../rules/presets/scroll/arc-scroll.md | 107 ++-- .../rules/presets/scroll/fade-scroll.md | 102 ++- .../rules/presets/scroll/parallax-scroll.md | 104 ++- 21 files changed, 1867 insertions(+), 1195 deletions(-) create mode 100644 packages/motion-presets/rules/presets/background-scroll.md create mode 100644 packages/motion-presets/rules/presets/entrance.md create mode 100644 packages/motion-presets/rules/presets/mouse.md create mode 100644 packages/motion-presets/rules/presets/ongoing.md create mode 100644 packages/motion-presets/rules/presets/scroll.md diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 3892e4c7..5a1589db 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -1,33 +1,33 @@ --- name: Generate LLM Preset Rules -overview: Create concise, structured rule files for all 83 motion presets to help LLMs understand when to use each preset and generate appropriate implementation code. +overview: Create two-level rule files (category + preset) optimized for LLM decision flow. todos: - - id: setup - content: Create directory structure and copy plan to rules/presets/ - status: in_progress - - id: pilot-entrance - content: "PILOT: Generate 2-3 entrance rules (FadeIn, ArcIn, BounceIn) for review" + - id: restructure + content: "Restructure: Create category files, update existing preset files to new format" status: pending - - id: pilot-scroll - content: "PILOT: Generate 2-3 scroll rules (ParallaxScroll, FadeScroll, ArcScroll)" + - id: category-entrance + content: "Create entrance.md category file with decision guide" status: pending - - id: pilot-ongoing - content: "PILOT: Generate 2-3 ongoing rules (Pulse, Bounce, Spin)" + - id: category-scroll + content: "Create scroll.md category file with decision guide" status: pending - - id: pilot-mouse - content: "PILOT: Generate 2-3 mouse rules (Tilt3DMouse, TrackMouse, BounceMouse)" + - id: category-ongoing + content: "Create ongoing.md category file with decision guide" status: pending - - id: pilot-background - content: "PILOT: Generate 2-3 background-scroll rules (BgParallax, BgZoom, BgFade)" + - id: category-mouse + content: "Create mouse.md category file with decision guide" + status: pending + - id: category-background + content: "Create background-scroll.md category file with decision guide" + status: pending + - id: update-presets + content: "Update existing preset files to simplified format (remove when-to-use, alternatives)" status: pending - id: review - content: Review pilot files with user, adjust format if needed + content: "Review new structure with user" status: pending - id: generate-remaining - content: Generate remaining ~70 preset rule files - status: pending - - id: create-index - content: Create master index/README in rules/presets/ + content: "Generate remaining preset files" status: pending --- @@ -35,378 +35,384 @@ todos: ## Execution Phases -### Phase 1: Pilot (Current) +### Phase 1: Create Category Files (Current) -Generate 2-3 sample rule files per category to validate format: +Create 5 category-level files with decision guides: -| Category | Pilot Presets | +- `entrance.md` - Decision guide for 24 entrance presets +- `scroll.md` - Decision guide for 20 scroll presets +- `ongoing.md` - Decision guide for 14 ongoing presets +- `mouse.md` - Decision guide for 13 mouse presets +- `background-scroll.md` - Decision guide for 12 background-scroll presets -|----------|---------------| +### Phase 2: Update Existing Preset Files -| entrance | FadeIn, ArcIn, BounceIn | +Update the 15 pilot preset files to the simplified format: -| scroll | ParallaxScroll, FadeScroll, ArcScroll | +- Remove: When to Use, When NOT to Use, Related Presets, Decision Hints +- Keep: Visual Description, Parameters, Examples -| ongoing | Pulse, Bounce, Spin | +### Phase 3: Review & Complete -| mouse | Tilt3DMouse, TrackMouse, BounceMouse | +- Review new structure with user +- Generate remaining ~70 preset files -| background-scroll | BgParallax, BgZoom, BgFade | -**Total pilot files: ~14 files** +--- -### Phase 2: Review +## Structure Overview -Review pilot files, adjust format based on feedback. +**Two-level hierarchy optimized for LLM decision flow:** -### Phase 3: Complete Generation +### Level 1: Category Files (Decision Layer) -Generate remaining ~70 preset rule files + master index. +- `rules/presets/entrance.md` - When to use entrance, comparison of all 24 presets +- `rules/presets/scroll.md` - When to use scroll, comparison of all 20 presets +- `rules/presets/ongoing.md` - When to use ongoing, comparison of all 14 presets +- `rules/presets/mouse.md` - When to use mouse, comparison of all 13 presets +- `rules/presets/background-scroll.md` - When to use background-scroll, comparison of all 12 presets ---- +### Level 2: Preset Files (Detail Layer) -## Structure Overview +- `rules/presets/entrance/arc-in.md` - Visual description, parameters, examples +- `rules/presets/entrance/fade-in.md` - Visual description, parameters, examples +- etc. -Create rule markdown files mirroring the docs structure: +**Why this structure?** +LLM decision flow is a waterfall - it won't read all preset descriptions before selecting. It needs: -- `rules/presets/entrance/` (24 presets) -- `rules/presets/scroll/` (20 presets) -- `rules/presets/ongoing/` (14 presets) -- `rules/presets/mouse/` (13 presets) -- `rules/presets/background-scroll/` (12 presets) +1. First: "Which category?" → Read category file +2. Then: "Which preset?" → Use decision table in category file +3. Finally: "How to configure?" → Read specific preset file -## Rule File Format +## Category File Format -Each rule file will be optimized for LLM token efficiency. +Each category file guides the LLM to select the right preset. --- -### 1. Header (YAML frontmatter) +### Category File Sections + +#### 1. Header (YAML frontmatter) ```yaml -name: PresetName -category: entrance | scroll | ongoing | mouse | backgroundScroll -tags: [tag1, tag2, tag3, ...] # Semantic search keywords +name: Entrance Animations +category: entrance +tags: [appear, reveal, enter, load, show, intro, page-load, modal, popup] ``` -Tags are searchable intent keywords to help LLM match user requests: +Tags help LLM match user intent via semantic search. -- Motion type: `fade`, `slide`, `rotate`, `scale`, `3d`, `blur` -- Tone: `subtle`, `dramatic`, `playful`, `professional` -- Context: `entrance`, `hero`, `modal`, `cards`, `list-items` +#### 2. Description & Synonyms ---- +Verbose overview of the category with alternative phrasings: -### 2. Synonyms +```markdown +## Description -Natural language variations to help LLM match user intent (3-7 alternatives): +Entrance animations bring elements into view for the first time. They create the initial +impression and set the tone for user interaction. These are one-shot animations that play +once when an element first appears. -```markdown ## Synonyms -fade in, appear, materialize, opacity transition, gentle reveal + +appear animation, reveal effect, intro animation, show animation, enter animation, +page load animation, element appearance, fade in effect, loading animation ``` ---- +#### 3. When to Use This Category -### 3. Visual Description (Human-written) +When should an LLM choose this category over others: -**This section requires manual writing.** Describe what the user SEES in plain, non-technical language. Focus on the visual experience, not implementation details. +```markdown +## When to Use Entrance Animations -**DO describe:** +- Elements appearing for the first time on page load +- Modal/overlay/popup appearances +- Content revealing after user action (click, tab switch) +- Elements entering viewport (triggered once, not scroll-driven) +- First-time visibility of lazy-loaded content -- What the element looks like during the animation (fades, moves, rotates, scales) -- The path or direction of movement (straight, curved, from where to where) -- The overall feeling (smooth, bouncy, snappy, dramatic, subtle) +## When NOT to Use -**DO NOT reference:** +- Scroll-driven reveals → use Scroll animations +- Continuous/looping animations → use Ongoing animations +- Mouse-reactive elements → use Mouse animations +- Background media → use Background Scroll animations +``` -- CSS properties (translateY, perspective, rotateX) -- Keyframe percentages or offsets -- Easing function names -- Implementation details (800px perspective, 70% of animation) +#### 4. Accessibility Considerations -**Good example for ArcIn:** -> Element swings into view along a curved path, like a door opening towards you. It starts tilted away and gradually flattens as it settles into place. Fades in while moving. Creates a dramatic, cinematic reveal with depth. +Important for inclusive design: -**Bad example (too technical):** -> Uses perspective(800px) with rotateX/Y transforms. Opacity fades from 0 to 1 during first 70% with sineIn easing. Main arc uses quintInOut. +```markdown +## Accessibility Considerations ---- +- **Respect prefers-reduced-motion**: Use FadeIn as fallback or disable animations entirely +- **Duration guidelines**: Keep under 500ms for functional UI, up to 1200ms for decorative +- **Avoid vestibular triggers**: Limit large-scale movement, spinning, parallax for motion-sensitive users +- **Focus management**: Ensure animated elements don't interfere with keyboard focus order +- **Screen readers**: Animations are visual-only; ensure content is accessible without them +``` -### 4. When to Use +#### 5. Preset List with Tags and Synonyms -**Keep it short: 3-5 bullet points max.** Focus on the most common and confident use cases. +Each preset as a block with description, tags, and synonyms for LLM matching: ```markdown -- Hero sections needing dramatic reveal -- Featured/premium content -- Single focal elements +## Available Presets + +### FadeIn +**Description**: Gradual opacity transition from invisible to visible. Universal, subtle, accessibility-safe. +**Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear` +**Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance + +### ArcIn +**Description**: 3D curved swing like a door opening. Dramatic, cinematic, creates depth. +**Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium` +**Synonyms**: arc entrance, curved reveal, swing in, cinematic entrance, perspective reveal + +... ``` ---- +This format is optimal for LLM intent matching - tags and synonyms are explicitly labeled and grouped with each preset. -### 5. When NOT to Use +#### 6. Decision Guide -**Keep it short: 2-4 bullet points max.** Only the most important anti-patterns. +Help LLM choose between presets: ```markdown -- Multiple simultaneous elements -- Subtle/professional interfaces -- Mobile with performance concerns +## Decision Guide + +### By Tone +- **Subtle/Professional**: FadeIn, BlurIn, SlideIn +- **Dramatic/Cinematic**: ArcIn, FlipIn, TurnIn +- **Playful/Energetic**: BounceIn, SpinIn, PunchIn + +### By Use Case +- **Hero sections**: ArcIn, ExpandIn, GrowIn +- **Modals/Overlays**: FadeIn, DropIn +- **List items**: FadeIn, SlideIn (with stagger) +- **Notifications**: BounceIn, PunchIn + +### Reduced Motion Alternatives +Always provide a reduced-motion fallback: +- Complex animations → FadeIn +- Movement-based → FadeIn or no animation +- 3D/Spinning → FadeIn + +### Parallels in Other Categories +| Entrance | Scroll Equivalent | Mouse Equivalent | +|----------|-------------------|------------------| +| ArcIn | ArcScroll | - | +| FadeIn | FadeScroll | - | +| SpinIn | SpinScroll | SpinMouse | ``` --- -### 6. Parameters +### Preset File Sections -**Use TypeScript notation.** Pull min/max/step/enum from `@wix/effects-kit` ([wix-private/wow-libs/effects-kit](https://github.com/wix-private/wow-libs/tree/master/packages/effects-kit)). -**IMPORTANT: Parameter Subsets Vary Per Preset** +Each preset file contains the details needed AFTER the LLM has decided to use this preset. +Since category files handle decision-making, preset files can be more verbose about implementation details. -Different presets support different subsets of enum values: +#### 1. Preset Header (YAML frontmatter) -**Direction variants:** - -- `EffectFourDirections`: `'top' | 'right' | 'bottom' | 'left'` -- `EffectFiveDirections`: adds `'center'` -- `EffectEightDirections`: adds diagonals `'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'` -- `EffectNineDirections`: eight + `'center'` -- `EffectFourCorners`: `'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'` -- `EffectTwoDirections`: `'left' | 'right'` -- `EffectTwoAxes`: `'horizontal' | 'vertical'` - -**Easing variants:** - -- Full easing set available for most presets -- **Clipped/masked animations** (ShapeIn, RevealIn, ShuttersIn, etc.) exclude `backOut`, `backIn`, `backInOut` because overshoot breaks the clip boundary -- Some presets have preset-specific easing maps tied to `power` levels +```yaml +name: ArcIn +category: entrance +``` -Always document the **exact subset** supported by each preset, not the base type. +#### 2. Visual Description (Human-written, verbose) -Example: +**Describe what the user SEES in plain, non-technical language.** Be detailed and use analogies. -```typescript -interface ArcIn { - direction: 'top' | 'right' | 'bottom' | 'left'; // EffectFourDirections, default: 'left' - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - // Inherited from base - duration?: number; // min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // min: 0, max: 8000, step: 100, default: 0 - easing?: Easing; // default: 'quintInOut' -} -``` +**DO describe:** -Add brief impact notes: +- What the element looks like at the start, middle, and end +- The path or direction of movement +- The overall feeling (smooth, bouncy, dramatic) +- Real-world analogies (like a door opening, a ball bouncing, etc.) +- How opacity, scale, rotation, and position change -- `direction`: Determines rotation axis and arc path origin -- `power`: Controls rotation intensity (soft: 15°, medium: 30°, hard: 45°) +**DO NOT reference:** ---- +- CSS properties (translateY, perspective, rotateX) +- Keyframe percentages or offsets +- Easing function names (unless explaining power/easing parameter) +- Internal implementation details -### 7. Minimal Examples +**Example:** +> Element swings into view along a curved path, like a door opening towards you. At the start, +> the element is invisible and tilted away (as if rotated back into the screen). As the animation +> plays, it gradually rotates forward while simultaneously fading in. The element follows an arc +> trajectory rather than moving in a straight line, creating a sense of depth and dimension. +> By the end, it settles flat and fully visible in its final position. The motion feels cinematic +> and dramatic, best suited for hero elements that need to make an impression. -**Only include examples that show fundamentally different configurations.** Don't add examples just for variety. +#### 3. Parameters (detailed) -- Include basic/default usage -- Only add more examples if they demonstrate meaningfully different behavior (e.g., different direction that changes the visual, inverted mode, etc.) +**Use TypeScript notation.** Pull min/max/step/enum from `@wix/effects-kit`. +Include comprehensive parameter impact notes explaining what each value does visually. ```typescript -// Basic -{ type: 'ArcIn', direction: 'bottom' } - -// Only add if meaningfully different: -{ type: 'ArcIn', direction: 'left', power: 'hard' } +interface ArcIn { + direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 +} ``` -**Skip examples that only differ by duration, delay, or minor parameter tweaks.** +**Parameter Impact (verbose):** ---- +- `direction`: Controls which edge the element appears to swing from + - `top`: Element tilts forward (rotates on X-axis), appears to fall into place from above + - `bottom`: Element tilts backward, appears to rise up from below + - `left`: Element tilts sideways (rotates on Y-axis), swings in from the left + - `right`: Element tilts opposite direction, swings in from the right +- `power`: Controls how dramatic the rotation and arc appear + - `soft`: Subtle 15° rotation, gentle arc - good for supporting content + - `medium`: Balanced 30° rotation - the sweet spot for most uses + - `hard`: Dramatic 45° rotation with slight overshoot - attention-grabbing +- `duration`: How long the animation takes (1200ms default is cinematic, 600ms is snappy) +- `delay`: Wait time before animation starts (useful for staggered sequences) -### 8. Related Presets +#### 4. Best Practices -**Specifically highlight parallel presets across triggers:** +Tips for effective use of this specific preset: ```markdown -## Related Presets +## Best Practices -### Same Category (Entrance) -- **FlipIn** - Simpler 3D flip without arc motion -- **TurnIn** - Corner-based 3D rotation, more complex +- Use on single focal elements, not multiple simultaneous items +- Combine with stagger delay for sequential reveals +- Consider `power: 'soft'` for mobile devices +- Pair with complementary exit animation if element will be removed +``` -### Parallel in Other Triggers -- **ArcScroll** (scroll) - Same arc motion, scroll-driven -- **TiltScroll** (scroll) - Similar 3D tilt, scroll-driven +#### 5. Examples (with context) -### Alternatives -- **FadeIn** - When subtle is needed over dramatic -- **SlideIn** - When 2D motion is preferred over 3D -``` +Include examples with explanatory comments: ---- +```typescript +// Basic usage - element swings in from bottom +{ type: 'ArcIn', direction: 'bottom' } -### 9. Decision Hints (Optional) +// Hero section - dramatic entrance from side +{ type: 'ArcIn', direction: 'left', power: 'hard' } -Help LLM navigate similar presets: +// Subtle supporting content +{ type: 'ArcIn', direction: 'top', power: 'soft', duration: 800 } -```yaml -choose_this_when: - - "user wants 3D dramatic entrance" - - "hero section needs cinematic reveal" - - "premium/luxury brand feel" - -choose_alternative_when: - - "subtle needed" → FadeIn, BlurIn - - "2D motion preferred" → SlideIn, GlideIn - - "playful/bouncy" → BounceIn - - "scroll-driven" → ArcScroll +// Staggered cards (apply to each with increasing delay) +{ type: 'ArcIn', direction: 'bottom', delay: 0 } // Card 1 +{ type: 'ArcIn', direction: 'bottom', delay: 100 } // Card 2 +{ type: 'ArcIn', direction: 'bottom', delay: 200 } // Card 3 ``` +**Note:** "When to use", "When not to use", "Alternatives", and "Decision hints" remain in the **category file**. + --- -## Data Sources +--- -### From `motion-presets/src/types.ts` +## Sample Files -- TypeScript interface definitions -- Parameter types and optionality +### Sample Category File: entrance.md -### From `motion-presets/src/library/{category}/{Preset}.ts` +```markdown +--- +name: Entrance Animations +category: entrance +--- -- Default values in implementation -- Keyframe analysis for visual description cues -- Easing maps +# Entrance Animations -### From `effects-kit/src/effects/{category}/{preset}.ts` +## When to Use Entrance Animations -- `min`, `max`, `step` constraints -- `enum` options (check each preset - they override base enums!) -- `default` and `mobileDefault` values -- `units` for number-with-unit types -- Preset-specific schema overrides +- Elements appearing for the first time on page load +- Modal/overlay appearances +- Content revealing after user action +- Triggered once (not continuous or scroll-driven) -### From `effects-kit/src/effects/baseParams.ts` +## Available Presets -Common parameters (but presets may use subsets): +| Preset | Description | +|--------|-------------| +| FadeIn | Gradual opacity transition, subtle and universal | +| ArcIn | 3D curved swing, dramatic and cinematic | +| BounceIn | Playful bouncing, energetic | +| SlideIn | Straight movement from direction | +| FlipIn | 3D flip rotation | +| ... | ... | -- `duration`: min: 0, max: 4000, step: 100 -- `delay`: min: 0, max: 8000, step: 100 -- `power`: enum: `['soft', 'medium', 'hard']` -- `easing`: full set (but clipped animations exclude `back*` easings) +## Decision Guide -**Direction base types:** +### By Tone +- **Subtle/Professional**: FadeIn, BlurIn, SlideIn +- **Dramatic/Cinematic**: ArcIn, FlipIn, TurnIn +- **Playful/Energetic**: BounceIn, SpinIn, PunchIn -- `directionFourSides`: `['left', 'right', 'top', 'bottom']` -- `directionFiveSides`: four + `'center'` -- `directionEightSides`: four + diagonals -- `directionNineSides`: eight + `'center'` -- `directionFourCorners`: `['top-left', 'top-right', 'bottom-left', 'bottom-right']` -- `directionTwoSides`: `['left', 'right']` -- `directionTwoAxes`: `['horizontal', 'vertical']` +### By Use Case +- **Hero sections**: ArcIn, ExpandIn, GrowIn +- **Modals/Overlays**: FadeIn, DropIn +- **List items (staggered)**: FadeIn, SlideIn +- **Notifications/Badges**: BounceIn, PunchIn -**Easing base types:** +### Parallels in Other Categories -- `easing`: full set including `backIn`, `backOut`, `backInOut` -- `easingExcludingBackOut`: for clipped/masked animations +| Entrance | Scroll | Mouse | +|----------|--------|-------| +| ArcIn | ArcScroll | - | +| FadeIn | FadeScroll | - | +| SpinIn | SpinScroll | SpinMouse | +| - | ParallaxScroll | TrackMouse | +``` --- -## Sample Rule File - -> **See**: [rules/presets/entrance/arc-in.md](rules/presets/entrance/arc-in.md) after generation - -**Frontmatter:** +### Sample Preset File: entrance/arc-in.md -```yaml +```markdown +--- name: ArcIn category: entrance -tags: [3d, arc, curved, dramatic, cinematic, perspective, rotation, entrance] -``` - -**Synonyms:** - -> arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective reveal - -**Visual Description:** - -> Element swings into view along a curved path, like a door opening towards you. It starts tilted away and gradually flattens as it settles into place. Fades in while moving. The effect feels dramatic and cinematic, with a sense of depth. - -**When to Use:** +--- -- Hero sections needing dramatic reveal -- Premium/featured content -- Single focal elements requiring attention +# ArcIn -**When NOT to Use:** +## Visual Description -- Multiple simultaneous elements -- Subtle, professional interfaces -- Mobile with many animated elements +Element swings into view along a curved path, like a door opening towards you. +It starts tilted away and gradually flattens as it settles into place. +Fades in while moving. The effect feels dramatic and cinematic. -**Parameters:** +## Parameters -```typescript +\`\`\`typescript interface ArcIn { - direction: 'top' | 'right' | 'bottom' | 'left'; // EffectFourDirections, default: 'left' + direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - duration?: number; // min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // min: 0, max: 8000, step: 100, default: 0 - easing?: Easing; // full set supported, default: 'quintInOut' + duration?: number; // min: 0, max: 4000, default: 1200 + delay?: number; // min: 0, max: 8000, default: 0 } -``` +\`\`\` **Parameter Impact:** +- `direction`: top/bottom tilts forward/back, left/right tilts sideways +- `power`: soft = subtle, medium = noticeable, hard = dramatic -- `direction`: Determines rotation axis (top/bottom = X-axis, left/right = Y-axis) and arc origin -- `power`: Rotation intensity - soft: subtle tilt, medium: noticeable arc, hard: dramatic swing - -**Minimal Examples:** +## Examples -```typescript -// Basic - swings in from bottom +\`\`\`typescript +// Basic { type: 'ArcIn', direction: 'bottom' } -// Side entry (rotates on different axis) +// Side entry (tilts on different axis) { type: 'ArcIn', direction: 'left' } +\`\`\` ``` -**Related Presets:** - -| Category | Preset | Comparison | - -|----------|--------|------------| - -| Same (Entrance) | FlipIn | Simpler 3D flip, no arc path | - -| Same (Entrance) | TurnIn | Corner-based 3D rotation | - -| Same (Entrance) | CurveIn | Alternative curved 3D motion | - -| Parallel (Scroll) | ArcScroll | Arc motion driven by scroll position | - -| Parallel (Scroll) | TiltScroll | 3D tilt on scroll | - -| Alternative | FadeIn | When subtle is needed | - -| Alternative | SlideIn | When 2D motion preferred | - -| Alternative | GlideIn | Smooth 2D glide with direction control | - -**Decision Hints:** - -```yaml -choose_this_when: - - "dramatic 3D entrance needed" - - "hero/featured content" - - "cinematic feel" - - "premium brand" - -choose_alternative_when: - - subtle_needed: FadeIn, BlurIn - - 2d_preferred: SlideIn, GlideIn - - playful_bouncy: BounceIn - - scroll_driven: ArcScroll -``` - -
- --- ## File Organization @@ -414,23 +420,25 @@ choose_alternative_when: ```text rules/presets/ ├── README.md # Master index -├── entrance/ # 24 files +├── entrance.md # Category: when to use, decision guide +├── scroll.md # Category: when to use, decision guide +├── ongoing.md # Category: when to use, decision guide +├── mouse.md # Category: when to use, decision guide +├── background-scroll.md # Category: when to use, decision guide +├── entrance/ # Preset details (24 files) │ ├── fade-in.md │ ├── arc-in.md -│ ├── blur-in.md │ └── ... -├── scroll/ # 20 files +├── scroll/ # Preset details (20 files) │ ├── parallax-scroll.md -│ ├── arc-scroll.md │ └── ... -├── ongoing/ # 14 files +├── ongoing/ # Preset details (14 files) │ ├── pulse.md -│ ├── bounce.md │ └── ... -├── mouse/ # 13 files +├── mouse/ # Preset details (13 files) │ ├── tilt-3d-mouse.md │ └── ... -└── background-scroll/ # 12 files +└── background-scroll/ # Preset details (12 files) ├── bg-parallax.md └── ... ``` @@ -439,10 +447,36 @@ rules/presets/ ## Implementation Notes -1. **Visual Description**: Write in plain language describing what the user sees. NO technical terms (CSS properties, keyframe percentages, easing names). Use analogies and natural descriptions. -2. **When to Use / When NOT to Use**: Keep short (3-5 and 2-4 bullets respectively). Focus on high-confidence, common cases. -3. **Examples**: Only include if they show fundamentally different behavior. Skip examples that only differ by duration/delay. -4. **Parameters**: Combine TypeScript types from `motion-presets` with constraints from `effects-kit`. **Always check each preset's specific file** - they override base params with different enum subsets -5. **Direction/Easing subsets**: Document the exact subset each preset supports, not the base type. Clipped animations (ShapeIn, RevealIn, ShuttersIn, WinkIn) exclude back easings -6. **Cross-trigger mapping**: Map entrance presets to their scroll/mouse equivalents where they exist (e.g., ArcIn ↔ ArcScroll) -7. **Tags**: Derive from visual characteristics, use cases, and motion type +### Category Files (Verbose) + +1. **Header**: Include tags for semantic search matching +2. **Description & Synonyms**: Verbose overview with alternative phrasings +3. **When to Use / When NOT to Use**: Clear guidance on category selection +4. **Accessibility Considerations**: Reduced motion, vestibular safety, duration guidelines +5. **Preset List**: Brief 1-line descriptions for quick scanning +6. **Decision Guide**: Group by tone, use case, reduced-motion alternatives, cross-category parallels + +### Preset Files (Verbose) + +1. **Visual Description**: Detailed, use analogies, describe start/middle/end states +2. **Parameters**: TypeScript notation with comprehensive impact notes for each value +3. **Best Practices**: Tips specific to this preset +4. **Examples**: Multiple examples with explanatory comments, including stagger patterns + +### Data Sources + +- **Types**: `motion-presets/src/types.ts` +- **Constraints**: `effects-kit/src/effects/{category}/{preset}.ts` +- **Base params**: `effects-kit/src/effects/baseParams.ts` + +### Notes on Parameter Subsets + +- Direction types vary: FourDirections, FiveDirections (adds center), EightDirections (adds diagonals) +- Clipped animations (ShapeIn, RevealIn, ShuttersIn, WinkIn) exclude back easings + +### Accessibility Guidelines + +- Always mention `prefers-reduced-motion` media query support +- Recommend FadeIn as universal fallback +- Note vestibular triggers (spinning, parallax, large movement) +- Duration guidance: <500ms functional, <1200ms decorative diff --git a/packages/motion-presets/rules/presets/background-scroll.md b/packages/motion-presets/rules/presets/background-scroll.md new file mode 100644 index 00000000..6ad83f15 --- /dev/null +++ b/packages/motion-presets/rules/presets/background-scroll.md @@ -0,0 +1,168 @@ +--- +name: Background Scroll Animations +category: backgroundScroll +tags: [background, bg, scroll, section, hero, media, image, video, fullwidth, cinematic] +--- + +# Background Scroll Animations + +## Description + +Background Scroll animations are specifically designed for animating background media (images and videos) in response to scroll position. They're optimized for full-width section backgrounds and create immersive, cinematic effects as users scroll through a page. + +These differ from regular Scroll animations in that they target the background layer of a container rather than the element itself. They're perfect for hero sections, full-bleed images, and creating depth between content and backgrounds. + +## Synonyms + +background animation, bg scroll effect, background parallax, section background, hero background, scroll background, media background animation, full-width background, background reveal, cinematic background + +## When to Use Background Scroll Animations + +- **Hero sections**: Landing page heroes with depth/movement +- **Full-width section backgrounds**: Sections with background images/videos +- **Cinematic storytelling**: Narrative pages with immersive backgrounds +- **Portfolio/Photography**: Showcasing images with scroll-driven effects +- **Section transitions**: Visual interest between content sections +- **Depth/Layering**: Creating separation between background and content + +## When NOT to Use Background Scroll Animations + +- **Regular content elements** → use Scroll animations instead +- **Non-media backgrounds** → color backgrounds don't benefit from these +- **Mobile with performance concerns** → background effects are heavy; test carefully +- **Text-heavy sections** → effects may distract from reading +- **Multiple animated backgrounds** → performance and visual overload +- **Small background areas** → effects are less noticeable, not worth the cost + +## Accessibility Considerations + +- **Respect `prefers-reduced-motion`**: Disable all background scroll animations or use only subtle BgFade +- **Vestibular triggers**: BgParallax, BgZoom, BgRotate, and BgFake3D can trigger motion sickness. These effects are particularly problematic because they affect large areas of the screen +- **Performance on low-end devices**: Background animations are computationally expensive. Provide graceful degradation +- **Content readability**: Ensure text overlaying animated backgrounds remains readable throughout the scroll range +- **Contrast maintenance**: Animated backgrounds shouldn't cause text contrast to drop below WCAG requirements +- **Video backgrounds**: If using video, ensure it doesn't autoplay with sound and provide pause controls + +## Available Presets + +### BgParallax + +**Description**: Background moves slower than scroll creating depth illusion. Like background is further away than foreground content. +**Tags**: `parallax`, `depth`, `movement`, `slow`, `layer`, `distance`, `immersive` +**Synonyms**: background parallax, bg parallax, background scroll, parallax background, depth background + +### BgZoom + +**Description**: Background zooms in/out as user scrolls. Cinematic dolly-like effect, camera moving towards/away. +**Tags**: `zoom`, `scale`, `dolly`, `cinematic`, `dramatic`, `approach`, `retreat` +**Synonyms**: background zoom, bg zoom, zoom scroll, dolly zoom, zoom effect background, ken burns scroll + +### BgFade + +**Description**: Background opacity transition on scroll. Subtle fade in/out as section enters/exits viewport. +**Tags**: `fade`, `opacity`, `transition`, `subtle`, `reveal`, `in`, `out` +**Synonyms**: background fade, bg fade, fade background, background opacity, background reveal + +### BgFadeBack + +**Description**: Fade targeting back layer specifically. For layered backgrounds with separate fade control. +**Tags**: `fade`, `back`, `layer`, `opacity`, `separate`, `control` +**Synonyms**: bg fade back, back layer fade, layered fade, separate layer fade + +### BgPan + +**Description**: Horizontal/vertical background panning. Background slides across as user scrolls. +**Tags**: `pan`, `horizontal`, `vertical`, `slide`, `movement`, `traverse` +**Synonyms**: background pan, bg pan, pan scroll, horizontal background, sliding background + +### BgRotate + +**Description**: Background rotation driven by scroll. Dynamic unusual effect, background spins with scroll. +**Tags**: `rotate`, `spin`, `dynamic`, `unusual`, `creative`, `turn` +**Synonyms**: background rotate, bg rotate, spin background, rotation scroll, turning background + +### BgSkew + +**Description**: Background skew distortion on scroll. Experimental angled distortion effect. +**Tags**: `skew`, `distortion`, `angle`, `experimental`, `warp`, `tilt` +**Synonyms**: background skew, bg skew, skew scroll, distortion background, angled background + +### BgReveal + +**Description**: Clip-based background reveal. Theatrical curtain-like unveiling of background. +**Tags**: `reveal`, `clip`, `mask`, `theatrical`, `curtain`, `unveil`, `progressive` +**Synonyms**: background reveal, bg reveal, clip reveal, curtain background, unveiling background + +### BgCloseUp + +**Description**: Alternative zoom implementation. Cinematic close-up approach effect on background. +**Tags**: `closeup`, `zoom`, `cinematic`, `approach`, `alternative`, `scale` +**Synonyms**: bg close up, close up zoom, cinematic closeup, approach zoom + +### BgPullBack + +**Description**: Reverse zoom (pulling away). Expansive revealing effect, camera retreating from background. +**Tags**: `pullback`, `zoom`, `reverse`, `expansive`, `retreat`, `reveal`, `wide` +**Synonyms**: bg pull back, pull back zoom, reverse zoom, expansive reveal, retreat zoom + +### BgFake3D + +**Description**: Simulated 3D depth layers. Immersive parallax-enhanced depth simulation. +**Tags**: `fake3d`, `depth`, `layers`, `immersive`, `3d`, `parallax`, `simulation` +**Synonyms**: bg fake 3d, simulated 3d, depth layers, immersive background, 3d parallax + +### ImageParallax + +**Description**: Parallax for regular img elements (not CSS backgrounds). Same parallax effect for inline images. +**Tags**: `image`, `parallax`, `img`, `inline`, `element`, `depth` +**Synonyms**: image parallax, img parallax, inline image parallax, element parallax + +## Decision Guide + +### By Effect Type + +- **Movement/Depth**: BgParallax, BgPan, ImageParallax, BgFake3D +- **Scale/Zoom**: BgZoom, BgCloseUp, BgPullBack +- **Opacity**: BgFade, BgFadeBack +- **Rotation**: BgRotate +- **Distortion**: BgSkew +- **Reveal/Mask**: BgReveal + +### By Use Case + +- **Depth/Immersion**: BgParallax (most common), BgFake3D +- **Cinematic reveals**: BgZoom, BgCloseUp, BgReveal, BgPullBack +- **Section transitions**: BgFade, BgFadeBack +- **Creative/Experimental**: BgSkew, BgRotate +- **Horizontal storytelling**: BgPan + +### Background vs Regular Element Animations + +| Use Background Scroll for... | Use regular Scroll for... | +|------------------------------|---------------------------| +| `background-image` on sections | `` elements in flow | +| CSS background media | Content that scrolls with page | +| Full-width/full-height backgrounds | Individual elements | +| Media behind content | Media as content | + +**Exception**: `ImageParallax` is in this category but works on regular `` elements, not CSS backgrounds. + +### Reduced Motion Alternatives + +| Original | Reduced Motion Fallback | +|----------|------------------------| +| BgParallax | Static background (disable) | +| BgZoom, BgCloseUp, BgPullBack | BgFade or static | +| BgRotate, BgSkew | Disable | +| BgFake3D | Static or subtle BgParallax | +| BgFade | Keep (it's already subtle) | + +### Parallels in Other Categories + +| Background | Scroll | Entrance | +|------------|--------|----------| +| BgParallax | ParallaxScroll | - | +| BgZoom | GrowScroll | GrowIn | +| BgFade | FadeScroll | FadeIn | +| BgReveal | RevealScroll | RevealIn | +| BgRotate | SpinScroll | SpinIn | diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md index e5ab93bf..1288cc51 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md @@ -1,92 +1,66 @@ --- name: BgFade category: backgroundScroll -tags: [fade, background, scroll, opacity, reveal, transition] --- # BgFade -## Synonyms - -background fade, bg fade, fade background, background opacity, background reveal - ## Visual Description -Background gradually appears or disappears as you scroll through a section. In "in" mode, background fades from invisible to visible. In "out" mode, it fades away. Creates smooth transitions between sections. +Background opacity changes in response to scroll position, fading in as the section enters the viewport or fading out as it exits. This is the scroll-driven equivalent of FadeIn, applied specifically to background media. -## When to Use +**`range: 'in'`**: Background starts invisible (or semi-transparent) and gradually becomes fully visible as the user scrolls into the section. Creates a smooth reveal effect. -- Section transitions with background change -- Progressive background reveals -- Creating focus on content areas +**`range: 'out'`**: Background starts visible and gradually becomes invisible as the user scrolls past the section. Creates a graceful dismissal effect. -## When NOT to Use +**The visual effect**: Subtle and elegant. BgFade transitions backgrounds smoothly without the drama of zoom or parallax. It's perfect for section transitions, layered reveals, or guiding focus. -- When background must always be visible -- Critical visual information in background +This is one of the safest background scroll effects—it's subtle, doesn't cause motion sickness, and degrades gracefully. ## Parameters ```typescript interface BgFade { - range: 'in' | 'out'; // EffectRangeInOut, required - // Scroll range params - start?: number; // min: 0, max: 100, default: 0 (in) or 50 (out) - end?: number; // min: 0, max: 100, default: 50 (in) or 100 (out) + range: 'in' | 'out'; // required + start?: number; // %, min: 0, max: 100, default: 0 (in) or 50 (out) + end?: number; // %, min: 0, max: 100, default: 50 (in) or 100 (out) } ``` **Parameter Impact:** -- `range`: Fade direction - - `in`: Fades from transparent to visible (0→1) on entry - - `out`: Fades from visible to transparent (1→0) on exit -- `start`/`end`: Scroll position range for fade - - For `in`: Default 0-50 (fade completes by viewport center) - - For `out`: Default 50-100 (fade starts from viewport center) +- `range`: Fade direction (required) + - `in`: Background fades from transparent to visible as section enters + - `out`: Background fades from visible to transparent as section exits +- `start`/`end`: Scroll position range for the fade (0-100) + - Values represent percentage of element visibility in viewport + - **For `in`**: Default 0-50 means fade completes by mid-viewport + - **For `out`**: Default 50-100 means fade starts at mid-viewport + - Wider range = slower fade; narrower range = faster fade + +## Best Practices -## Minimal Examples +- **Combine in + out for full lifecycle**: Apply both for backgrounds that fade in and out +- **Adjust timing with start/end**: Want fade to complete earlier? Lower the `end` value +- **Use for section transitions**: Fade backgrounds between sections for smooth visual flow +- **Safe for reduced motion**: BgFade is subtle enough to keep in most cases +- **Test overlap with content**: Ensure fading background doesn't make content unreadable at any point + +## Examples ```typescript -// Fade in as section enters +// Basic - fade in as section enters { type: 'BgFade', range: 'in' } // Fade out as section exits { type: 'BgFade', range: 'out' } -``` - -## Related Presets - -### Same Category (Background Scroll) - -- **BgFadeBack** - Fade with different layer targeting -- **BgParallax** - Movement without fade -- **BgZoom** - Zoom effect on background - -### Parallel in Other Triggers - -- **FadeScroll** (scroll) - Fade for regular elements -- **FadeIn** (entrance) - Time-based fade entrance - -### Alternatives - -- **BgParallax** - When movement preferred over opacity -- **BgZoom** - When zoom effect preferred -- **FadeScroll** - For regular (non-background) elements -## Decision Hints +// Quick fade in (completes early) +{ type: 'BgFade', range: 'in', start: 0, end: 25 } -```yaml -choose_this_when: - - "background reveal/hide" - - "section transitions" - - "layered background effects" - - "focus control via background" - - "progressive disclosure" +// Slow fade in (completes late) +{ type: 'BgFade', range: 'in', start: 0, end: 75 } -choose_alternative_when: - - movement_based: BgParallax - - zoom_effect: BgZoom - - regular_elements: FadeScroll - - time_based: FadeIn +// Delayed fade out (starts later) +{ type: 'BgFade', range: 'out', start: 70, end: 100 } ``` diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md index e58c1e34..78ed100d 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md @@ -1,86 +1,60 @@ --- name: BgParallax category: backgroundScroll -tags: [parallax, background, scroll, depth, continuous, vertical] --- # BgParallax -## Synonyms - -background parallax, bg parallax, background scroll, parallax background, depth background - ## Visual Description -Background image or video moves slower than page scroll, creating an illusion of depth. Like the background is further away than the content in front of it. Subtle effect that adds visual richness without being distracting. +Background image or video moves at a different rate than the page scroll, creating an illusion of depth. As users scroll, the background shifts slower than the content in front of it, making it feel like it's further away—like distant scenery through a window. -## When to Use +**How it works**: The background's vertical position is adjusted based on scroll position, but at a slower rate than the scroll itself. When you scroll 100 pixels down, the background might only move 20-50 pixels. -- Hero sections with depth -- Full-width section backgrounds -- Landing pages with visual richness +**The visual effect**: Subtle depth and dimension without being distracting. The background feels "behind" the content, creating layers of depth. It's one of the most widely used scroll effects because it adds polish without overwhelming. -## When NOT to Use - -- Mobile with performance concerns -- Color-only backgrounds (no benefit) +This is specifically for CSS background images/videos on containers, not for regular `` elements in the content flow. ## Parameters ```typescript interface BgParallax { - speed?: number; // min: 0.05, max: 0.95, step: 0.01, default: 0.2 + speed?: number; // ratio, min: 0.05, max: 0.95, step: 0.01, default: 0.2 range?: 'continuous'; // only continuous supported } ``` **Parameter Impact:** -- `speed`: Rate of background movement (0.05-0.95) - - Lower values (0.1-0.2): Subtle, barely noticeable parallax - - Medium values (0.3-0.5): Noticeable depth effect - - Higher values (0.6-0.95): Dramatic, pronounced parallax - - Default 0.2 is subtle and safe for most uses - -## Minimal Examples +- `speed`: Rate of background movement relative to scroll (0.05-0.95) + - **0.05-0.2**: Very subtle, barely noticeable—safe, professional + - **0.2 (default)**: Subtle but perceptible—ideal starting point + - **0.3-0.5**: Noticeable depth effect—clearly parallax + - **0.6-0.95**: Strong parallax, dramatic movement—use carefully + - **Visual rule**: Lower speed = background feels further away +- `range`: Only `continuous` is supported + - Effect runs throughout entire time section is in viewport -```typescript -// Basic -{ type: 'BgParallax' } -``` +## Best Practices -## Related Presets +- **Start subtle (0.2)**: Increase only if depth effect isn't noticeable enough +- **Test on real content**: Parallax can make text over backgrounds harder to read +- **Consider mobile**: Background parallax can be janky on mobile—test or disable +- **One section at a time**: Multiple parallax backgrounds competing can feel chaotic +- **Use high-quality images**: Parallax reveals more of the background—ensure images are large enough and high-res -### Same Category (Background Scroll) +## Examples -- **BgZoom** - Zoom effect on background -- **BgFade** - Fade effect on background -- **BgPan** - Horizontal/vertical pan on background -- **ImageParallax** - For regular images (non-background) - -### Parallel in Other Triggers - -- **ParallaxScroll** (scroll) - Parallax for regular elements - -### Alternatives - -- **ParallaxScroll** - When animating regular elements -- **BgZoom** - When zoom effect preferred -- **BgFade** - When opacity transition preferred +```typescript +// Basic - subtle parallax (default) +{ type: 'BgParallax' } -## Decision Hints +// Very subtle (barely noticeable) +{ type: 'BgParallax', speed: 0.1 } -```yaml -choose_this_when: - - "background depth effect" - - "hero section immersion" - - "section visual interest" - - "landing page polish" - - "image/video backgrounds" +// Noticeable depth effect +{ type: 'BgParallax', speed: 0.4 } -choose_alternative_when: - - regular_elements: ParallaxScroll - - zoom_effect: BgZoom - - fade_effect: BgFade - - horizontal_pan: BgPan +// Strong parallax (use sparingly) +{ type: 'BgParallax', speed: 0.6 } ``` diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md index 621d9f06..a7eb2158 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md @@ -1,36 +1,26 @@ --- name: BgZoom category: backgroundScroll -tags: [zoom, background, scroll, scale, depth, 3d, perspective] --- # BgZoom -## Synonyms - -background zoom, bg zoom, zoom scroll, dolly zoom, zoom effect background, ken burns scroll - ## Visual Description -Background image zooms in or out as you scroll, like a camera dolly move. Creates a cinematic, dramatic effect where the background appears to move towards or away from you. +Background image scales up or down as the user scrolls, creating a cinematic dolly-like effect. The background appears to move toward you (zooming in) or away from you (zooming out) as you scroll through the section. -## When to Use +**`direction: 'in'`**: Background starts at normal scale and gradually zooms in as scroll progresses. Creates a "moving closer" sensation, like approaching something. -- Cinematic hero sections -- Dramatic section reveals -- Photography/portfolio showcases +**`direction: 'out'`**: Background starts zoomed in and gradually zooms out. Creates an "expanding view" sensation, like pulling back to reveal more. -## When NOT to Use - -- Multiple sections with zoom -- Mobile with performance concerns +**The visual effect**: Dramatic, cinematic, and immersive. BgZoom transforms a static background into an active part of the scroll experience. It's attention-grabbing and best used for hero sections or focal points. ## Parameters ```typescript interface BgZoom { - direction: 'in' | 'out'; // EffectRangeInOut, default: 'in' - zoom?: number; // min: 0.1, max: 10, step: 0.1, default: 10 + direction: 'in' | 'out'; // default: 'in' + zoom?: number; // multiplier, min: 0.1, max: 10, step: 0.1, default: 10 range?: 'continuous'; // only continuous supported } ``` @@ -38,56 +28,38 @@ interface BgZoom { **Parameter Impact:** - `direction`: Zoom behavior - - `in`: Background zooms in (towards viewer) as scroll progresses - - `out`: Background zooms out (away from viewer), uses 0.375x factor -- `zoom`: Maximum zoom amount (0.1-10) - - Lower values (1-3): Subtle zoom - - Medium values (5-7): Noticeable cinematic zoom - - Higher values (8-10): Dramatic, pronounced zoom + - `in` (default): Background zooms in as scroll progresses—feels like approaching + - `out`: Background zooms out—feels like pulling back/revealing +- `zoom`: Maximum zoom magnitude (0.1-10) + - **1-3**: Subtle zoom, barely noticeable—safe for most uses + - **4-6**: Medium zoom, clearly cinematic—good for hero sections + - **7-10**: Dramatic zoom—very attention-grabbing, use sparingly + - **10 (default)**: Maximum drama—ensure this fits your design +- `range`: Only `continuous` is supported + +## Best Practices -## Minimal Examples +- **Default zoom (10) is dramatic**: Consider starting with 3-5 for more subtle effect +- **One zooming background per page**: Multiple competing zooms are overwhelming +- **Ensure image resolution**: Zooming in reveals imperfections—use high-res images +- **Consider content overlap**: Ensure zooming doesn't make text over background harder to read +- **Test on mobile**: Zoom effects can be performance-heavy + +## Examples ```typescript -// Zoom in as you scroll +// Basic - zooms in as you scroll { type: 'BgZoom', direction: 'in' } -// Zoom out as you scroll +// Zoom out (revealing, expanding view) { type: 'BgZoom', direction: 'out' } -``` - -## Related Presets - -### Same Category (Background Scroll) - -- **BgParallax** - Movement without zoom -- **BgFade** - Opacity-based transition -- **BgCloseUp** - Similar zoom with different implementation -- **BgPullBack** - Reverse zoom effect - -### Parallel in Other Triggers - -- **GrowScroll** (scroll) - Scale effect for regular elements -- **ShrinkScroll** (scroll) - Shrink effect for regular elements - -### Alternatives - -- **BgParallax** - When subtle movement preferred -- **BgCloseUp** - Alternative zoom implementation -- **BgFade** - When opacity transition preferred -## Decision Hints +// Subtle zoom in +{ type: 'BgZoom', direction: 'in', zoom: 3 } -```yaml -choose_this_when: - - "cinematic background effect" - - "dramatic section reveal" - - "hero with depth" - - "photography showcase" - - "dolly zoom feel" +// Medium dramatic zoom +{ type: 'BgZoom', direction: 'in', zoom: 6 } -choose_alternative_when: - - subtle_movement: BgParallax - - opacity_transition: BgFade - - alternative_zoom: BgCloseUp - - regular_elements: GrowScroll +// Dramatic full zoom +{ type: 'BgZoom', direction: 'in', zoom: 10 } ``` diff --git a/packages/motion-presets/rules/presets/entrance.md b/packages/motion-presets/rules/presets/entrance.md new file mode 100644 index 00000000..472b022f --- /dev/null +++ b/packages/motion-presets/rules/presets/entrance.md @@ -0,0 +1,231 @@ +--- +name: Entrance Animations +category: entrance +tags: [entrance, appear, reveal, enter, load, show, intro, page-load, modal, popup, first-time, visibility] +--- + +# Entrance Animations + +## Description + +Entrance animations bring elements into view for the first time. They create the initial impression and set the tone for user interaction. These are one-shot animations that play once when an element first appears, whether on page load, after a user action, or when content becomes visible. + +Entrance animations are the most commonly used animation category. They help establish visual hierarchy, guide user attention, and make interfaces feel polished and responsive. A well-chosen entrance animation can make the difference between a static, lifeless page and an engaging, dynamic experience. + +## Synonyms + +appear animation, reveal effect, intro animation, show animation, enter animation, page load animation, element appearance, fade in effect, loading animation, first-time visibility, content reveal, emergence effect + +## When to Use Entrance Animations + +- **Page load reveals**: Elements appearing when the page first loads +- **Modal/overlay/popup appearances**: Dialogs, tooltips, dropdowns appearing +- **Content revealing after user action**: Click, tab switch, accordion expand +- **Elements entering viewport once**: Triggered once (not scroll-driven continuous) +- **Lazy-loaded content**: Images, cards, or sections loading asynchronously +- **State transitions**: Empty → populated states, loading → loaded + +## When NOT to Use Entrance Animations + +- **Scroll-driven reveals** → use Scroll animations instead +- **Continuous/looping animations** → use Ongoing animations instead +- **Mouse-reactive elements** → use Mouse animations instead +- **Background media** → use Background Scroll animations instead +- **Frequently toggled elements** → may cause animation fatigue + +## Accessibility Considerations + +- **Respect `prefers-reduced-motion`**: Always provide FadeIn as fallback or disable animations entirely for users who prefer reduced motion +- **Duration guidelines**: Keep animations under 500ms for functional UI elements (buttons, modals), up to 1200ms for decorative/hero content +- **Avoid vestibular triggers**: Limit large-scale movement, spinning (SpinIn), and 3D rotations for motion-sensitive users. BounceIn, ArcIn, FlipIn, and TurnIn can trigger vestibular disorders +- **Focus management**: Ensure animated elements don't interfere with keyboard focus order. Modal entrances should trap focus appropriately +- **Screen readers**: Animations are visual-only; ensure all content is accessible without them. Use `aria-live` regions for dynamic content +- **Reduced motion fallback order**: SpinIn/FlipIn → FadeIn, BounceIn → FadeIn or SlideIn, ArcIn → FadeIn + +## Available Presets + +### FadeIn + +**Description**: Gradual opacity transition from invisible to visible. No movement or shape changes - just smooth materialization. The simplest and most universally applicable entrance. +**Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear`, `universal`, `accessible` +**Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance, dissolve in + +### ArcIn + +**Description**: 3D curved swing like a door opening towards you. Starts tilted away and gradually flattens as it settles. Dramatic, cinematic, creates depth. +**Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium`, `hero` +**Synonyms**: arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective reveal, dramatic arc, door opening + +### BlurIn + +**Description**: Element transitions from blurry to sharp focus while fading in. Soft, dreamy, draws attention to the sharpening moment. +**Tags**: `blur`, `focus`, `soft`, `dreamy`, `gentle`, `elegant`, `attention` +**Synonyms**: blur reveal, focus in, soft reveal, dreamy entrance, blur to focus, defocus to focus + +### BounceIn + +**Description**: Playful bouncing physics - overshoots landing spot then bounces smaller and smaller until settled. Fun, energetic, attention-grabbing. +**Tags**: `bounce`, `playful`, `energetic`, `fun`, `elastic`, `spring`, `attention`, `physics` +**Synonyms**: bounce entrance, bouncy reveal, spring in, elastic entrance, playful appear, jump in, hop in + +### CircleIn + +**Description**: Circular mask expanding from center point to reveal element. Geometric, modern, spotlight-like effect. +**Tags**: `circle`, `mask`, `geometric`, `modern`, `spotlight`, `radial`, `reveal` +**Synonyms**: circle reveal, radial reveal, spotlight entrance, circular mask, expanding circle + +### CurveIn + +**Description**: Alternative curved 3D motion path. Similar to ArcIn but with different trajectory characteristics. +**Tags**: `3d`, `curve`, `path`, `motion`, `trajectory`, `cinematic` +**Synonyms**: curved entrance, path reveal, curved motion, trajectory entrance + +### DropIn + +**Description**: Falls from above with subtle scale/bounce on landing. Gravity-like, natural feeling entrance with soft impact. +**Tags**: `drop`, `fall`, `gravity`, `natural`, `scale`, `bounce`, `impact`, `landing` +**Synonyms**: drop entrance, fall in, gravity drop, landing animation, drop down + +### ExpandIn + +**Description**: Expands outward from center point. Growing, revealing, spotlight-like emergence effect. +**Tags**: `expand`, `grow`, `center`, `scale`, `emergence`, `spotlight`, `reveal` +**Synonyms**: expand entrance, growing reveal, center expand, emergence, outward growth + +### FlipIn + +**Description**: 3D card flip rotation to reveal element. Dramatic, reveals "other side", card-like metaphor. +**Tags**: `flip`, `3d`, `rotation`, `card`, `dramatic`, `reveal`, `turn` +**Synonyms**: flip entrance, card flip, 3d flip, flip reveal, turn over, flip animation + +### FloatIn + +**Description**: Gentle floating/drifting entrance. Ethereal, light, dreamy movement as if carried by air. +**Tags**: `float`, `drift`, `ethereal`, `light`, `dreamy`, `gentle`, `air`, `soft` +**Synonyms**: float entrance, drift in, floating reveal, ethereal entrance, airy entrance + +### FoldIn + +**Description**: Paper-folding 3D effect. Origami-like, creative, element unfolds into view. +**Tags**: `fold`, `3d`, `paper`, `origami`, `creative`, `unfold`, `dimensional` +**Synonyms**: fold entrance, paper fold, origami reveal, unfold animation, folding entrance + +### GlideIn + +**Description**: Smooth 2D glide from direction with angle control. Clean, directional, professional movement. +**Tags**: `glide`, `slide`, `smooth`, `directional`, `clean`, `professional`, `angle` +**Synonyms**: glide entrance, smooth slide, directional glide, angled entrance, sliding reveal + +### GlitchIn + +**Description**: Digital glitch/distortion effect. Edgy, tech-inspired, disruptive visual entrance. +**Tags**: `glitch`, `digital`, `distortion`, `edgy`, `tech`, `disruption`, `modern`, `cyber` +**Synonyms**: glitch entrance, digital reveal, distortion entrance, tech glitch, cyber entrance + +### GrowIn + +**Description**: Scale from small to full size. Expanding, emerging, element grows into existence. +**Tags**: `grow`, `scale`, `expand`, `emerge`, `size`, `zoom`, `magnify` +**Synonyms**: grow entrance, scale up, expanding entrance, zoom in, size grow, emergence + +### PunchIn + +**Description**: Corner-based scale with energy and impact. Impactful, attention-grabbing, punchy entrance. +**Tags**: `punch`, `impact`, `corner`, `scale`, `energy`, `attention`, `bold`, `strong` +**Synonyms**: punch entrance, impact reveal, corner punch, bold entrance, powerful entrance + +### RevealIn + +**Description**: Directional clip/mask reveal like a curtain opening. Theatrical, unveiling, directional exposure. +**Tags**: `reveal`, `clip`, `mask`, `curtain`, `directional`, `theatrical`, `unveil` +**Synonyms**: reveal entrance, curtain reveal, clip reveal, unveiling, mask reveal, wipe in + +### ShapeIn + +**Description**: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise, customizable mask shapes. +**Tags**: `shape`, `mask`, `geometric`, `circle`, `square`, `diamond`, `precise`, `custom` +**Synonyms**: shape reveal, geometric reveal, mask entrance, shape mask, custom shape reveal + +### ShuttersIn + +**Description**: Venetian blind strip reveal. Segmented, rhythmic, strips revealing content progressively. +**Tags**: `shutters`, `blinds`, `strips`, `segmented`, `rhythmic`, `venetian`, `progressive` +**Synonyms**: shutters reveal, blind reveal, strip entrance, venetian entrance, segmented reveal + +### SlideIn + +**Description**: Straight movement from direction. Clean, simple, versatile directional entrance. +**Tags**: `slide`, `move`, `directional`, `clean`, `simple`, `versatile`, `translate` +**Synonyms**: slide entrance, slide in, directional slide, movement entrance, translate in + +### SpinIn + +**Description**: Rotating entrance with spin. Dynamic, playful, attention-grabbing rotation into view. +**Tags**: `spin`, `rotate`, `dynamic`, `playful`, `attention`, `rotation`, `turn` +**Synonyms**: spin entrance, rotating reveal, spin in, rotation entrance, twirl in + +### TiltIn + +**Description**: 3D tilt into view. Subtle depth, elegant perspective shift as element appears. +**Tags**: `tilt`, `3d`, `subtle`, `depth`, `elegant`, `perspective`, `angle` +**Synonyms**: tilt entrance, perspective tilt, 3d tilt, angled reveal, subtle 3d + +### TurnIn + +**Description**: Corner-pivot 3D rotation. Complex, dramatic, premium feeling entrance with pivot point. +**Tags**: `turn`, `3d`, `corner`, `pivot`, `dramatic`, `premium`, `complex`, `rotation` +**Synonyms**: turn entrance, corner turn, pivot reveal, 3d turn, corner rotation + +### WinkIn + +**Description**: Split-in-half reveal from center. Unique, eye-like opening, center-split entrance. +**Tags**: `wink`, `split`, `center`, `unique`, `eye`, `opening`, `divide` +**Synonyms**: wink entrance, split reveal, center split, eye opening, divide reveal + +## Decision Guide + +### By Tone + +- **Subtle/Professional**: FadeIn, BlurIn, SlideIn, GlideIn, TiltIn +- **Dramatic/Cinematic**: ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn +- **Playful/Energetic**: BounceIn, SpinIn, PunchIn, GlitchIn +- **Geometric/Modern**: CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn +- **Soft/Dreamy**: FloatIn, BlurIn, FadeIn + +### By Use Case + +- **Hero sections**: ArcIn, ExpandIn, GrowIn, FloatIn, RevealIn +- **Modals/Overlays**: FadeIn, DropIn, GrowIn, SlideIn +- **List items (staggered)**: FadeIn, SlideIn, GlideIn +- **Notifications/Badges**: BounceIn, PunchIn, DropIn +- **Cards**: FlipIn, ArcIn, TiltIn, FadeIn +- **Images/Media**: RevealIn, ShapeIn, ShuttersIn, CircleIn, BlurIn +- **Text content**: FadeIn, SlideIn, BlurIn +- **CTAs/Buttons**: BounceIn, PunchIn, GrowIn + +### Reduced Motion Alternatives + +Always provide a reduced-motion fallback. Recommended mappings: + +| Original | Reduced Motion Fallback | +|----------|------------------------| +| BounceIn, SpinIn, PunchIn | FadeIn | +| ArcIn, FlipIn, TurnIn | FadeIn | +| SlideIn, GlideIn | FadeIn (or keep with shorter duration) | +| ShuttersIn, ShapeIn | FadeIn | +| GlitchIn | FadeIn | + +### Parallels in Other Categories + +| Entrance | Scroll | Ongoing | Mouse | +|----------|--------|---------|-------| +| ArcIn | ArcScroll | - | - | +| FadeIn | FadeScroll | Flash | - | +| SpinIn | SpinScroll | Spin | SpinMouse | +| BounceIn | - | Bounce | BounceMouse | +| TiltIn | TiltScroll | - | Tilt3DMouse | +| FlipIn | FlipScroll | Flip | - | +| GrowIn | GrowScroll | - | ScaleMouse | +| SlideIn | SlideScroll | - | TrackMouse | +| BlurIn | BlurScroll | - | BlurMouse | +| RevealIn | RevealScroll | - | - | diff --git a/packages/motion-presets/rules/presets/entrance/arc-in.md b/packages/motion-presets/rules/presets/entrance/arc-in.md index b035bb46..249e1e75 100644 --- a/packages/motion-presets/rules/presets/entrance/arc-in.md +++ b/packages/motion-presets/rules/presets/entrance/arc-in.md @@ -1,96 +1,77 @@ --- name: ArcIn category: entrance -tags: [3d, arc, curved, dramatic, cinematic, perspective, rotation, entrance, premium] --- # ArcIn -## Synonyms - -arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective reveal, dramatic arc - ## Visual Description -Element swings into view along a curved path, like a door opening towards you. It starts tilted away and gradually flattens as it settles into place. Fades in while moving. The effect feels dramatic and cinematic, with a sense of depth. +Element swings into view along a curved arc path, like a door opening towards you or a card being dealt onto a table. The motion has a sense of depth and dimension—the element appears to exist in 3D space, rotating on an axis as it enters. -## When to Use +**At the start**: The element is invisible and tilted away from the viewer. Depending on the direction, it's either rotated back (like looking at the top of a tilted card), forward (like seeing the bottom edge), or sideways (like a door partially open). -- Hero sections needing dramatic reveal -- Premium/featured content -- Single focal elements requiring attention +**During the animation**: The element simultaneously fades in and rotates toward its final flat position. The rotation follows a smooth arc trajectory, not a linear path, which creates the cinematic "swinging" feel. The opacity increases as the rotation progresses. -## When NOT to Use +**At the end**: The element is fully visible and flat (no rotation), settled in its final position. -- Multiple simultaneous elements -- Subtle, professional interfaces -- Mobile with many animated elements +The effect feels dramatic, premium, and cinematic—best suited for hero elements, featured content, or moments where you want to make an impression. ## Parameters ```typescript interface ArcIn { - direction: 'top' | 'right' | 'bottom' | 'left'; // EffectFourDirections, default: 'left' + direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - duration?: number; // min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // min: 0, max: 8000, step: 100, default: 0 - easing?: Easing; // full set supported, default: 'quintInOut' + duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` **Parameter Impact:** -- `direction`: Determines rotation axis and arc origin - - `top`/`bottom`: Rotates on X-axis (tilts forward/backward) - - `left`/`right`: Rotates on Y-axis (tilts sideways) -- `power`: Controls easing curve and perceived intensity - - `soft`: `cubicInOut` - gentle, subtle arc - - `medium`: `quintInOut` - balanced, noticeable arc - - `hard`: `backOut` - dramatic with slight overshoot - -## Minimal Examples +- `direction`: Determines the rotation axis and where the element appears to come from + - `top`: Rotates on X-axis, element tilts forward as if falling into place from above + - `bottom`: Rotates on X-axis opposite direction, element rises up from below + - `left`: Rotates on Y-axis, element swings in from the left like a door opening + - `right`: Rotates on Y-axis opposite direction, swings in from the right + - **Visual tip**: `left`/`right` feel like hinged doors; `top`/`bottom` feel like flaps or lids +- `power`: Controls the intensity of the rotation and easing + - `soft`: ~15° rotation, gentle easing—subtle, elegant, good for supporting content + - `medium`: ~30° rotation, balanced easing—the sweet spot for most uses + - `hard`: ~45° rotation with slight overshoot—dramatic, attention-grabbing, use sparingly +- `duration`: Animation length + - **800-1000ms**: Snappy but still cinematic + - **1200ms (default)**: Balanced cinematic feel + - **1500-2000ms**: Very slow, dramatic, use for hero moments only +- `delay`: Pre-animation wait time, useful for sequencing + +## Best Practices + +- **Use on single focal elements**—ArcIn is dramatic and competes for attention. Don't use on multiple simultaneous elements +- **Consider mobile**: Use `power: 'soft'` on mobile devices for better performance and reduced motion intensity +- **Match direction to layout**: If content comes from the left side of the screen, use `direction: 'left'` +- **Pair with stagger for sequences**: If animating multiple items, use increasing `delay` values +- **Have a simpler fallback**: Use FadeIn for reduced-motion preference + +## Examples ```typescript -// Basic - swings in from bottom -{ type: 'ArcIn', direction: 'bottom' } - -// Side entry (tilts on different axis) -{ type: 'ArcIn', direction: 'left' } -``` - -## Related Presets - -### Same Category (Entrance) - -- **FlipIn** - Simpler 3D flip without arc path, just rotation -- **TurnIn** - Corner-based 3D rotation, more complex pivot point -- **CurveIn** - Alternative curved 3D motion, different path - -### Parallel in Other Triggers - -- **ArcScroll** (scroll) - Arc motion driven by scroll position -- **TiltScroll** (scroll) - 3D tilt on scroll, similar perspective - -### Alternatives +// Basic - swings in from left (default) +{ type: 'ArcIn' } -- **FadeIn** - When subtle is needed, reduced motion fallback -- **SlideIn** - When 2D motion preferred, less dramatic -- **GlideIn** - Smooth 2D glide with angle control +// Hero section - dramatic entrance from bottom +{ type: 'ArcIn', direction: 'bottom', power: 'hard' } -## Decision Hints +// Subtle supporting content +{ type: 'ArcIn', direction: 'left', power: 'soft', duration: 800 } -```yaml -choose_this_when: - - "dramatic 3D entrance needed" - - "hero/featured content" - - "cinematic feel" - - "premium brand" - - "single focal element" +// Side-by-side cards with stagger +{ type: 'ArcIn', direction: 'left', delay: 0 } // Left card +{ type: 'ArcIn', direction: 'right', delay: 150 } // Right card -choose_alternative_when: - - subtle_needed: FadeIn, BlurIn - - 2d_preferred: SlideIn, GlideIn - - playful_bouncy: BounceIn - - scroll_driven: ArcScroll - - simpler_3d: FlipIn +// Sequential vertical reveal +{ type: 'ArcIn', direction: 'top', delay: 0 } +{ type: 'ArcIn', direction: 'top', delay: 200 } +{ type: 'ArcIn', direction: 'top', delay: 400 } ``` diff --git a/packages/motion-presets/rules/presets/entrance/bounce-in.md b/packages/motion-presets/rules/presets/entrance/bounce-in.md index ebdb1c26..d238f5ef 100644 --- a/packages/motion-presets/rules/presets/entrance/bounce-in.md +++ b/packages/motion-presets/rules/presets/entrance/bounce-in.md @@ -1,100 +1,76 @@ --- name: BounceIn category: entrance -tags: [bounce, playful, energetic, fun, elastic, entrance, attention, spring] --- # BounceIn -## Synonyms - -bounce entrance, bouncy reveal, spring in, elastic entrance, playful appear, jump in, hop in - ## Visual Description -Element bounces into view with playful, physics-like motion. It overshoots its landing spot, then bounces back smaller and smaller until it settles. Like a ball dropping and bouncing to rest. Fades in as it enters. Creates a fun, energetic, attention-grabbing entrance. +Element bounces into view with playful, physics-inspired motion that mimics a ball dropping and bouncing to rest. The animation creates an energetic, fun, attention-grabbing entrance that feels alive and dynamic. -## When to Use +**At the start**: The element is invisible and positioned away from its final location (based on direction). If coming from `top`, it's above; if from `center`, it's scaled down like approaching from far away. -- Playful, fun brand interfaces -- Gamification elements and rewards -- Notification badges needing attention -- Call-to-action buttons +**During the animation**: The element moves toward its final position but overshoots it, then bounces back. This bounce-settle pattern repeats with decreasing amplitude—each bounce is smaller than the last—until the element comes to rest. Simultaneously, the element fades in during the initial approach. -## When NOT to Use +**At the end**: The element is fully visible, in its final position, completely settled with no residual motion. -- Professional/corporate interfaces -- Multiple simultaneous elements -- When subtle entrance is needed +The effect feels playful, energetic, and attention-grabbing. It's perfect for elements that should feel fun, alive, or important enough to demand attention. ## Parameters ```typescript interface BounceIn { - direction: 'top' | 'right' | 'bottom' | 'left' | 'center'; // EffectFiveDirections, default: 'top' + direction: 'top' | 'right' | 'bottom' | 'left' | 'center'; // default: 'top' power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - distanceFactor?: number; // min: 1, max: 4, step: 0.1, default: 1 (responsive only) - duration?: number; // min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // min: 0, max: 8000, step: 100, default: 0 + distanceFactor?: number; // min: 1, max: 4, step: 0.1, default: 1 + duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` **Parameter Impact:** -- `direction`: Origin of the bounce movement - - `top`: Bounces down from above - - `bottom`: Bounces up from below - - `left`/`right`: Bounces horizontally - - `center`: Bounces on Z-axis with 3D perspective (towards viewer) -- `power`: Controls bounce amplitude - - `soft`: Factor 1 - subtle bounces - - `medium`: Factor 2 - noticeable bounces - - `hard`: Factor 3 - dramatic, large bounces -- `distanceFactor`: Fine-grained control over bounce distance (1-4) - -## Minimal Examples +- `direction`: Origin point of the bounce + - `top`: Bounces down from above, like something dropping from the ceiling + - `bottom`: Bounces up from below, like something popping up from the ground + - `left`/`right`: Bounces horizontally, like something thrown from the side + - `center`: Bounces on Z-axis with 3D perspective—element appears to bounce toward the viewer from far away. Most dramatic option +- `power`: Controls bounce amplitude (how far it overshoots) + - `soft` (default): Factor 1, subtle bounces—professional enough for business contexts + - `medium`: Factor 2, noticeable bounces—clearly playful + - `hard`: Factor 3, dramatic large bounces—very energetic, potentially distracting +- `distanceFactor`: Fine-grained control over bounce travel distance (1-4) + - Lower values = tighter, more contained bounces + - Higher values = larger, more exaggerated bounces +- `duration`: Total animation time including all bounces + - **800-1000ms**: Quick, snappy bounces + - **1200ms (default)**: Balanced timing + - **1500ms+**: Slow, deliberate bounces + +## Best Practices + +- **Use for attention**: BounceIn demands attention—reserve for elements that deserve it (notifications, CTAs, rewards) +- **Limit to one element**: Multiple simultaneous bounces create visual chaos +- **Consider the context**: BounceIn is inherently playful; it may feel unprofessional in corporate/serious contexts +- **`center` direction is most dramatic**: Use for maximum impact, but it's also the most intense for motion-sensitive users +- **Reduced motion**: Always provide FadeIn fallback—bouncing can trigger vestibular discomfort + +## Examples ```typescript -// Basic - bounces down from top -{ type: 'BounceIn', direction: 'top' } - -// Bounces towards viewer (3D effect) -{ type: 'BounceIn', direction: 'center' } -``` - -## Related Presets - -### Same Category (Entrance) - -- **PunchIn** - Similar energy but with scale, corner-based -- **DropIn** - Single drop with scale, no bounce -- **SpinIn** - Rotation-based energetic entrance - -### Parallel in Other Triggers - -- **Bounce** (ongoing) - Continuous bouncing animation -- **BounceMouse** (mouse) - Bouncy response to mouse movement - -### Alternatives +// Basic - bounces down from above +{ type: 'BounceIn' } -- **FadeIn** - When subtle is needed, reduced motion fallback -- **SlideIn** - Same directional entrance without bounce -- **DropIn** - Single drop motion, more subtle than bounce +// Notification badge - subtle but noticeable +{ type: 'BounceIn', direction: 'top', power: 'soft' } -## Decision Hints +// Reward/Achievement popup - dramatic center bounce +{ type: 'BounceIn', direction: 'center', power: 'medium' } -```yaml -choose_this_when: - - "playful/fun interface" - - "attention-grabbing element" - - "gamification/rewards" - - "energetic brand tone" - - "notification/badge appearance" +// Playful CTA button +{ type: 'BounceIn', direction: 'bottom', power: 'medium', duration: 1000 } -choose_alternative_when: - - professional_tone: FadeIn, SlideIn - - subtle_needed: FadeIn, DropIn - - rotation_based: SpinIn - - scale_emphasis: PunchIn, GrowIn - - continuous_bounce: Bounce (ongoing) +// Chat message appearing (from side) +{ type: 'BounceIn', direction: 'left', power: 'soft', duration: 800 } ``` diff --git a/packages/motion-presets/rules/presets/entrance/fade-in.md b/packages/motion-presets/rules/presets/entrance/fade-in.md index 6585d5b6..184f1b6a 100644 --- a/packages/motion-presets/rules/presets/entrance/fade-in.md +++ b/packages/motion-presets/rules/presets/entrance/fade-in.md @@ -1,84 +1,62 @@ --- name: FadeIn category: entrance -tags: [fade, opacity, subtle, simple, professional, minimal, entrance, appear] --- # FadeIn -## Synonyms - -fade in, appear, materialize, opacity transition, gentle reveal, soft entrance, dissolve in - ## Visual Description -Element gradually appears from invisible to fully visible. No movement or shape changes - just a smooth, gentle materialization. The simplest and most universally applicable entrance animation. - -## When to Use - -- Subtle content reveals in professional interfaces -- Modal and overlay appearances -- Loading state transitions -- Reduced motion fallback +Element transitions smoothly from completely invisible (opacity 0) to fully visible (opacity 1). This is the simplest and most universal animation—there's no movement, rotation, scale change, or any other transformation. The element simply materializes in place, like a gentle reveal or a light gradually turning on. -## When NOT to Use +At the start, the element is entirely transparent. During the animation, opacity increases linearly until the element reaches full visibility. The effect is subtle, clean, and professional. It draws minimal attention to the animation itself, instead letting the content take focus. -- When attention needs to be drawn to element -- Hero sections where impact is needed +FadeIn is the safest animation choice—it works everywhere, doesn't trigger motion sensitivity issues, and serves as the ideal fallback for more complex animations when reduced motion is preferred. ## Parameters ```typescript interface FadeIn { - // No preset-specific parameters - duration?: number; // min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // min: 0, max: 8000, step: 100, default: 0 + duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` **Parameter Impact:** -- `duration`: Controls how quickly opacity transitions. Shorter (300-500ms) feels snappy, longer (800-1200ms) feels gentle -- `delay`: Useful for staggered reveals in sequences - -## Minimal Examples - -```typescript -// Basic -{ type: 'FadeIn' } -``` - -## Related Presets - -### Same Category (Entrance) +- `duration`: Controls how quickly the opacity transition completes + - **200-400ms**: Snappy, barely noticeable—good for functional UI elements like tooltips, dropdowns + - **500-800ms**: Balanced, noticeable but not slow—good for modals, cards + - **1000-1500ms**: Slow, deliberate—good for hero content, dramatic reveals + - **1200ms (default)**: The sweet spot for most decorative uses +- `delay`: Time before animation starts + - **0ms**: Immediate start + - **100-300ms**: Slight pause, useful for staggered sequences + - **500ms+**: Noticeable wait, use intentionally for dramatic effect -- **BlurIn** - Adds blur-to-focus effect alongside fade -- **DropIn** - Combines fade with subtle scale effect +## Best Practices -### Parallel in Other Triggers +- Use as the **default reduced-motion fallback** for all other entrance animations +- Keep duration under 500ms for functional UI (modals, dropdowns, tooltips) +- Combine with `delay` for elegant staggered list reveals +- Consider even shorter durations (200-300ms) for frequently shown/hidden elements +- Don't overthink it—FadeIn is often the right choice when you're unsure -- **FadeScroll** (scroll) - Opacity transition driven by scroll position -- **BgFade** (background-scroll) - Background-specific fade on scroll +## Examples -### Alternatives - -- **BlurIn** - When you want more visual interest than pure fade -- **SlideIn** - When directional context matters -- **GrowIn** - When scale emphasis is needed +```typescript +// Basic - default settings work for most cases +{ type: 'FadeIn' } -## Decision Hints +// Quick functional fade (modal, dropdown) +{ type: 'FadeIn', duration: 300 } -```yaml -choose_this_when: - - "subtle entrance needed" - - "professional/minimal UI" - - "reduced motion fallback" - - "multiple elements appearing" - - "modal/overlay appearance" +// Slow dramatic reveal (hero content) +{ type: 'FadeIn', duration: 1500 } -choose_alternative_when: - - attention_needed: BounceIn, PunchIn - - direction_matters: SlideIn, GlideIn - - more_visual_interest: BlurIn, DropIn - - dramatic_hero: ArcIn, FlipIn +// Staggered list items +{ type: 'FadeIn', delay: 0 } // Item 1 +{ type: 'FadeIn', delay: 100 } // Item 2 +{ type: 'FadeIn', delay: 200 } // Item 3 +{ type: 'FadeIn', delay: 300 } // Item 4 ``` diff --git a/packages/motion-presets/rules/presets/mouse.md b/packages/motion-presets/rules/presets/mouse.md new file mode 100644 index 00000000..2279421d --- /dev/null +++ b/packages/motion-presets/rules/presets/mouse.md @@ -0,0 +1,174 @@ +--- +name: Mouse Animations +category: mouse +tags: [mouse, cursor, hover, interactive, follow, track, pointer, mousemove, desktop, response] +--- + +# Mouse Animations + +## Description + +Mouse animations respond to cursor position, creating interactive elements that follow, tilt, or transform based on where the user's mouse is located. These animations create a sense of depth, interactivity, and playfulness that makes interfaces feel responsive and alive. + +Mouse animations are **desktop-only**—they require a mouse or trackpad and have no effect on touch devices. Always consider mobile fallbacks when using mouse animations. + +## Synonyms + +cursor animation, hover effect, mouse follow, cursor tracking, mouse parallax, interactive hover, pointer animation, mousemove effect, cursor response, mouse-driven animation, hover interaction + +## When to Use Mouse Animations + +- **Interactive cards/products**: Tilt effect on product images, cards +- **Parallax depth with cursor**: Layered elements responding to mouse +- **Hero section interactivity**: Adding depth and engagement to landing pages +- **Portfolio/showcase**: Interactive image galleries, project previews +- **Playful interfaces**: Game-like interactions, fun micro-interactions +- **Premium/luxury feel**: Subtle tilt effects convey quality + +## When NOT to Use Mouse Animations + +- **Mobile-first designs** → these simply won't work on touch devices +- **Clickable/interactive elements** → may interfere with click targets +- **Accessibility-critical interfaces** → mouse animations exclude keyboard users +- **Performance-sensitive pages** → constant calculations on mousemove +- **Multiple simultaneous effects** → visual overload, performance issues +- **Essential functionality** → never rely on mouse animation for core features + +## Accessibility Considerations + +- **Desktop-only limitation**: Mouse animations don't work on touch devices, keyboard navigation, or for users who can't use a mouse. Always ensure content is fully accessible without them +- **Respect `prefers-reduced-motion`**: Disable mouse animations entirely for users who prefer reduced motion +- **Vestibular concerns**: Tilt3DMouse, SpinMouse, and Track3DMouse with large values can cause discomfort. Keep effects subtle +- **Don't interfere with interaction**: Mouse animations shouldn't make it harder to click buttons, links, or form elements +- **Provide visual feedback alternatives**: If hover effects are important for understanding UI state, provide non-motion alternatives +- **Keyboard users excluded**: Mouse animations are invisible to keyboard navigators—don't use them to convey important information + +## Available Presets + +### Tilt3DMouse + +**Description**: Element tilts towards cursor like holding a card and angling it. 3D perspective rotation following mouse position. +**Tags**: `tilt`, `3d`, `perspective`, `card`, `rotate`, `angle`, `premium`, `interactive` +**Synonyms**: 3d tilt, mouse tilt, perspective tilt, interactive tilt, hover tilt, card tilt, gyroscope effect + +### TrackMouse + +**Description**: Element follows cursor position, moving in same direction. Floating object that drifts towards where you point. +**Tags**: `track`, `follow`, `translate`, `movement`, `parallax`, `float`, `drift` +**Synonyms**: mouse tracking, follow cursor, cursor follow, mouse movement, parallax mouse, floating follow + +### BounceMouse + +**Description**: Bouncy/elastic cursor following. Overshoots and wobbles before settling, springy playful motion. +**Tags**: `bounce`, `elastic`, `spring`, `playful`, `wobble`, `overshoot`, `jelly` +**Synonyms**: bouncy mouse, elastic follow, spring mouse, bouncy cursor effect, elastic tracking + +### Track3DMouse + +**Description**: Combined translation + 3D rotation following mouse. Complex immersive effect with movement and tilt. +**Tags**: `track`, `3d`, `translate`, `rotate`, `complex`, `immersive`, `combined` +**Synonyms**: 3d track mouse, combined mouse effect, translate and tilt, immersive mouse + +### SpinMouse + +**Description**: Rotation following mouse angle. Element spins/rotates based on cursor position around element. +**Tags**: `spin`, `rotate`, `angle`, `circular`, `dynamic`, `follow` +**Synonyms**: mouse spin, rotation follow, angle mouse, spinning cursor effect + +### ScaleMouse + +**Description**: Scale based on cursor distance. Element grows/shrinks depending on how close mouse is. +**Tags**: `scale`, `zoom`, `distance`, `proximity`, `grow`, `shrink`, `size` +**Synonyms**: scale mouse, zoom mouse, proximity scale, distance zoom, hover scale + +### SwivelMouse + +**Description**: Z-axis rotation following cursor. Unique gyroscope-like rotation on vertical axis. +**Tags**: `swivel`, `z-axis`, `rotate`, `gyroscope`, `unique`, `vertical` +**Synonyms**: swivel mouse, z rotation, gyroscope mouse, vertical rotation + +### SkewMouse + +**Description**: Skew distortion following cursor. Experimental angular distortion based on mouse position. +**Tags**: `skew`, `distortion`, `angle`, `experimental`, `warp`, `tilt` +**Synonyms**: skew mouse, distortion mouse, angle skew, warp mouse + +### BlurMouse + +**Description**: Blur based on cursor distance. Focus/defocus effect depending on mouse proximity. +**Tags**: `blur`, `focus`, `distance`, `proximity`, `defocus`, `depth` +**Synonyms**: blur mouse, focus mouse, proximity blur, distance focus + +### AiryMouse + +**Description**: Floating/airy cursor response. Ethereal, light movement as if carried by air currents. +**Tags**: `airy`, `float`, `ethereal`, `light`, `gentle`, `drift`, `soft` +**Synonyms**: airy mouse, floating mouse, ethereal cursor, light follow, gentle drift + +### BlobMouse + +**Description**: Organic blob-like deformation. Experimental fluid shape distortion following cursor. +**Tags**: `blob`, `organic`, `fluid`, `deform`, `experimental`, `shape`, `morph` +**Synonyms**: blob mouse, organic deform, fluid mouse, shape morph, blob effect + +### CustomMouse + +**Description**: Configurable custom behavior. Flexible preset for custom mouse-driven transformations. +**Tags**: `custom`, `configurable`, `flexible`, `advanced`, `custom-behavior` +**Synonyms**: custom mouse, configurable mouse, flexible mouse effect, advanced mouse + +## Decision Guide + +### By Effect Type + +- **Translation/Movement**: TrackMouse, BounceMouse, AiryMouse +- **3D Rotation/Tilt**: Tilt3DMouse, Track3DMouse, SwivelMouse +- **2D Rotation**: SpinMouse +- **Scale**: ScaleMouse +- **Distortion**: SkewMouse, BlobMouse +- **Blur**: BlurMouse + +### By Tone + +- **Professional/Premium**: Tilt3DMouse (subtle), TrackMouse (subtle), ScaleMouse +- **Playful/Fun**: BounceMouse, BlobMouse, AiryMouse +- **Game-like/Dynamic**: SpinMouse, Track3DMouse, SkewMouse +- **Experimental/Creative**: BlobMouse, SkewMouse + +### By Use Case + +- **Product cards/Images**: Tilt3DMouse, ScaleMouse +- **Hero section depth**: TrackMouse (multiple layers with different distances) +- **Interactive portfolios**: Tilt3DMouse, Track3DMouse +- **Playful interfaces**: BounceMouse, BlobMouse, AiryMouse +- **Decorative elements**: TrackMouse, SpinMouse +- **Focus/Attention**: ScaleMouse, BlurMouse + +### Important: Mobile Fallback Strategies + +Since mouse animations don't work on touch devices: + +1. **Do nothing**: Element remains static on mobile (acceptable for decorative effects) +2. **Use entrance animation**: Apply FadeIn or similar on mobile instead +3. **Use device orientation**: Some effects can map to device tilt (advanced) +4. **Touch-based alternative**: Respond to touch position (requires custom implementation) + +### Reduced Motion Alternatives + +| Original | Reduced Motion Fallback | +|----------|------------------------| +| Tilt3DMouse, Track3DMouse | Disable or very subtle scale | +| TrackMouse, BounceMouse | Disable | +| SpinMouse | Disable | +| All mouse animations | Static state | + +### Parallels in Other Categories + +| Mouse | Entrance | Scroll | Ongoing | +|-------|----------|--------|---------| +| Tilt3DMouse | TiltIn | TiltScroll | - | +| TrackMouse | GlideIn | ParallaxScroll | - | +| BounceMouse | BounceIn | - | Bounce | +| SpinMouse | SpinIn | SpinScroll | Spin | +| ScaleMouse | GrowIn | GrowScroll | Pulse | +| BlurMouse | BlurIn | BlurScroll | - | diff --git a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md index 2263947c..1ece0a4c 100644 --- a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md @@ -1,91 +1,70 @@ --- name: BounceMouse category: mouse -tags: [bounce, elastic, mouse, spring, playful, follow, interactive] --- # BounceMouse -## Synonyms - -bouncy mouse, elastic follow, spring mouse, bouncy cursor effect, elastic tracking - ## Visual Description -Element follows the mouse with a bouncy, springy motion. Like a jelly or rubber ball that overshoots and wobbles before settling. Creates a playful, game-like interaction feel. - -## When to Use +Element follows the mouse cursor with a bouncy, elastic motion. Instead of moving directly to follow the cursor, the element overshoots its target and wobbles back and forth before settling—like a jelly or rubber ball being pulled by an invisible string. -- Playful/fun interface elements -- Game-like interactions -- Mascot/character elements -- Child-friendly interfaces +**How it works**: Like TrackMouse, the element's position responds to cursor location. But instead of smooth easing, BounceMouse uses elastic/spring physics that cause the element to overshoot and oscillate before coming to rest. -## When NOT to Use +**The visual effect**: Playful, springy, and game-like. The bouncing creates a sense of fun and energy, like the element is alive and excited to follow your cursor. It's inherently casual and not suited for serious professional contexts. -- Professional/corporate interfaces -- When smooth following is preferred +**The difference from TrackMouse**: TrackMouse smoothly follows; BounceMouse bounces and wobbles. TrackMouse feels responsive and professional; BounceMouse feels playful and energetic. ## Parameters ```typescript interface BounceMouse { - distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // min: 5, max: 800, default: { value: 80, type: 'px' } + distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // default: { value: 80, type: 'px' } axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' inverted?: boolean; // default: false - transitionDuration?: number; // min: 0, max: 5000, step: 20, default: 500 + transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 transitionEasing?: 'elastic' | 'bounce'; // default: 'elastic' } ``` **Parameter Impact:** -- `distance`: Maximum translation distance (default 80px, smaller than TrackMouse) -- `axis`: Movement constraint (horizontal, vertical, or both) -- `transitionEasing`: Spring behavior - - `elastic`: Smooth spring with overshoot and settle - - `bounce`: Multiple bounces before settling -- `inverted`: Element bounces away from mouse instead of towards - -## Minimal Examples +- `distance`: Maximum translation distance (smaller default than TrackMouse) + - Default 80px is intentionally smaller—bouncy motion with large distances can be overwhelming + - Keep values moderate (50-150px) for best results +- `axis`: Constrain movement direction + - `both` (default): Bounces in 2D + - `horizontal`/`vertical`: Constrains to one axis +- `inverted`: Reverse movement direction + - Creates "repelled" bouncy effect +- `transitionDuration`: Affects bounce timing +- `transitionEasing`: Spring behavior type + - `elastic` (default): Smooth spring with overshoot and gentle settle + - `bounce`: Multiple distinct bounces before settling—more energetic + +## Best Practices + +- **Keep distances small**: Bouncy motion amplifies perceived distance—start with 50-100px +- **Match playful contexts**: BounceMouse screams "fun"—ensure it fits your brand +- **One bouncing element**: Multiple bouncing elements are visually overwhelming +- **Consider `elastic` vs `bounce`**: `elastic` is smoother; `bounce` is more cartoonish +- **Reduced motion**: Disable entirely—bouncy motion can cause discomfort + +## Examples ```typescript -// Basic +// Basic - bouncy cursor following { type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } -``` - -## Related Presets - -### Same Category (Mouse) - -- **TrackMouse** - Same tracking without bounce easing -- **ScaleMouse** - Scale-based mouse response -- **Tilt3DMouse** - 3D tilt mouse response - -### Parallel in Other Triggers - -- **BounceIn** (entrance) - Bouncy entrance animation -- **Bounce** (ongoing) - Continuous bounce animation - -### Alternatives -- **TrackMouse** - When smooth following preferred -- **Tilt3DMouse** - When 3D effect preferred -- **ScaleMouse** - When scale response preferred +// Smaller, more contained bounce +{ type: 'BounceMouse', distance: { value: 50, type: 'px' }, axis: 'both' } -## Decision Hints +// Horizontal only bounce +{ type: 'BounceMouse', distance: { value: 100, type: 'px' }, axis: 'horizontal' } -```yaml -choose_this_when: - - "playful mouse interaction" - - "game-like interface" - - "elastic/springy feel" - - "character/mascot following" - - "fun/energetic brand" +// More cartoonish bounce easing +{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both', transitionEasing: 'bounce' } -choose_alternative_when: - - smooth_following: TrackMouse - - 3d_effect: Tilt3DMouse - - scale_based: ScaleMouse - - professional_interface: TrackMouse (with easeOut) +// Inverted (bounces away from cursor) +{ type: 'BounceMouse', distance: { value: 60, type: 'px' }, axis: 'both', inverted: true } ``` diff --git a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md index 0f00b9c2..38a99a1c 100644 --- a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md @@ -1,99 +1,83 @@ --- name: Tilt3DMouse category: mouse -tags: [3d, tilt, mouse, perspective, interactive, hover, rotation] --- # Tilt3DMouse -## Synonyms - -3d tilt, mouse tilt, perspective tilt, interactive tilt, hover tilt, card tilt, gyroscope effect - ## Visual Description -Element tilts towards the mouse cursor, like holding a card and angling it. Moving mouse left tilts element left, moving up tilts it back. Creates an interactive 3D feel where elements respond to cursor position. +Element tilts in 3D space toward the mouse cursor, like holding a physical card and angling it to catch the light. Moving the mouse left makes the element tilt left; moving up makes it tilt back. The effect creates an interactive, premium feel where elements respond to cursor position. -## When to Use +**How it works**: The element's rotation is calculated based on the cursor's position relative to the element's center. The closer to an edge, the more pronounced the tilt. Moving the cursor away from the element returns it to flat. -- Interactive cards and product displays -- Hero sections with depth effect -- Portfolio thumbnails -- Game-like interfaces +**The visual effect**: The element feels tangible and responsive, like a physical object you can manipulate. It creates depth and interactivity, making the interface feel premium and engaging. Commonly used for product cards, images, and interactive showcases. -## When NOT to Use - -- Mobile devices (no mouse) -- Text-heavy content +**Inverted mode**: When inverted, the element tilts away from the cursor instead of toward it—creating a "repelled" rather than "attracted" feel. ## Parameters ```typescript interface Tilt3DMouse { power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - angle?: number; // min: 5, max: 85, step: 1, default: 50 (responsive) - perspective?: number; // min: 200, max: 1000, step: 50, default: 1000 (base) / 800 (impl) + angle?: number; // degrees, min: 5, max: 85, step: 1, default: 50 + perspective?: number; // px, min: 200, max: 1000, step: 50, default: 800 inverted?: boolean; // default: false - transitionDuration?: number; // min: 0, max: 5000, step: 20, default: 500 + transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' } ``` **Parameter Impact:** -- `power`: Preset combinations of angle + perspective + easing - - `soft`: 25° angle, 1000px perspective - subtle tilt - - `medium`: 50° angle, 500px perspective - noticeable tilt - - `hard`: 85° angle, 200px perspective - dramatic tilt +- `power`: Preset combinations for quick setup + - `soft`: 25° max angle, 1000px perspective—subtle, professional + - `medium` (default): 50° max angle, 500px perspective—balanced, noticeable + - `hard`: 85° max angle, 200px perspective—dramatic, attention-grabbing - `angle`: Maximum rotation degrees (5-85) -- `perspective`: 3D depth perception (lower = more dramatic) -- `inverted`: Reverses tilt direction (element tilts away from mouse) -- `transitionDuration`: Smoothing delay for tilt changes + - Lower values (5-25): Subtle tilt, professional feel + - Medium values (30-50): Noticeable, engaging + - High values (60-85): Dramatic, can feel exaggerated +- `perspective`: 3D depth perception (200-1000px) + - Lower values (200-400): Dramatic perspective, close-up feel + - Higher values (800-1000): Subtle perspective, more natural +- `inverted`: Reverses tilt direction + - `false` (default): Tilts toward cursor + - `true`: Tilts away from cursor +- `transitionDuration`: Smoothing delay for tilt changes (0-5000ms) + - Lower values: Snappy response + - Higher values: Smooth, laggy response - `transitionEasing`: Easing curve for transitions -## Minimal Examples +## Best Practices -```typescript -// Basic -{ type: 'Tilt3DMouse' } +- **Use on cards and images**: Tilt3DMouse is perfect for product cards, portfolio items, and interactive images +- **Keep it subtle in professional contexts**: Use `power: 'soft'` or low `angle` values for business sites +- **Consider hover area**: Works best when element has space around it for mouse movement +- **Add shadow for depth**: Combine with dynamic shadows that shift with tilt for extra realism +- **Desktop only**: Remember this doesn't work on touch devices—ensure content is accessible without it -// Inverted (tilts away from mouse) -{ type: 'Tilt3DMouse', inverted: true } -``` +## Examples -## Related Presets - -### Same Category (Mouse) - -- **Track3DMouse** - Translation + rotation, different effect -- **SwivelMouse** - Rotation following mouse angle - -### Parallel in Other Triggers +```typescript +// Basic - balanced tilt effect +{ type: 'Tilt3DMouse' } -- **TiltScroll** (scroll) - 3D tilt driven by scroll -- **ArcScroll** (scroll) - Arc rotation on scroll -- **TiltIn** (entrance) - One-time tilt entrance +// Subtle professional effect +{ type: 'Tilt3DMouse', power: 'soft' } -### Alternatives +// Dramatic interactive card +{ type: 'Tilt3DMouse', power: 'hard' } -- **TrackMouse** - When translation preferred over rotation -- **ScaleMouse** - When scale effect preferred -- **SwivelMouse** - When rotation around Z-axis preferred +// Custom subtle tilt +{ type: 'Tilt3DMouse', angle: 15, perspective: 1000 } -## Decision Hints +// Inverted (tilts away from cursor) +{ type: 'Tilt3DMouse', inverted: true } -```yaml -choose_this_when: - - "interactive 3D card effect" - - "product hover enhancement" - - "premium/gaming interface" - - "depth/perspective on hover" - - "gyroscope-like effect" +// Snappy response +{ type: 'Tilt3DMouse', transitionDuration: 100 } -choose_alternative_when: - - translation_preferred: TrackMouse - - scale_effect: ScaleMouse - - z_rotation: SwivelMouse - - scroll_driven: TiltScroll - - mobile_device: (use device orientation) +// Smooth, dreamy response +{ type: 'Tilt3DMouse', transitionDuration: 800, transitionEasing: 'easeOut' } ``` diff --git a/packages/motion-presets/rules/presets/mouse/track-mouse.md b/packages/motion-presets/rules/presets/mouse/track-mouse.md index 77fb8445..7672cfa1 100644 --- a/packages/motion-presets/rules/presets/mouse/track-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/track-mouse.md @@ -1,103 +1,87 @@ --- name: TrackMouse category: mouse -tags: [track, follow, mouse, movement, translate, interactive, cursor] --- # TrackMouse -## Synonyms - -mouse tracking, follow cursor, cursor follow, mouse movement, parallax mouse, floating follow - ## Visual Description -Element follows the mouse cursor, moving in the same direction. Like a floating object that drifts towards where you point. Can be limited to horizontal or vertical movement only. Creates an interactive, responsive feel. - -## When to Use +Element follows the mouse cursor, translating its position based on cursor location. Like a floating object that drifts toward where you point, the element moves in the direction of the cursor within defined bounds. -- Parallax-like mouse effects -- Floating elements that follow cursor -- Interactive hero sections -- Creating depth with layered elements +**How it works**: As the cursor moves across the viewport, the element shifts position proportionally. The `distance` parameter defines how far the element can move from its center position. Movement can be constrained to horizontal, vertical, or both axes. -## When NOT to Use +**The visual effect**: Creates a responsive, floating feel. Multiple elements with different distances create parallax-like depth. The effect feels interactive and playful, like objects following your gaze. -- Mobile devices (no mouse) -- Interactive/clickable elements +**Inverted mode**: When inverted, the element moves in the opposite direction—cursor goes right, element goes left. This can create interesting "repelling" effects. ## Parameters ```typescript interface TrackMouse { - distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // min: 5, max: 800, default: { value: 250, type: 'px' } + distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // default: { value: 250, type: 'px' } axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' power?: 'soft' | 'medium' | 'hard'; // default: 'medium' inverted?: boolean; // default: false - transitionDuration?: number; // min: 0, max: 5000, step: 20, default: 500 + transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' } ``` **Parameter Impact:** -- `distance`: Maximum translation distance from center - - Higher values = element moves further - - Different units for responsive behavior -- `axis`: Movement constraint - - `both`: Moves in 2D following cursor +- `distance`: Maximum translation distance from center position + - `value`: How far the element can move (5-800) + - `type`: Unit of measurement + - `px`: Fixed pixel distance + - `percentage`: Relative to element size + - `vh`/`vw`: Relative to viewport + - Larger values = more dramatic movement +- `axis`: Constrain movement direction + - `both` (default): Element moves in 2D, following cursor anywhere - `horizontal`: Only left/right movement - `vertical`: Only up/down movement -- `power`: Affects easing - - `soft`: Linear easing - - `medium`: `easeOut` - - `hard`: `hardBackOut` (slight overshoot) -- `inverted`: Element moves opposite to mouse direction - -## Minimal Examples +- `power`: Affects easing curve + - `soft`: Linear easing—direct, mechanical + - `medium` (default): `easeOut`—smooth, natural + - `hard`: `hardBackOut`—slight overshoot, bouncy +- `inverted`: Reverse movement direction + - `false`: Element follows cursor + - `true`: Element moves opposite to cursor +- `transitionDuration`: Smoothing delay +- `transitionEasing`: Easing curve for smooth transitions + +## Best Practices + +- **Layer multiple elements**: Apply different distances to create parallax depth (e.g., 50px, 150px, 300px) +- **Keep distances reasonable**: Very large distances can make elements move off-screen +- **Constrain axis when appropriate**: Horizontal-only is great for decorative elements in hero sections +- **Inverted creates depth**: Use inverted on "background" elements to create separation from "foreground" +- **Desktop only**: Always ensure content is usable without mouse tracking + +## Examples ```typescript // Basic - follows mouse in all directions { type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } -// Horizontal only +// Horizontal only (good for hero backgrounds) { type: 'TrackMouse', distance: { value: 100, type: 'px' }, axis: 'horizontal' } -``` - -## Related Presets - -### Same Category (Mouse) - -- **Tilt3DMouse** - 3D rotation instead of translation -- **Track3DMouse** - Combined translation + rotation -- **BounceMouse** - Tracking with elastic easing - -### Parallel in Other Triggers - -- **ParallaxScroll** (scroll) - Parallax on scroll instead of mouse -- **MoveScroll** (scroll) - Movement on scroll -- **GlideIn** (entrance) - Directional entrance animation - -### Alternatives -- **Tilt3DMouse** - When 3D rotation preferred -- **BounceMouse** - When bouncy/elastic feel wanted -- **ScaleMouse** - When scale effect preferred +// Subtle background layer +{ type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'both' } -## Decision Hints +// Dramatic foreground element +{ type: 'TrackMouse', distance: { value: 300, type: 'px' }, axis: 'both' } -```yaml -choose_this_when: - - "element follows cursor" - - "parallax mouse effect" - - "floating/hovering elements" - - "depth layers on mouse" - - "decorative cursor interaction" +// Inverted (moves opposite to cursor) +{ type: 'TrackMouse', distance: { value: 150, type: 'px' }, axis: 'both', inverted: true } -choose_alternative_when: - - 3d_tilt: Tilt3DMouse - - bouncy_elastic: BounceMouse - - scale_effect: ScaleMouse - - z_rotation: SwivelMouse - - scroll_based: ParallaxScroll +// Parallax depth layers (apply to different elements) +// Far background +{ type: 'TrackMouse', distance: { value: 30, type: 'px' }, axis: 'both' } +// Mid layer +{ type: 'TrackMouse', distance: { value: 80, type: 'px' }, axis: 'both' } +// Foreground +{ type: 'TrackMouse', distance: { value: 150, type: 'px' }, axis: 'both' } ``` diff --git a/packages/motion-presets/rules/presets/ongoing.md b/packages/motion-presets/rules/presets/ongoing.md new file mode 100644 index 00000000..d4e4895d --- /dev/null +++ b/packages/motion-presets/rules/presets/ongoing.md @@ -0,0 +1,175 @@ +--- +name: Ongoing Animations +category: ongoing +tags: [ongoing, continuous, loop, looping, repeating, infinite, persistent, ambient, status, indicator] +--- + +# Ongoing Animations + +## Description + +Ongoing animations run continuously in a loop, creating persistent motion on the page. Unlike entrance animations (one-shot) or scroll animations (scroll-driven), ongoing animations repeat indefinitely until stopped. They're used to draw attention, indicate status, or add ambient visual interest. + +Use ongoing animations sparingly—they constantly draw the eye and can be distracting or fatiguing if overused. They work best for single focal points like loading indicators, status badges, or attention-grabbing CTAs. + +## Synonyms + +continuous animation, looping animation, infinite animation, repeating animation, ambient motion, persistent animation, attention animation, status indicator, loading animation, idle animation, background motion + +## When to Use Ongoing Animations + +- **Loading/Processing indicators**: Spinners, progress indicators +- **Status indicators**: Live/active/online status, recording indicator +- **Attention-drawing elements**: Notification badges, important CTAs +- **Decorative ambient motion**: Background elements, illustrations +- **Waiting states**: While content loads or processes +- **Gamification elements**: Rewards, achievements, collectibles + +## When NOT to Use Ongoing Animations + +- **Multiple simultaneous animations** → visual chaos, distracting +- **Content that needs to be read** → motion interferes with reading +- **Professional/minimal interfaces** → may feel unprofessional +- **Mobile with battery concerns** → continuous animation drains battery +- **One-time reveals** → use Entrance animations +- **Scroll-driven effects** → use Scroll animations + +## Accessibility Considerations + +- **Respect `prefers-reduced-motion`**: Stop all ongoing animations or reduce to very subtle Pulse +- **Provide pause controls**: Users should be able to stop animations. WCAG 2.2.2 requires pause/stop for any motion lasting more than 5 seconds +- **Vestibular safety**: Spin, Bounce, Wiggle, and Swing can trigger motion sickness. Pulse and Flash (subtle) are safer +- **Avoid flashing**: Flash animation at high intensity or speed can trigger seizures. Never exceed 3 flashes per second +- **Attention interference**: Ongoing animations can distract users with ADHD or cognitive disabilities +- **Screen reader announcement**: Ensure status changes are announced, not just animated + +## Available Presets + +### Pulse + +**Description**: Gentle scale oscillation, heartbeat-like rhythm. Shrinks and expands continuously. Subtle, universal attention indicator. +**Tags**: `pulse`, `scale`, `heartbeat`, `throb`, `attention`, `subtle`, `status`, `breathing` +**Synonyms**: pulse effect, heartbeat, throb, breathing, scale pulse, attention pulse, pulsing + +### Bounce + +**Description**: Vertical bouncing motion like a ball on trampoline. Playful, energetic, attention-grabbing continuous motion. +**Tags**: `bounce`, `vertical`, `movement`, `playful`, `energetic`, `jump`, `hop`, `spring` +**Synonyms**: bouncing, jumping, hopping, vertical bounce, continuous bounce, bouncy animation + +### Spin + +**Description**: Continuous rotation around center. Like a wheel or loading spinner. Mechanical, precise circular motion. +**Tags**: `spin`, `rotate`, `loading`, `circular`, `wheel`, `continuous`, `mechanical` +**Synonyms**: spinning, rotating, rotation, circular motion, revolve, turn continuously + +### Breathe + +**Description**: Slow scale in/out like breathing rhythm. Calm, organic, meditative expansion and contraction. +**Tags**: `breathe`, `scale`, `slow`, `calm`, `organic`, `meditative`, `expansion`, `zen` +**Synonyms**: breathing animation, slow pulse, meditation, calm scale, organic rhythm + +### Flash + +**Description**: Opacity pulsing/blinking effect. Attention, warning, notification indicator through visibility changes. +**Tags**: `flash`, `blink`, `opacity`, `attention`, `warning`, `notification`, `visibility` +**Synonyms**: flashing, blinking, blink animation, attention flash, warning blink + +### Swing + +**Description**: Rotation oscillation like a pendulum. Back and forth pivoting motion, playful rhythmic movement. +**Tags**: `swing`, `pendulum`, `oscillation`, `rotation`, `pivot`, `rhythmic`, `back-forth` +**Synonyms**: swinging, pendulum motion, oscillating, pivot swing, back and forth + +### Wiggle + +**Description**: Horizontal shake/wiggle motion. Side-to-side movement for attention, playful "notice me" effect. +**Tags**: `wiggle`, `shake`, `horizontal`, `attention`, `playful`, `notice`, `side-to-side` +**Synonyms**: wiggling, shaking, horizontal shake, side wiggle, shake animation + +### Flip + +**Description**: Periodic 180° flips. Card-like rotation showing front/back, dramatic periodic turn. +**Tags**: `flip`, `rotation`, `180`, `card`, `periodic`, `turn`, `front-back` +**Synonyms**: flipping, card flip, periodic flip, turn animation, flip cycle + +### Fold + +**Description**: 3D folding motion. Paper-like folding and unfolding, creative dimensional movement. +**Tags**: `fold`, `3d`, `paper`, `dimensional`, `creative`, `unfold` +**Synonyms**: folding, paper fold, 3d fold, origami motion, fold animation + +### Jello + +**Description**: Wobbly elastic deformation. Jiggly, bouncy distortion like gelatin wobbling. +**Tags**: `jello`, `wobble`, `elastic`, `jiggly`, `bouncy`, `gelatin`, `deform` +**Synonyms**: jello wobble, jiggly, elastic wobble, bouncy deform, gelatin shake + +### Rubber + +**Description**: Elastic stretch effect. Springy stretching and snapping back, rubbery distortion. +**Tags**: `rubber`, `elastic`, `stretch`, `spring`, `snap`, `distortion` +**Synonyms**: rubber stretch, elastic animation, stretchy, springy, snap back + +### Poke + +**Description**: Quick scale bump like being tapped. Brief attention "boop" effect, momentary scale spike. +**Tags**: `poke`, `bump`, `tap`, `quick`, `attention`, `boop`, `spike` +**Synonyms**: poke effect, bump animation, tap, boop, attention tap, quick bump + +### Cross + +**Description**: X-pattern diagonal movement. Unique geometric motion crossing diagonally. +**Tags**: `cross`, `diagonal`, `x-pattern`, `geometric`, `unique`, `movement` +**Synonyms**: cross movement, diagonal cross, x-pattern, crossing animation + +### DVD + +**Description**: Corner-to-corner bounce (DVD screensaver). Nostalgic bouncing around container, retro effect. +**Tags**: `dvd`, `screensaver`, `corner`, `bounce`, `nostalgic`, `retro`, `container` +**Synonyms**: dvd bounce, screensaver, corner bounce, retro bounce, dvd logo + +## Decision Guide + +### By Motion Type + +- **Scale-based**: Pulse, Breathe, Poke, Rubber +- **Movement/Position**: Bounce, Wiggle, Cross, DVD +- **Rotation**: Spin, Swing, Flip, Fold +- **Opacity**: Flash +- **Deformation**: Jello, Rubber + +### By Tone + +- **Subtle/Professional**: Pulse (soft), Breathe, Flash (soft) +- **Playful/Energetic**: Bounce, Wiggle, Jello, DVD, Rubber +- **Mechanical/Technical**: Spin, Flip, Fold +- **Attention-grabbing**: Flash, Bounce, Pulse (hard), Poke + +### By Use Case + +- **Loading/Processing**: Spin, Pulse +- **Status indicator (live/active)**: Pulse, Breathe +- **Notification badge**: Bounce, Pulse, Poke, Flash +- **CTA emphasis**: Pulse, Bounce +- **Character/Mascot**: Bounce, Wiggle, Jello +- **Decorative background**: Spin (slow), Breathe, Float + +### Reduced Motion Alternatives + +| Original | Reduced Motion Fallback | +|----------|------------------------| +| Spin, Swing, Flip | Stop animation or very slow Pulse | +| Bounce, Wiggle, Jello | Pulse (soft) or stop | +| Flash | Reduce frequency, ensure <3 flashes/second | +| DVD, Cross | Stop animation | + +### Parallels in Other Categories + +| Ongoing | Entrance | Scroll | Mouse | +|---------|----------|--------|-------| +| Pulse | DropIn | GrowScroll | ScaleMouse | +| Bounce | BounceIn | - | BounceMouse | +| Spin | SpinIn | SpinScroll | SpinMouse | +| Flip | FlipIn | FlipScroll | - | +| Flash | FadeIn | FadeScroll | - | diff --git a/packages/motion-presets/rules/presets/ongoing/bounce.md b/packages/motion-presets/rules/presets/ongoing/bounce.md index 74c8a6b3..a25b95f6 100644 --- a/packages/motion-presets/rules/presets/ongoing/bounce.md +++ b/packages/motion-presets/rules/presets/ongoing/bounce.md @@ -1,92 +1,71 @@ --- name: Bounce category: ongoing -tags: [bounce, vertical, movement, playful, continuous, attention, jump] --- # Bounce -## Synonyms - -bouncing, jumping, hopping, vertical bounce, continuous bounce, bouncy animation - ## Visual Description -Element continuously bounces up and down like a ball on a trampoline. Bounces high, then smaller and smaller before the cycle repeats. Creates playful, energetic, attention-grabbing continuous motion. - -## When to Use +Element bounces up and down continuously in a playful, physics-inspired motion. Like a ball on a trampoline, the element jumps upward, reaches a peak, falls back down, and bounces again with decreasing height until the cycle resets. -- Playful/fun interface elements -- Gamification indicators -- "Jump here" attention indicators -- Child-friendly interfaces +**The motion**: Starting from its rest position, the element moves upward, reaches its peak, falls back down past the rest position (like a ball compressing on impact), then bounces up again with less height. This continues until bounces become minimal, then the cycle restarts. -## When NOT to Use +**The visual effect**: Energetic, playful, and attention-grabbing. The bouncing feels alive, like something excited or trying to get your attention. It's inherently fun and casual—not suitable for serious or professional contexts. -- Professional/corporate interfaces -- Multiple simultaneous elements +Bounce is one of the more intense ongoing animations. Use it when you want to add playful energy and don't mind the element constantly demanding attention. ## Parameters ```typescript interface Bounce { power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - intensity?: number; // min: 0, max: 1, step: 0.1, default: 0.3 (responsive) - duration?: number; // min: 100, max: 4000, step: 100, default: 1200 - delay?: number; // min: 0, max: 8000, step: 100, default: 1000 + intensity?: number; // 0-1, min: 0, max: 1, step: 0.1, default: 0.3 + duration?: number; // ms, min: 100, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 1000 } ``` **Parameter Impact:** - `power`: Preset bounce height multipliers - - `soft`: Factor 1 - subtle bounces (~49px max height) - - `medium`: Factor 2 - noticeable bounces (~98px) - - `hard`: Factor 3 - dramatic bounces (~147px) -- `intensity`: Fine-grained control (0-1), maps to factor 1-3 -- `delay`: Pause before bounce cycle starts + - `soft` (default): ~49px maximum height, contained bounces—noticeable but not wild + - `medium`: ~98px maximum height, clearly bouncy—playful and energetic + - `hard`: ~147px maximum height, dramatic bounces—very attention-grabbing, potentially annoying +- `intensity`: Fine-grained control (0-1) mapping to factor 1-3 + - 0.3 (default) = soft + - 0.5 = medium + - 1.0 = hard - `duration`: Full bounce cycle time + - **800-1000ms**: Quick, energetic bouncing + - **1200ms (default)**: Balanced timing + - **1500ms+**: Slower, more deliberate bounces +- `delay`: Initial wait before bouncing starts + - Gives users a moment before the motion begins -## Minimal Examples - -```typescript -// Basic -{ type: 'Bounce' } -``` - -## Related Presets - -### Same Category (Ongoing) +## Best Practices -- **Pulse** - Scale-based instead of movement -- **Swing** - Rotation-based oscillation -- **Wiggle** - Horizontal movement oscillation +- **Use sparingly**: Bounce is inherently distracting—reserve for elements that truly need attention +- **One bouncing element**: Multiple bouncing elements create visual chaos +- **Match the brand**: Bounce is playful/casual; ensure it fits the overall tone +- **Consider the context**: Bouncing indefinitely can become annoying—consider triggering only when relevant +- **Reduced motion**: Always provide alternative (stop animation entirely or switch to subtle Pulse) -### Parallel in Other Triggers +## Examples -- **BounceIn** (entrance) - One-time bounce entrance -- **BounceMouse** (mouse) - Bouncy response to mouse - -### Alternatives +```typescript +// Basic - subtle continuous bounce +{ type: 'Bounce' } -- **Pulse** - When scale-based attention preferred -- **Swing** - When rotation preferred -- **Wiggle** - When horizontal movement preferred +// Playful mascot/character +{ type: 'Bounce', power: 'medium', duration: 1000 } -## Decision Hints +// Attention indicator (jump here!) +{ type: 'Bounce', power: 'soft', duration: 1500 } -```yaml -choose_this_when: - - "playful/fun interface" - - "gamification element" - - "energetic attention" - - "character/mascot animation" - - "vertical movement needed" +// Game reward/achievement +{ type: 'Bounce', power: 'hard', duration: 800 } -choose_alternative_when: - - scale_based: Pulse - - rotation_based: Swing, Spin - - horizontal: Wiggle - - subtle_attention: Pulse (soft) - - one_time: BounceIn +// Gentle notification (less intrusive) +{ type: 'Bounce', power: 'soft', intensity: 0.2, duration: 1400 } ``` diff --git a/packages/motion-presets/rules/presets/ongoing/pulse.md b/packages/motion-presets/rules/presets/ongoing/pulse.md index e7b6c876..27bbea87 100644 --- a/packages/motion-presets/rules/presets/ongoing/pulse.md +++ b/packages/motion-presets/rules/presets/ongoing/pulse.md @@ -1,91 +1,71 @@ --- name: Pulse category: ongoing -tags: [pulse, scale, attention, heartbeat, throb, continuous, subtle] --- # Pulse -## Synonyms - -pulse effect, heartbeat, throb, breathing, scale pulse, attention pulse, pulsing - ## Visual Description -Element gently shrinks and expands in a rhythmic, heartbeat-like pattern. Like something breathing or pulsing with life. Creates subtle, continuous attention without being distracting. - -## When to Use +Element gently expands and contracts in a continuous rhythmic pattern, like a heartbeat or something softly breathing. The scale oscillates—growing slightly larger, then shrinking back to normal size—in an endless loop. -- Drawing attention to important elements -- Live/active status indicators -- Notification badges -- Waiting/processing states +**The motion**: The element starts at its normal size, grows slightly (maybe 5-15% larger), then shrinks back. This cycle repeats continuously. The timing feels organic, like a pulse or breath, not mechanical. -## When NOT to Use +**The visual effect**: Creates a sense of life and activity without being aggressive or distracting. The pulsing draws attention subtly, suggesting "hey, look here" without shouting. It's the gentlest way to indicate something is active, alive, or important. -- Multiple elements simultaneously -- Professional/minimal interfaces +Pulse is the most universally safe ongoing animation—it's subtle enough for professional contexts and doesn't trigger motion sensitivity as strongly as movement-based animations. ## Parameters ```typescript interface Pulse { power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - intensity?: number; // min: 0, max: 1, step: 0.1, default: 0 (responsive) - duration?: number; // min: 100, max: 4000, step: 100, default: 1300 - delay?: number; // min: 0, max: 8000, step: 100, default: 1000 + intensity?: number; // 0-1, min: 0, max: 1, step: 0.1, default: 0 + duration?: number; // ms, min: 100, max: 4000, step: 100, default: 1300 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 1000 } ``` **Parameter Impact:** -- `power`: Preset intensity levels - - `soft`: Offset 0 - very subtle pulse - - `medium`: Offset 0.06 - noticeable pulse - - `hard`: Offset 0.12 - pronounced pulse -- `intensity`: Fine-grained control (0-1), overrides power -- `delay`: Time before animation starts (useful for staggering) -- `duration`: Full cycle time (includes delay in calculation) - -## Minimal Examples +- `power`: Preset intensity levels for the pulse magnitude + - `soft` (default): Very subtle pulse, barely noticeable—professional, gentle + - `medium`: Noticeable pulse, clearly alive—good for status indicators + - `hard`: Pronounced pulse, attention-demanding—use for important alerts +- `intensity`: Fine-grained control over pulse magnitude (0-1) + - Overrides `power` if specified + - 0 = no pulse, 1 = maximum pulse + - Use for precise control when presets don't fit +- `duration`: Full pulse cycle time (expand + contract) + - **800-1000ms**: Quick, energetic pulse + - **1300ms (default)**: Balanced, natural feeling + - **2000ms+**: Slow, breathing-like rhythm +- `delay`: Initial wait before pulsing begins + - Useful for staggering multiple pulsing elements + +## Best Practices + +- **One pulsing element at a time**: Multiple simultaneous pulses are visually chaotic +- **Use for status, not content**: Pulse is for "this is active/important," not for decorating content +- **Prefer `soft` power**: Start subtle; increase only if attention isn't captured +- **Combine with color/icon**: Pulse alone may not convey meaning—pair with visual indicators +- **Safe for reduced motion**: Pulse (soft) is often acceptable even with reduced motion preference, but offer disable option + +## Examples ```typescript -// Basic +// Basic - subtle pulse indicating activity { type: 'Pulse' } -``` - -## Related Presets - -### Same Category (Ongoing) - -- **Breathe** - Scale-based but different timing pattern -- **Flash** - Opacity-based attention effect - -### Parallel in Other Triggers - -- **GrowScroll** (scroll) - Scale change on scroll -- **DropIn** (entrance) - Scale-based entrance - -### Alternatives -- **Flash** - When opacity-based attention preferred -- **Bounce** - When vertical movement preferred -- **Breathe** - When different rhythm needed +// Live status indicator (streaming, recording) +{ type: 'Pulse', power: 'medium', duration: 1000 } -## Decision Hints +// Gentle notification badge +{ type: 'Pulse', power: 'soft', duration: 1500 } -```yaml -choose_this_when: - - "subtle continuous attention" - - "heartbeat/living effect" - - "status indicator" - - "notification badge" - - "gentle CTA emphasis" +// Attention-demanding alert +{ type: 'Pulse', power: 'hard', duration: 800 } -choose_alternative_when: - - opacity_based: Flash - - vertical_movement: Bounce - - rotation: Spin - - different_rhythm: Breathe - - one_time_attention: BounceIn, PunchIn +// Slow, calming breathing effect +{ type: 'Pulse', power: 'soft', duration: 2500 } ``` diff --git a/packages/motion-presets/rules/presets/ongoing/spin.md b/packages/motion-presets/rules/presets/ongoing/spin.md index 60432889..b9e7f7a8 100644 --- a/packages/motion-presets/rules/presets/ongoing/spin.md +++ b/packages/motion-presets/rules/presets/ongoing/spin.md @@ -1,97 +1,73 @@ --- name: Spin category: ongoing -tags: [spin, rotation, continuous, loading, circular, rotate] --- # Spin -## Synonyms - -spinning, rotating, rotation, circular motion, revolve, turn continuously - ## Visual Description -Element continuously rotates around its center, like a wheel or loading spinner. Can spin clockwise or counter-clockwise at constant speed or with acceleration/deceleration. Creates smooth, continuous circular motion. +Element rotates continuously around its center point, like a wheel, gear, or loading spinner. The rotation can be clockwise or counter-clockwise, at a constant speed or with easing variations. -## When to Use +**The motion**: The element pivots around its center, completing full 360° rotations indefinitely. By default, the rotation is smooth and constant (linear easing), creating a mechanical, precise feel. With power variations, the rotation can accelerate/decelerate for a more organic feel. -- Loading indicators -- Processing/waiting states -- Refresh icons during action -- Decorative spinning elements +**The visual effect**: Mechanical, precise, often associated with loading or processing states. Spin is universally understood as "something is happening" or "please wait." It can also be decorative for elements like gears, wheels, or abstract shapes. -## When NOT to Use - -- Text elements (unreadable) -- Multiple simultaneous spins +Spin is ideal for loading indicators and decorative rotating elements, but it can be a strong vestibular trigger for motion-sensitive users. ## Parameters ```typescript interface Spin { - direction: 'clockwise' | 'counter-clockwise'; // EffectSpinDirections, default: 'clockwise' + direction: 'clockwise' | 'counter-clockwise'; // default: 'clockwise' power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - duration?: number; // min: 100, max: 50000, step: 100, default: 7000 - delay?: number; // min: 0, max: 8000, step: 100, default: 0 - easing?: Easing; // default: 'linear' (responsive) + duration?: number; // ms, min: 100, max: 50000, step: 100, default: 7000 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` **Parameter Impact:** - `direction`: Rotation direction - - `clockwise`: Rotates right (default, natural feeling) - - `counter-clockwise`: Rotates left -- `power`: Controls easing curve - - `soft`: Linear - constant speed, mechanical feel - - `medium`: `quintInOut` - accelerates then decelerates - - `hard`: `backOut` - slight overshoot, more dynamic -- `duration`: One full rotation time (default 7000ms = 7 seconds, slow) - -## Minimal Examples + - `clockwise` (default): Rotates right, natural/expected direction for most users + - `counter-clockwise`: Rotates left, can feel like "rewinding" or unconventional +- `power`: Controls the easing curve of rotation + - `soft` (default): Linear, constant speed—mechanical, precise + - `medium`: Eased rotation (accelerate/decelerate)—more organic feel + - `hard`: Strong easing with slight overshoot—dynamic, bouncy +- `duration`: Time for one complete rotation + - **1000-2000ms**: Fast spin, energetic + - **3000-5000ms**: Medium speed, typical for loaders + - **7000ms (default)**: Slow, deliberate rotation + - **10000ms+**: Very slow, decorative/ambient +- `delay`: Wait before spinning starts + +## Best Practices + +- **Default duration is slow**: 7 seconds per rotation is intentionally calm. For loaders, consider 1000-2000ms +- **Use for loading states**: Spin is the universal "loading" indicator +- **Don't spin text**: Rotating text is unreadable and disorienting +- **Consider direction**: Clockwise feels natural; counter-clockwise may feel "wrong" to some users +- **Reduced motion**: Always provide static fallback—spinning is a strong vestibular trigger + +## Examples ```typescript -// Basic - clockwise spin +// Basic - slow clockwise spin { type: 'Spin', direction: 'clockwise' } -// Counter-clockwise -{ type: 'Spin', direction: 'counter-clockwise' } -``` - -## Related Presets +// Loading spinner (faster) +{ type: 'Spin', direction: 'clockwise', duration: 1500 } -### Same Category (Ongoing) - -- **Swing** - Oscillating rotation (back and forth) -- **Flip** - 180° flips, not continuous - -### Parallel in Other Triggers - -- **SpinIn** (entrance) - Spin into view (one-time) -- **SpinScroll** (scroll) - Rotation driven by scroll -- **SpinMouse** (mouse) - Rotation following mouse - -### Alternatives - -- **Swing** - When oscillation preferred over full rotation -- **Pulse** - When scale-based attention preferred -- **Flip** - When flip effect preferred +// Counter-clockwise (for variety or specific meaning) +{ type: 'Spin', direction: 'counter-clockwise' } -## Decision Hints +// Fast energetic spin +{ type: 'Spin', direction: 'clockwise', duration: 800 } -```yaml -choose_this_when: - - "loading/processing indicator" - - "refresh icon animation" - - "decorative rotation" - - "mechanical/gear effect" - - "continuous circular motion" +// Slow decorative rotation (gear, wheel) +{ type: 'Spin', direction: 'clockwise', duration: 15000 } -choose_alternative_when: - - oscillation_needed: Swing - - scale_based: Pulse - - entrance_spin: SpinIn - - scroll_driven: SpinScroll - - mouse_driven: SpinMouse +// Dynamic spin with easing +{ type: 'Spin', direction: 'clockwise', power: 'medium', duration: 2000 } ``` diff --git a/packages/motion-presets/rules/presets/scroll.md b/packages/motion-presets/rules/presets/scroll.md new file mode 100644 index 00000000..d1efafbf --- /dev/null +++ b/packages/motion-presets/rules/presets/scroll.md @@ -0,0 +1,214 @@ +--- +name: Scroll Animations +category: scroll +tags: [scroll, parallax, scroll-driven, viewport, scroll-reveal, on-scroll, scroll-triggered, storytelling, progressive] +--- + +# Scroll Animations + +## Description + +Scroll animations tie element transformations to the user's scroll position. Unlike entrance animations that play once, scroll animations continuously respond to scroll progress—elements can animate in as they enter the viewport, animate out as they leave, or transform throughout the entire scroll range. + +Scroll animations create immersive, storytelling experiences where the user's scrolling becomes an active part of the interaction. They're powerful for landing pages, portfolios, and narrative-driven designs. However, they require careful consideration for performance and accessibility. + +## Synonyms + +scroll-driven animation, scroll-triggered effect, parallax effect, scroll reveal, scroll fade, on-scroll animation, viewport animation, scroll-linked animation, scroll storytelling, progressive reveal, scroll-based transition + +## When to Use Scroll Animations + +- **Progressive content reveals**: Elements fading/sliding in as user scrolls to them +- **Parallax depth effects**: Layered elements moving at different rates +- **Storytelling experiences**: Narrative tied to scroll progress +- **Section transitions**: Effects as user scrolls between sections +- **Emphasis on scroll progress**: Progress indicators, timeline-like reveals +- **De-emphasizing passed content**: Fading out content as user scrolls past + +## When NOT to Use Scroll Animations + +- **One-time entrance effects** → use Entrance animations (more performant) +- **Continuous/looping animations** → use Ongoing animations +- **Mouse-reactive elements** → use Mouse animations +- **Background media** → use Background Scroll animations +- **Mobile-first designs** → scroll animations can be janky on mobile; test carefully +- **Content that must remain readable** → avoid on text-heavy sections + +## Accessibility Considerations + +- **Respect `prefers-reduced-motion`**: Disable scroll animations entirely or use subtle FadeScroll only +- **Vestibular safety**: ParallaxScroll, ArcScroll, FlipScroll, SpinScroll, and Spin3dScroll can trigger motion sickness. Provide alternatives or disable for sensitive users +- **Performance impact**: Scroll animations run continuously; optimize for 60fps. Janky animations are worse than no animations +- **Content accessibility**: Ensure all content is readable without animations. Don't hide critical information behind scroll-triggered reveals +- **Keyboard navigation**: Users navigating with keyboard may not trigger scroll animations in expected ways +- **Duration of scroll range**: Don't make users scroll excessively to reveal content + +## Available Presets + +### ParallaxScroll + +**Description**: Element moves slower/faster than scroll, creating depth illusion. Like looking through a window where distant objects move slower. +**Tags**: `parallax`, `depth`, `layered`, `continuous`, `movement`, `distance`, `speed` +**Synonyms**: parallax effect, scroll parallax, depth scroll, layered scroll, differential scroll, scroll movement + +### FadeScroll + +**Description**: Opacity transition tied to scroll position. Fade in on enter, fade out on exit. Smooth, cinematic content reveals. +**Tags**: `fade`, `opacity`, `reveal`, `in`, `out`, `transition`, `subtle` +**Synonyms**: scroll fade, fade on scroll, opacity scroll, scroll reveal, scroll disappear + +### ArcScroll + +**Description**: 3D tilt/rotation as user scrolls. Like a card tilting towards or away. Dramatic, cinematic depth effect. +**Tags**: `3d`, `arc`, `rotation`, `perspective`, `tilt`, `cinematic`, `dramatic` +**Synonyms**: scroll arc, 3d scroll, tilt scroll, rotation scroll, perspective scroll + +### BlurScroll + +**Description**: Blur/unblur effect controlled by scroll position. Creates focus/defocus transitions tied to scroll. +**Tags**: `blur`, `focus`, `defocus`, `soft`, `transition`, `depth` +**Synonyms**: scroll blur, blur on scroll, focus scroll, defocus scroll, blur transition + +### FlipScroll + +**Description**: Full 3D card flip driven by scroll. Dramatic rotation revealing content as user scrolls. +**Tags**: `flip`, `3d`, `rotation`, `card`, `dramatic`, `turn`, `reveal` +**Synonyms**: scroll flip, 3d flip scroll, card flip scroll, flip on scroll + +### GrowScroll + +**Description**: Scale up as element enters viewport. Element grows larger tied to scroll progress. +**Tags**: `grow`, `scale`, `zoom`, `expand`, `size`, `enlarge`, `in` +**Synonyms**: scroll grow, scale scroll, zoom scroll, grow on scroll, expand scroll + +### ShrinkScroll + +**Description**: Scale down as element exits viewport. Element shrinks tied to scroll progress. +**Tags**: `shrink`, `scale`, `reduce`, `minimize`, `size`, `out` +**Synonyms**: scroll shrink, scale down scroll, shrink on scroll, minimize scroll + +### MoveScroll + +**Description**: General translation movement on scroll. Move element in any direction tied to scroll position. +**Tags**: `move`, `translate`, `position`, `movement`, `direction`, `shift` +**Synonyms**: scroll move, translate scroll, movement scroll, position scroll + +### PanScroll + +**Description**: Horizontal or vertical panning effect. Element slides across tied to scroll. +**Tags**: `pan`, `horizontal`, `vertical`, `slide`, `traverse`, `sweep` +**Synonyms**: scroll pan, pan on scroll, horizontal scroll, sliding scroll + +### RevealScroll + +**Description**: Clip-based directional reveal on scroll. Content unveils progressively as user scrolls. +**Tags**: `reveal`, `clip`, `mask`, `directional`, `unveil`, `progressive`, `wipe` +**Synonyms**: scroll reveal, clip scroll, wipe scroll, unveil scroll, mask reveal scroll + +### ShapeScroll + +**Description**: Shape mask reveal controlled by scroll. Geometric shapes expanding/contracting on scroll. +**Tags**: `shape`, `mask`, `geometric`, `circle`, `expand`, `contract` +**Synonyms**: shape scroll, mask scroll, geometric reveal scroll, shape reveal + +### ShuttersScroll + +**Description**: Venetian blind strips revealing on scroll. Segmented progressive reveal tied to scroll. +**Tags**: `shutters`, `blinds`, `strips`, `segmented`, `progressive`, `venetian` +**Synonyms**: shutters scroll, blind scroll, strip reveal scroll, venetian scroll + +### SkewPanScroll + +**Description**: Panning with skew distortion effect. Movement plus angular distortion on scroll. +**Tags**: `skew`, `pan`, `distortion`, `angle`, `movement`, `warp` +**Synonyms**: skew scroll, skew pan, distortion scroll, angled pan scroll + +### SlideScroll + +**Description**: Slide movement tied to scroll position. Directional sliding as user scrolls. +**Tags**: `slide`, `move`, `directional`, `translate`, `shift` +**Synonyms**: scroll slide, slide on scroll, directional slide scroll + +### Spin3dScroll + +**Description**: 3D rotation around axis on scroll. Element rotates in 3D space as user scrolls. +**Tags**: `spin`, `3d`, `rotation`, `axis`, `revolve`, `orbit` +**Synonyms**: 3d spin scroll, rotation scroll, spin on scroll, 3d rotate scroll + +### SpinScroll + +**Description**: 2D rotation driven by scroll. Element spins flat as user scrolls. +**Tags**: `spin`, `rotate`, `2d`, `turn`, `circular` +**Synonyms**: scroll spin, rotate scroll, 2d spin scroll, turning scroll + +### StretchScroll + +**Description**: Stretch/squeeze deformation on scroll. Element distorts proportionally tied to scroll. +**Tags**: `stretch`, `squeeze`, `deform`, `distort`, `elastic`, `proportion` +**Synonyms**: stretch scroll, squeeze scroll, deform scroll, elastic scroll + +### TiltScroll + +**Description**: 3D tilt effect as user scrolls. Subtle perspective shift tied to scroll position. +**Tags**: `tilt`, `3d`, `perspective`, `angle`, `subtle`, `depth` +**Synonyms**: scroll tilt, 3d tilt scroll, perspective scroll, angle scroll + +### TurnScroll + +**Description**: Corner-pivot 3D rotation on scroll. Complex rotation with pivot point on scroll. +**Tags**: `turn`, `3d`, `corner`, `pivot`, `rotation`, `complex` +**Synonyms**: turn scroll, corner turn scroll, pivot scroll, 3d turn scroll + +## Decision Guide + +### By Effect Type + +- **Opacity**: FadeScroll, BlurScroll +- **Movement/Position**: ParallaxScroll, MoveScroll, PanScroll, SlideScroll +- **Scale**: GrowScroll, ShrinkScroll, StretchScroll +- **3D Rotation**: ArcScroll, FlipScroll, TiltScroll, TurnScroll, Spin3dScroll +- **2D Rotation**: SpinScroll +- **Reveal/Mask**: RevealScroll, ShapeScroll, ShuttersScroll + +### By Use Case + +- **Depth/Layering effects**: ParallaxScroll, MoveScroll (with different speeds) +- **Content reveal**: FadeScroll (in), RevealScroll, GrowScroll +- **Dramatic/Cinematic sections**: ArcScroll, FlipScroll, TiltScroll +- **Storytelling/Timeline**: Multiple presets with coordinated ranges +- **De-emphasize passed content**: FadeScroll (out), ShrinkScroll, BlurScroll (out) +- **Hero sections**: ArcScroll, TiltScroll, GrowScroll + +### Range Modes + +Most scroll presets support range modes that control when the animation occurs: + +- **`in`**: Animates as element enters viewport (0% → 50% visibility) +- **`out`**: Animates as element exits viewport (50% → 100% visibility) +- **`continuous`**: Animates throughout entire scroll range (0% → 100%) + +Custom `start` and `end` values allow fine-tuning the scroll range. + +### Reduced Motion Alternatives + +| Original | Reduced Motion Fallback | +|----------|------------------------| +| ParallaxScroll | Disable (static position) | +| ArcScroll, FlipScroll, Spin3dScroll | FadeScroll or disable | +| SpinScroll | Disable | +| TiltScroll, TurnScroll | FadeScroll | +| GrowScroll, ShrinkScroll | FadeScroll | + +### Parallels in Other Categories + +| Scroll | Entrance | Ongoing | Background | +|--------|----------|---------|------------| +| FadeScroll | FadeIn | - | BgFade | +| ArcScroll | ArcIn | - | - | +| ParallaxScroll | - | - | BgParallax | +| TiltScroll | TiltIn | - | - | +| FlipScroll | FlipIn | Flip | - | +| GrowScroll | GrowIn | - | BgZoom | +| SpinScroll | SpinIn | Spin | BgRotate | +| RevealScroll | RevealIn | - | BgReveal | +| BlurScroll | BlurIn | - | - | diff --git a/packages/motion-presets/rules/presets/scroll/arc-scroll.md b/packages/motion-presets/rules/presets/scroll/arc-scroll.md index 79ce694e..d3fe74d2 100644 --- a/packages/motion-presets/rules/presets/scroll/arc-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/arc-scroll.md @@ -1,96 +1,73 @@ --- name: ArcScroll category: scroll -tags: [3d, arc, scroll, rotation, perspective, tilt, depth] --- # ArcScroll -## Synonyms - -scroll arc, 3d scroll, tilt scroll, rotation scroll, perspective scroll, scroll rotation - ## Visual Description -Element tilts and rotates in 3D as you scroll, like a card flipping towards or away from you. Creates a dramatic, cinematic reveal with depth. The element appears to exist in 3D space, rotating on an invisible axis as scroll progresses. +Element tilts and rotates in 3D space as the user scrolls, creating a dramatic cinematic effect similar to ArcIn but driven by scroll position instead of time. The element appears to exist in 3D space, rotating on an axis as scroll progresses. -## When to Use +**How it looks**: Imagine a trading card slowly tilting as you scroll—it starts tilted away from you and gradually rotates flat, or vice versa. The effect creates depth and dimension, making the element feel like it's pivoting in real space. -- Dramatic scroll-based reveals -- Portfolio or showcase pages -- Hero sections with 3D depth +**`direction: 'vertical'`**: Element rotates on the X-axis, tilting forward/backward like a laptop screen opening or closing. -## When NOT to Use +**`direction: 'horizontal'`**: Element rotates on the Y-axis, tilting left/right like a door swinging open. -- Multiple simultaneous elements -- Text-heavy content -- Mobile with performance concerns +The rotation is tied directly to scroll position, creating a satisfying connection between user input and visual transformation. ## Parameters ```typescript interface ArcScroll { - direction: 'horizontal' | 'vertical'; // EffectTwoAxes, default: 'vertical' - range?: 'in' | 'out' | 'continuous'; // default: 'continuous' (wix) or 'in'/'out' (responsive) - // Scroll range params - start?: number; // varies by range - end?: number; // varies by range + direction: 'horizontal' | 'vertical'; // default: 'vertical' + range?: 'in' | 'out' | 'continuous'; // default varies + start?: number; // %, scroll position start + end?: number; // %, scroll position end } ``` **Parameter Impact:** -- `direction`: Rotation axis - - `vertical`: Rotates on X-axis (tilts forward/backward) - - `horizontal`: Rotates on Y-axis (tilts left/right) -- `range`: When rotation occurs - - `in`: Rotates from tilted to flat as enters viewport - - `out`: Rotates from flat to tilted as exits viewport - - `continuous`: Full rotation throughout scroll - -## Minimal Examples +- `direction`: Determines the rotation axis + - `vertical`: Rotates on X-axis—element tilts forward/backward + - At start: tilted back (top edge away from viewer) + - At end: flat, facing viewer + - Feels like a screen or lid opening toward you + - `horizontal`: Rotates on Y-axis—element tilts left/right + - At start: tilted to one side + - At end: flat, facing viewer + - Feels like a door or panel swinging open +- `range`: When the rotation occurs + - `in`: Rotates from tilted → flat as element enters viewport + - `out`: Rotates from flat → tilted as element exits viewport + - `continuous`: Full rotation range throughout scroll visibility +- `start`/`end`: Fine-tune when rotation begins and completes (0-100) + +## Best Practices + +- **Use on single focal elements**: ArcScroll is dramatic; multiple simultaneous rotations are overwhelming +- **Test performance**: 3D transforms can be expensive; ensure smooth 60fps +- **Consider viewport position**: Element needs to be positioned where rotation is visible during scroll range +- **Pair with complementary content**: Works well with text that doesn't rotate alongside +- **Reduced motion**: Provide FadeScroll or static fallback—3D rotation is a vestibular trigger + +## Examples ```typescript -// Tilts left/right as you scroll -{ type: 'ArcScroll', direction: 'horizontal' } - -// Tilts forward/backward as you scroll +// Basic - tilts forward/backward as you scroll { type: 'ArcScroll', direction: 'vertical' } -``` - -## Related Presets -### Same Category (Scroll) - -- **TiltScroll** - Similar 3D tilt, different implementation -- **FlipScroll** - Full flip rotation on scroll -- **Spin3dScroll** - Continuous spin on scroll - -### Parallel in Other Triggers - -- **ArcIn** (entrance) - Time-based arc entrance -- **FlipIn** (entrance) - Time-based 3D flip - -### Alternatives - -- **TiltScroll** - Alternative 3D tilt approach -- **FadeScroll** - When subtle effect needed -- **ParallaxScroll** - When 2D depth preferred +// Tilts left/right as you scroll +{ type: 'ArcScroll', direction: 'horizontal' } -## Decision Hints +// Only rotate while entering viewport +{ type: 'ArcScroll', direction: 'vertical', range: 'in' } -```yaml -choose_this_when: - - "dramatic 3D scroll effect" - - "cinematic reveal" - - "portfolio/showcase" - - "single focal element" - - "creative/artistic design" +// Only rotate while exiting viewport +{ type: 'ArcScroll', direction: 'horizontal', range: 'out' } -choose_alternative_when: - - subtle_needed: FadeScroll, ParallaxScroll - - full_flip: FlipScroll - - continuous_spin: SpinScroll - - 2d_depth: ParallaxScroll - - time_based: ArcIn +// Custom scroll range (rotation completes earlier) +{ type: 'ArcScroll', direction: 'vertical', range: 'in', start: 0, end: 40 } ``` diff --git a/packages/motion-presets/rules/presets/scroll/fade-scroll.md b/packages/motion-presets/rules/presets/scroll/fade-scroll.md index ae15d1ae..25956828 100644 --- a/packages/motion-presets/rules/presets/scroll/fade-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/fade-scroll.md @@ -1,94 +1,74 @@ --- name: FadeScroll category: scroll -tags: [fade, opacity, scroll, reveal, in, out, transition] --- # FadeScroll -## Synonyms - -scroll fade, fade on scroll, opacity scroll, scroll reveal, scroll disappear, fade in scroll, fade out scroll - ## Visual Description -Element gradually appears or disappears as you scroll. In "in" mode, content fades from invisible to visible as it enters the viewport. In "out" mode, it fades away as you scroll past. Creates smooth, cinematic content reveals. +Element's opacity changes in response to scroll position, creating smooth fade-in or fade-out effects as the user scrolls. This is the scroll-driven equivalent of FadeIn—subtle, accessible, and universally applicable. -## When to Use +**`range: 'in'` mode**: Element starts invisible and gradually becomes visible as it enters the viewport. By the time it reaches the middle of the viewport, it's fully visible. Perfect for revealing content as users scroll to it. -- Content reveal as user scrolls -- Section transitions -- De-emphasizing passed content +**`range: 'out'` mode**: Element starts visible and gradually becomes invisible as it exits the viewport. Creates a graceful "dismissal" of content as users scroll past. Good for de-emphasizing passed content. -## When NOT to Use - -- Critical content that must always be visible -- Navigation or persistent UI elements +The transition is smooth and linear, tied directly to scroll position—not time-based. Scroll faster, and the fade happens faster; scroll slower, and it's more gradual. ## Parameters ```typescript interface FadeScroll { - range: 'in' | 'out'; // EffectRangeInOut, default: 'in' - opacity?: number; // min: 0, max: 1, step: 0.01, default: 0 - // Scroll range params - start?: number; // min: 0, max: 100, default: 0 (in) or 50 (out) - end?: number; // min: 0, max: 100, default: 50 (in) or 100 (out) + range: 'in' | 'out'; // default: 'in' + opacity?: number; // 0-1, min: 0, max: 1, step: 0.01, default: 0 + start?: number; // %, min: 0, max: 100, default: 0 (in) or 50 (out) + end?: number; // %, min: 0, max: 100, default: 50 (in) or 100 (out) } ``` **Parameter Impact:** -- `range`: Direction of the fade - - `in`: Fades from `opacity` to 1 as element enters viewport - - `out`: Fades from 1 to `opacity` as element leaves viewport -- `opacity`: Target opacity value (what it fades from/to) - - 0 (default): Fully transparent - - 0.5: Semi-transparent -- `start`/`end`: Scroll position range (0-100% of element visibility) +- `range`: Direction of the fade effect + - `in`: Fades from invisible → visible as element enters viewport. Element reaches full opacity by the `end` scroll position + - `out`: Fades from visible → invisible as element exits viewport. Element becomes fully transparent by the `end` scroll position +- `opacity`: The "other" opacity value (what it fades from/to) + - `0` (default): Element fades from/to completely invisible + - `0.3-0.5`: Element fades from/to semi-transparent (never fully disappears) + - `1`: No fade effect (element stays visible) +- `start`/`end`: Scroll position range as percentage of element visibility + - For `in`: Default 0-50 means fade completes when element reaches viewport center + - For `out`: Default 50-100 means fade starts from viewport center until element leaves + - Adjust for slower/faster fades: wider range = slower fade + +## Best Practices -## Minimal Examples +- **`range: 'in'` is most common**: Revealing content as users scroll to it is the primary use case +- **Don't fade critical content**: Important information should be visible without needing to scroll to it +- **Combine in + out**: Apply both modes for content that fades in and out as user scrolls past +- **Adjust start/end for timing**: Want fade to complete earlier? Use `end: 30`. Later? Use `end: 70` +- **Safe for reduced motion**: FadeScroll is subtle enough to keep even with `prefers-reduced-motion`, though disabling is also fine + +## Examples ```typescript -// Fade in as enters viewport +// Basic - fades in as enters viewport { type: 'FadeScroll', range: 'in' } -// Fade out as leaves viewport +// Fade out as exits viewport { type: 'FadeScroll', range: 'out' } -``` - -## Related Presets -### Same Category (Scroll) +// Slower fade in (completes later) +{ type: 'FadeScroll', range: 'in', start: 0, end: 70 } -- **BlurScroll** - Blur effect on scroll, can combine with fade -- **RevealScroll** - Clip-based reveal on scroll +// Quick fade in (completes earlier) +{ type: 'FadeScroll', range: 'in', start: 0, end: 25 } -### Parallel in Other Triggers +// Fade to semi-transparent (not fully invisible) +{ type: 'FadeScroll', range: 'out', opacity: 0.3 } -- **FadeIn** (entrance) - Time-based fade, not scroll-driven -- **BgFade** (background-scroll) - Fade specifically for backgrounds - -### Alternatives - -- **BlurScroll** - When blur effect is preferred over pure opacity -- **RevealScroll** - When directional reveal is needed -- **GrowScroll** - When scale change is preferred - -## Decision Hints - -```yaml -choose_this_when: - - "content reveal on scroll" - - "section transitions" - - "progressive disclosure" - - "de-emphasize passed content" - - "simple opacity transition" - -choose_alternative_when: - - blur_effect: BlurScroll - - directional_reveal: RevealScroll, SlideScroll - - scale_change: GrowScroll, ShrinkScroll - - background_specific: BgFade - - time_based: FadeIn +// Combined fade in and out (use two animations or trigger logic) +// As element enters: +{ type: 'FadeScroll', range: 'in' } +// As element exits: +{ type: 'FadeScroll', range: 'out' } ``` diff --git a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md index e5039621..9e72ece1 100644 --- a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md @@ -1,92 +1,74 @@ --- name: ParallaxScroll category: scroll -tags: [parallax, scroll, depth, layered, continuous, vertical, movement] --- # ParallaxScroll -## Synonyms - -parallax effect, scroll parallax, depth scroll, layered scroll, differential scroll, scroll movement - ## Visual Description -Element moves slower or faster than the page scroll, creating an illusion of depth. Like looking through a window where nearby objects move faster than distant ones. Different elements with different speeds create layered, dimensional feel. +Element moves at a different rate than the page scroll, creating an illusion of depth and dimension. When you scroll the page, this element moves slower (or faster, or even opposite) compared to the rest of the content, making it feel like it exists on a different layer—closer or further away. -## When to Use +**How it works**: As the user scrolls, the element's vertical position is modified based on the `speed` parameter. A speed of 0.5 means the element moves at half the scroll rate (appears further away). A negative speed means the element moves opposite to scroll direction. -- Landing pages with layered depth effect -- Hero sections with background/foreground separation -- Decorative elements that should feel "behind" or "in front" +**The visual effect**: Imagine looking through a car window—distant mountains move slowly while nearby trees zip past. ParallaxScroll recreates this depth perception. Faster-moving elements feel closer; slower elements feel further away. -## When NOT to Use - -- Text-heavy content (readability issues) -- Mobile with performance concerns +This is a continuous effect that runs throughout the entire time the element is in the viewport, creating an immersive, layered experience. ## Parameters ```typescript interface ParallaxScroll { - speed?: number; // min: -1, max: 1, step: 0.05, default: 0.5 + speed?: number; // ratio, min: -1, max: 1, step: 0.05, default: 0.5 range?: 'continuous'; // only continuous supported - // Scroll range params (from base) - start?: number; // min: 0, max: 0, default: 0 (screen enter) - end?: number; // min: 100, max: 100, default: 100 (screen leave) + start?: number; // %, min: 0, max: 0, default: 0 + end?: number; // %, min: 100, max: 100, default: 100 } ``` **Parameter Impact:** -- `speed`: Rate of movement relative to scroll - - Positive (0.1-1): Element moves same direction as scroll, but slower - - Negative (-1 to -0.1): Element moves opposite to scroll direction - - Higher absolute value = more pronounced effect - - 0.5 (default): Element moves at half scroll speed -- `range`: Only `continuous` - runs throughout entire scroll range - -## Minimal Examples +- `speed`: The core parameter—determines movement rate relative to scroll + - **Positive values (0.1 to 1)**: Element moves in same direction as scroll, but slower + - `0.1-0.3`: Subtle parallax, element feels slightly "behind" + - `0.4-0.6`: Noticeable depth effect (0.5 default is ideal) + - `0.7-0.9`: Strong parallax, element moves almost with scroll + - **Negative values (-1 to -0.1)**: Element moves opposite to scroll direction + - Creates unusual "floating against current" effect + - Use sparingly—can be disorienting + - **0**: No movement (element scrolls normally with page) +- `range`: Only `continuous` is supported—effect runs throughout viewport visibility +- `start`/`end`: Fixed at 0-100, covering full scroll range + +## Best Practices + +- **Layer multiple elements**: Create depth by applying different speeds to different elements (e.g., background: 0.2, midground: 0.5, foreground: 0.8) +- **Subtle is usually better**: Start with `speed: 0.3` and adjust—strong parallax can cause motion sickness +- **Test on mobile**: Parallax can be janky on mobile devices; consider disabling or reducing +- **Don't use on text**: Moving text while scrolling is hard to read +- **Combine with position**: Elements should be positioned appropriately to have room to move +- **Reduced motion**: Disable entirely for `prefers-reduced-motion` + +## Examples ```typescript -// Basic +// Basic - element moves at half scroll speed { type: 'ParallaxScroll' } -// Reverse parallax (moves opposite to scroll) -{ type: 'ParallaxScroll', speed: -0.3 } -``` - -## Related Presets +// Subtle background element (feels very far away) +{ type: 'ParallaxScroll', speed: 0.2 } -### Same Category (Scroll) +// Strong parallax (noticeable depth) +{ type: 'ParallaxScroll', speed: 0.7 } -- **MoveScroll** - General movement on scroll, more control -- **PanScroll** - Horizontal/vertical panning on scroll - -### Parallel in Other Triggers - -- **BgParallax** (background-scroll) - Parallax specifically for backgrounds - -### Alternatives - -- **FadeScroll** - When opacity change is preferred over movement -- **MoveScroll** - When more movement control needed -- **BgParallax** - When animating background media specifically - -## Decision Hints - -```yaml -choose_this_when: - - "depth/layered effect needed" - - "elements at different scroll rates" - - "cinematic scroll experience" - - "decorative elements" - - "hero section depth" +// Reverse parallax (floats against scroll direction) +{ type: 'ParallaxScroll', speed: -0.3 } -choose_alternative_when: - - background_specific: BgParallax - - horizontal_movement: PanScroll - - opacity_based: FadeScroll - - more_control: MoveScroll - - 3d_rotation: ArcScroll, TiltScroll +// Layered depth effect (apply to different elements) +// Background layer +{ type: 'ParallaxScroll', speed: 0.2 } +// Midground layer +{ type: 'ParallaxScroll', speed: 0.5 } +// Foreground decorative elements +{ type: 'ParallaxScroll', speed: 0.8 } ``` From 2cce551ac6af25b6b4419359fa2efc565ed05463 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Sun, 25 Jan 2026 10:06:09 +0200 Subject: [PATCH 05/20] Run prettier --fix on packages/motion-presets/rules --- packages/motion-presets/rules/presets/PLAN.md | 91 +++++++++++-------- .../rules/presets/background-scroll.md | 40 ++++---- .../presets/background-scroll/bg-fade.md | 6 +- .../presets/background-scroll/bg-parallax.md | 4 +- .../presets/background-scroll/bg-zoom.md | 6 +- .../motion-presets/rules/presets/entrance.md | 54 +++++++---- .../rules/presets/entrance/arc-in.md | 8 +- .../rules/presets/entrance/bounce-in.md | 10 +- .../rules/presets/entrance/fade-in.md | 4 +- .../motion-presets/rules/presets/mouse.md | 26 +++--- .../rules/presets/mouse/bounce-mouse.md | 10 +- .../rules/presets/mouse/tilt-3d-mouse.md | 12 +-- .../rules/presets/mouse/track-mouse.md | 12 +-- .../motion-presets/rules/presets/ongoing.md | 29 +++--- .../rules/presets/ongoing/bounce.md | 8 +- .../rules/presets/ongoing/pulse.md | 8 +- .../rules/presets/ongoing/spin.md | 8 +- .../motion-presets/rules/presets/scroll.md | 49 ++++++---- .../rules/presets/scroll/arc-scroll.md | 8 +- .../rules/presets/scroll/fade-scroll.md | 8 +- .../rules/presets/scroll/parallax-scroll.md | 10 +- 21 files changed, 224 insertions(+), 187 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 5a1589db..8da84d42 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -3,31 +3,31 @@ name: Generate LLM Preset Rules overview: Create two-level rule files (category + preset) optimized for LLM decision flow. todos: - id: restructure - content: "Restructure: Create category files, update existing preset files to new format" + content: 'Restructure: Create category files, update existing preset files to new format' status: pending - id: category-entrance - content: "Create entrance.md category file with decision guide" + content: 'Create entrance.md category file with decision guide' status: pending - id: category-scroll - content: "Create scroll.md category file with decision guide" + content: 'Create scroll.md category file with decision guide' status: pending - id: category-ongoing - content: "Create ongoing.md category file with decision guide" + content: 'Create ongoing.md category file with decision guide' status: pending - id: category-mouse - content: "Create mouse.md category file with decision guide" + content: 'Create mouse.md category file with decision guide' status: pending - id: category-background - content: "Create background-scroll.md category file with decision guide" + content: 'Create background-scroll.md category file with decision guide' status: pending - id: update-presets - content: "Update existing preset files to simplified format (remove when-to-use, alternatives)" + content: 'Update existing preset files to simplified format (remove when-to-use, alternatives)' status: pending - id: review - content: "Review new structure with user" + content: 'Review new structure with user' status: pending - id: generate-remaining - content: "Generate remaining preset files" + content: 'Generate remaining preset files' status: pending --- @@ -109,13 +109,13 @@ Verbose overview of the category with alternative phrasings: ```markdown ## Description -Entrance animations bring elements into view for the first time. They create the initial -impression and set the tone for user interaction. These are one-shot animations that play +Entrance animations bring elements into view for the first time. They create the initial +impression and set the tone for user interaction. These are one-shot animations that play once when an element first appears. ## Synonyms -appear animation, reveal effect, intro animation, show animation, enter animation, +appear animation, reveal effect, intro animation, show animation, enter animation, page load animation, element appearance, fade in effect, loading animation ``` @@ -162,11 +162,13 @@ Each preset as a block with description, tags, and synonyms for LLM matching: ## Available Presets ### FadeIn + **Description**: Gradual opacity transition from invisible to visible. Universal, subtle, accessibility-safe. **Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear` **Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance ### ArcIn + **Description**: 3D curved swing like a door opening. Dramatic, cinematic, creates depth. **Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium` **Synonyms**: arc entrance, curved reveal, swing in, cinematic entrance, perspective reveal @@ -184,28 +186,33 @@ Help LLM choose between presets: ## Decision Guide ### By Tone + - **Subtle/Professional**: FadeIn, BlurIn, SlideIn - **Dramatic/Cinematic**: ArcIn, FlipIn, TurnIn - **Playful/Energetic**: BounceIn, SpinIn, PunchIn ### By Use Case + - **Hero sections**: ArcIn, ExpandIn, GrowIn - **Modals/Overlays**: FadeIn, DropIn - **List items**: FadeIn, SlideIn (with stagger) - **Notifications**: BounceIn, PunchIn ### Reduced Motion Alternatives + Always provide a reduced-motion fallback: + - Complex animations → FadeIn - Movement-based → FadeIn or no animation - 3D/Spinning → FadeIn ### Parallels in Other Categories + | Entrance | Scroll Equivalent | Mouse Equivalent | -|----------|-------------------|------------------| -| ArcIn | ArcScroll | - | -| FadeIn | FadeScroll | - | -| SpinIn | SpinScroll | SpinMouse | +| -------- | ----------------- | ---------------- | +| ArcIn | ArcScroll | - | +| FadeIn | FadeScroll | - | +| SpinIn | SpinScroll | SpinMouse | ``` --- @@ -242,6 +249,7 @@ category: entrance - Internal implementation details **Example:** + > Element swings into view along a curved path, like a door opening towards you. At the start, > the element is invisible and tilted away (as if rotated back into the screen). As the animation > plays, it gradually rotates forward while simultaneously fading in. The element follows an arc @@ -256,10 +264,10 @@ Include comprehensive parameter impact notes explaining what each value does vis ```typescript interface ArcIn { - direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 + direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` @@ -337,23 +345,25 @@ category: entrance ## Available Presets -| Preset | Description | -|--------|-------------| -| FadeIn | Gradual opacity transition, subtle and universal | -| ArcIn | 3D curved swing, dramatic and cinematic | -| BounceIn | Playful bouncing, energetic | -| SlideIn | Straight movement from direction | -| FlipIn | 3D flip rotation | -| ... | ... | +| Preset | Description | +| -------- | ------------------------------------------------ | +| FadeIn | Gradual opacity transition, subtle and universal | +| ArcIn | 3D curved swing, dramatic and cinematic | +| BounceIn | Playful bouncing, energetic | +| SlideIn | Straight movement from direction | +| FlipIn | 3D flip rotation | +| ... | ... | ## Decision Guide ### By Tone + - **Subtle/Professional**: FadeIn, BlurIn, SlideIn - **Dramatic/Cinematic**: ArcIn, FlipIn, TurnIn - **Playful/Energetic**: BounceIn, SpinIn, PunchIn ### By Use Case + - **Hero sections**: ArcIn, ExpandIn, GrowIn - **Modals/Overlays**: FadeIn, DropIn - **List items (staggered)**: FadeIn, SlideIn @@ -361,12 +371,12 @@ category: entrance ### Parallels in Other Categories -| Entrance | Scroll | Mouse | -|----------|--------|-------| -| ArcIn | ArcScroll | - | -| FadeIn | FadeScroll | - | -| SpinIn | SpinScroll | SpinMouse | -| - | ParallaxScroll | TrackMouse | +| Entrance | Scroll | Mouse | +| -------- | -------------- | ---------- | +| ArcIn | ArcScroll | - | +| FadeIn | FadeScroll | - | +| SpinIn | SpinScroll | SpinMouse | +| - | ParallaxScroll | TrackMouse | ``` --- @@ -383,22 +393,23 @@ category: entrance ## Visual Description -Element swings into view along a curved path, like a door opening towards you. -It starts tilted away and gradually flattens as it settles into place. +Element swings into view along a curved path, like a door opening towards you. +It starts tilted away and gradually flattens as it settles into place. Fades in while moving. The effect feels dramatic and cinematic. ## Parameters \`\`\`typescript interface ArcIn { - direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - duration?: number; // min: 0, max: 4000, default: 1200 - delay?: number; // min: 0, max: 8000, default: 0 +direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' +power?: 'soft' | 'medium' | 'hard'; // default: 'medium' +duration?: number; // min: 0, max: 4000, default: 1200 +delay?: number; // min: 0, max: 8000, default: 0 } \`\`\` **Parameter Impact:** + - `direction`: top/bottom tilts forward/back, left/right tilts sideways - `power`: soft = subtle, medium = noticeable, hard = dramatic diff --git a/packages/motion-presets/rules/presets/background-scroll.md b/packages/motion-presets/rules/presets/background-scroll.md index 6ad83f15..d30b5461 100644 --- a/packages/motion-presets/rules/presets/background-scroll.md +++ b/packages/motion-presets/rules/presets/background-scroll.md @@ -138,31 +138,31 @@ background animation, bg scroll effect, background parallax, section background, ### Background vs Regular Element Animations -| Use Background Scroll for... | Use regular Scroll for... | -|------------------------------|---------------------------| -| `background-image` on sections | `` elements in flow | -| CSS background media | Content that scrolls with page | -| Full-width/full-height backgrounds | Individual elements | -| Media behind content | Media as content | +| Use Background Scroll for... | Use regular Scroll for... | +| ---------------------------------- | ------------------------------ | +| `background-image` on sections | `` elements in flow | +| CSS background media | Content that scrolls with page | +| Full-width/full-height backgrounds | Individual elements | +| Media behind content | Media as content | **Exception**: `ImageParallax` is in this category but works on regular `` elements, not CSS backgrounds. ### Reduced Motion Alternatives -| Original | Reduced Motion Fallback | -|----------|------------------------| -| BgParallax | Static background (disable) | -| BgZoom, BgCloseUp, BgPullBack | BgFade or static | -| BgRotate, BgSkew | Disable | -| BgFake3D | Static or subtle BgParallax | -| BgFade | Keep (it's already subtle) | +| Original | Reduced Motion Fallback | +| ----------------------------- | --------------------------- | +| BgParallax | Static background (disable) | +| BgZoom, BgCloseUp, BgPullBack | BgFade or static | +| BgRotate, BgSkew | Disable | +| BgFake3D | Static or subtle BgParallax | +| BgFade | Keep (it's already subtle) | ### Parallels in Other Categories -| Background | Scroll | Entrance | -|------------|--------|----------| -| BgParallax | ParallaxScroll | - | -| BgZoom | GrowScroll | GrowIn | -| BgFade | FadeScroll | FadeIn | -| BgReveal | RevealScroll | RevealIn | -| BgRotate | SpinScroll | SpinIn | +| Background | Scroll | Entrance | +| ---------- | -------------- | -------- | +| BgParallax | ParallaxScroll | - | +| BgZoom | GrowScroll | GrowIn | +| BgFade | FadeScroll | FadeIn | +| BgReveal | RevealScroll | RevealIn | +| BgRotate | SpinScroll | SpinIn | diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md index 1288cc51..52191bf0 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md @@ -21,9 +21,9 @@ This is one of the safest background scroll effects—it's subtle, doesn't cause ```typescript interface BgFade { - range: 'in' | 'out'; // required - start?: number; // %, min: 0, max: 100, default: 0 (in) or 50 (out) - end?: number; // %, min: 0, max: 100, default: 50 (in) or 100 (out) + range: 'in' | 'out'; // required + start?: number; // %, min: 0, max: 100, default: 0 (in) or 50 (out) + end?: number; // %, min: 0, max: 100, default: 50 (in) or 100 (out) } ``` diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md index 78ed100d..21d5fab9 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md @@ -19,8 +19,8 @@ This is specifically for CSS background images/videos on containers, not for reg ```typescript interface BgParallax { - speed?: number; // ratio, min: 0.05, max: 0.95, step: 0.01, default: 0.2 - range?: 'continuous'; // only continuous supported + speed?: number; // ratio, min: 0.05, max: 0.95, step: 0.01, default: 0.2 + range?: 'continuous'; // only continuous supported } ``` diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md index a7eb2158..c7adb484 100644 --- a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md +++ b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md @@ -19,9 +19,9 @@ Background image scales up or down as the user scrolls, creating a cinematic dol ```typescript interface BgZoom { - direction: 'in' | 'out'; // default: 'in' - zoom?: number; // multiplier, min: 0.1, max: 10, step: 0.1, default: 10 - range?: 'continuous'; // only continuous supported + direction: 'in' | 'out'; // default: 'in' + zoom?: number; // multiplier, min: 0.1, max: 10, step: 0.1, default: 10 + range?: 'continuous'; // only continuous supported } ``` diff --git a/packages/motion-presets/rules/presets/entrance.md b/packages/motion-presets/rules/presets/entrance.md index 472b022f..c672553a 100644 --- a/packages/motion-presets/rules/presets/entrance.md +++ b/packages/motion-presets/rules/presets/entrance.md @@ -1,7 +1,21 @@ --- name: Entrance Animations category: entrance -tags: [entrance, appear, reveal, enter, load, show, intro, page-load, modal, popup, first-time, visibility] +tags: + [ + entrance, + appear, + reveal, + enter, + load, + show, + intro, + page-load, + modal, + popup, + first-time, + visibility, + ] --- # Entrance Animations @@ -207,25 +221,25 @@ appear animation, reveal effect, intro animation, show animation, enter animatio Always provide a reduced-motion fallback. Recommended mappings: -| Original | Reduced Motion Fallback | -|----------|------------------------| -| BounceIn, SpinIn, PunchIn | FadeIn | -| ArcIn, FlipIn, TurnIn | FadeIn | -| SlideIn, GlideIn | FadeIn (or keep with shorter duration) | -| ShuttersIn, ShapeIn | FadeIn | -| GlitchIn | FadeIn | +| Original | Reduced Motion Fallback | +| ------------------------- | -------------------------------------- | +| BounceIn, SpinIn, PunchIn | FadeIn | +| ArcIn, FlipIn, TurnIn | FadeIn | +| SlideIn, GlideIn | FadeIn (or keep with shorter duration) | +| ShuttersIn, ShapeIn | FadeIn | +| GlitchIn | FadeIn | ### Parallels in Other Categories -| Entrance | Scroll | Ongoing | Mouse | -|----------|--------|---------|-------| -| ArcIn | ArcScroll | - | - | -| FadeIn | FadeScroll | Flash | - | -| SpinIn | SpinScroll | Spin | SpinMouse | -| BounceIn | - | Bounce | BounceMouse | -| TiltIn | TiltScroll | - | Tilt3DMouse | -| FlipIn | FlipScroll | Flip | - | -| GrowIn | GrowScroll | - | ScaleMouse | -| SlideIn | SlideScroll | - | TrackMouse | -| BlurIn | BlurScroll | - | BlurMouse | -| RevealIn | RevealScroll | - | - | +| Entrance | Scroll | Ongoing | Mouse | +| -------- | ------------ | ------- | ----------- | +| ArcIn | ArcScroll | - | - | +| FadeIn | FadeScroll | Flash | - | +| SpinIn | SpinScroll | Spin | SpinMouse | +| BounceIn | - | Bounce | BounceMouse | +| TiltIn | TiltScroll | - | Tilt3DMouse | +| FlipIn | FlipScroll | Flip | - | +| GrowIn | GrowScroll | - | ScaleMouse | +| SlideIn | SlideScroll | - | TrackMouse | +| BlurIn | BlurScroll | - | BlurMouse | +| RevealIn | RevealScroll | - | - | diff --git a/packages/motion-presets/rules/presets/entrance/arc-in.md b/packages/motion-presets/rules/presets/entrance/arc-in.md index 249e1e75..650c329b 100644 --- a/packages/motion-presets/rules/presets/entrance/arc-in.md +++ b/packages/motion-presets/rules/presets/entrance/arc-in.md @@ -21,10 +21,10 @@ The effect feels dramatic, premium, and cinematic—best suited for hero element ```typescript interface ArcIn { - direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 + direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` diff --git a/packages/motion-presets/rules/presets/entrance/bounce-in.md b/packages/motion-presets/rules/presets/entrance/bounce-in.md index d238f5ef..15f66a33 100644 --- a/packages/motion-presets/rules/presets/entrance/bounce-in.md +++ b/packages/motion-presets/rules/presets/entrance/bounce-in.md @@ -21,11 +21,11 @@ The effect feels playful, energetic, and attention-grabbing. It's perfect for el ```typescript interface BounceIn { - direction: 'top' | 'right' | 'bottom' | 'left' | 'center'; // default: 'top' - power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - distanceFactor?: number; // min: 1, max: 4, step: 0.1, default: 1 - duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 + direction: 'top' | 'right' | 'bottom' | 'left' | 'center'; // default: 'top' + power?: 'soft' | 'medium' | 'hard'; // default: 'soft' + distanceFactor?: number; // min: 1, max: 4, step: 0.1, default: 1 + duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` diff --git a/packages/motion-presets/rules/presets/entrance/fade-in.md b/packages/motion-presets/rules/presets/entrance/fade-in.md index 184f1b6a..60dba287 100644 --- a/packages/motion-presets/rules/presets/entrance/fade-in.md +++ b/packages/motion-presets/rules/presets/entrance/fade-in.md @@ -17,8 +17,8 @@ FadeIn is the safest animation choice—it works everywhere, doesn't trigger mot ```typescript interface FadeIn { - duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 + duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` diff --git a/packages/motion-presets/rules/presets/mouse.md b/packages/motion-presets/rules/presets/mouse.md index 2279421d..06074a07 100644 --- a/packages/motion-presets/rules/presets/mouse.md +++ b/packages/motion-presets/rules/presets/mouse.md @@ -155,20 +155,20 @@ Since mouse animations don't work on touch devices: ### Reduced Motion Alternatives -| Original | Reduced Motion Fallback | -|----------|------------------------| +| Original | Reduced Motion Fallback | +| ------------------------- | ---------------------------- | | Tilt3DMouse, Track3DMouse | Disable or very subtle scale | -| TrackMouse, BounceMouse | Disable | -| SpinMouse | Disable | -| All mouse animations | Static state | +| TrackMouse, BounceMouse | Disable | +| SpinMouse | Disable | +| All mouse animations | Static state | ### Parallels in Other Categories -| Mouse | Entrance | Scroll | Ongoing | -|-------|----------|--------|---------| -| Tilt3DMouse | TiltIn | TiltScroll | - | -| TrackMouse | GlideIn | ParallaxScroll | - | -| BounceMouse | BounceIn | - | Bounce | -| SpinMouse | SpinIn | SpinScroll | Spin | -| ScaleMouse | GrowIn | GrowScroll | Pulse | -| BlurMouse | BlurIn | BlurScroll | - | +| Mouse | Entrance | Scroll | Ongoing | +| ----------- | -------- | -------------- | ------- | +| Tilt3DMouse | TiltIn | TiltScroll | - | +| TrackMouse | GlideIn | ParallaxScroll | - | +| BounceMouse | BounceIn | - | Bounce | +| SpinMouse | SpinIn | SpinScroll | Spin | +| ScaleMouse | GrowIn | GrowScroll | Pulse | +| BlurMouse | BlurIn | BlurScroll | - | diff --git a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md index 1ece0a4c..6ac9cc13 100644 --- a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md @@ -19,11 +19,11 @@ Element follows the mouse cursor with a bouncy, elastic motion. Instead of movin ```typescript interface BounceMouse { - distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // default: { value: 80, type: 'px' } - axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' - inverted?: boolean; // default: false - transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 - transitionEasing?: 'elastic' | 'bounce'; // default: 'elastic' + distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // default: { value: 80, type: 'px' } + axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' + inverted?: boolean; // default: false + transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 + transitionEasing?: 'elastic' | 'bounce'; // default: 'elastic' } ``` diff --git a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md index 38a99a1c..bbd09285 100644 --- a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md @@ -19,12 +19,12 @@ Element tilts in 3D space toward the mouse cursor, like holding a physical card ```typescript interface Tilt3DMouse { - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - angle?: number; // degrees, min: 5, max: 85, step: 1, default: 50 - perspective?: number; // px, min: 200, max: 1000, step: 50, default: 800 - inverted?: boolean; // default: false - transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 - transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + angle?: number; // degrees, min: 5, max: 85, step: 1, default: 50 + perspective?: number; // px, min: 200, max: 1000, step: 50, default: 800 + inverted?: boolean; // default: false + transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 + transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' } ``` diff --git a/packages/motion-presets/rules/presets/mouse/track-mouse.md b/packages/motion-presets/rules/presets/mouse/track-mouse.md index 7672cfa1..635ee4ea 100644 --- a/packages/motion-presets/rules/presets/mouse/track-mouse.md +++ b/packages/motion-presets/rules/presets/mouse/track-mouse.md @@ -19,12 +19,12 @@ Element follows the mouse cursor, translating its position based on cursor locat ```typescript interface TrackMouse { - distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // default: { value: 250, type: 'px' } - axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - inverted?: boolean; // default: false - transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 - transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' + distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // default: { value: 250, type: 'px' } + axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' + power?: 'soft' | 'medium' | 'hard'; // default: 'medium' + inverted?: boolean; // default: false + transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 + transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' } ``` diff --git a/packages/motion-presets/rules/presets/ongoing.md b/packages/motion-presets/rules/presets/ongoing.md index d4e4895d..138c32c9 100644 --- a/packages/motion-presets/rules/presets/ongoing.md +++ b/packages/motion-presets/rules/presets/ongoing.md @@ -1,7 +1,8 @@ --- name: Ongoing Animations category: ongoing -tags: [ongoing, continuous, loop, looping, repeating, infinite, persistent, ambient, status, indicator] +tags: + [ongoing, continuous, loop, looping, repeating, infinite, persistent, ambient, status, indicator] --- # Ongoing Animations @@ -157,19 +158,19 @@ continuous animation, looping animation, infinite animation, repeating animation ### Reduced Motion Alternatives -| Original | Reduced Motion Fallback | -|----------|------------------------| -| Spin, Swing, Flip | Stop animation or very slow Pulse | -| Bounce, Wiggle, Jello | Pulse (soft) or stop | -| Flash | Reduce frequency, ensure <3 flashes/second | -| DVD, Cross | Stop animation | +| Original | Reduced Motion Fallback | +| --------------------- | ------------------------------------------ | +| Spin, Swing, Flip | Stop animation or very slow Pulse | +| Bounce, Wiggle, Jello | Pulse (soft) or stop | +| Flash | Reduce frequency, ensure <3 flashes/second | +| DVD, Cross | Stop animation | ### Parallels in Other Categories -| Ongoing | Entrance | Scroll | Mouse | -|---------|----------|--------|-------| -| Pulse | DropIn | GrowScroll | ScaleMouse | -| Bounce | BounceIn | - | BounceMouse | -| Spin | SpinIn | SpinScroll | SpinMouse | -| Flip | FlipIn | FlipScroll | - | -| Flash | FadeIn | FadeScroll | - | +| Ongoing | Entrance | Scroll | Mouse | +| ------- | -------- | ---------- | ----------- | +| Pulse | DropIn | GrowScroll | ScaleMouse | +| Bounce | BounceIn | - | BounceMouse | +| Spin | SpinIn | SpinScroll | SpinMouse | +| Flip | FlipIn | FlipScroll | - | +| Flash | FadeIn | FadeScroll | - | diff --git a/packages/motion-presets/rules/presets/ongoing/bounce.md b/packages/motion-presets/rules/presets/ongoing/bounce.md index a25b95f6..e9a452f6 100644 --- a/packages/motion-presets/rules/presets/ongoing/bounce.md +++ b/packages/motion-presets/rules/presets/ongoing/bounce.md @@ -19,10 +19,10 @@ Bounce is one of the more intense ongoing animations. Use it when you want to ad ```typescript interface Bounce { - power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - intensity?: number; // 0-1, min: 0, max: 1, step: 0.1, default: 0.3 - duration?: number; // ms, min: 100, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 1000 + power?: 'soft' | 'medium' | 'hard'; // default: 'soft' + intensity?: number; // 0-1, min: 0, max: 1, step: 0.1, default: 0.3 + duration?: number; // ms, min: 100, max: 4000, step: 100, default: 1200 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 1000 } ``` diff --git a/packages/motion-presets/rules/presets/ongoing/pulse.md b/packages/motion-presets/rules/presets/ongoing/pulse.md index 27bbea87..ecbf80b6 100644 --- a/packages/motion-presets/rules/presets/ongoing/pulse.md +++ b/packages/motion-presets/rules/presets/ongoing/pulse.md @@ -19,10 +19,10 @@ Pulse is the most universally safe ongoing animation—it's subtle enough for pr ```typescript interface Pulse { - power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - intensity?: number; // 0-1, min: 0, max: 1, step: 0.1, default: 0 - duration?: number; // ms, min: 100, max: 4000, step: 100, default: 1300 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 1000 + power?: 'soft' | 'medium' | 'hard'; // default: 'soft' + intensity?: number; // 0-1, min: 0, max: 1, step: 0.1, default: 0 + duration?: number; // ms, min: 100, max: 4000, step: 100, default: 1300 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 1000 } ``` diff --git a/packages/motion-presets/rules/presets/ongoing/spin.md b/packages/motion-presets/rules/presets/ongoing/spin.md index b9e7f7a8..a3c8e498 100644 --- a/packages/motion-presets/rules/presets/ongoing/spin.md +++ b/packages/motion-presets/rules/presets/ongoing/spin.md @@ -19,10 +19,10 @@ Spin is ideal for loading indicators and decorative rotating elements, but it ca ```typescript interface Spin { - direction: 'clockwise' | 'counter-clockwise'; // default: 'clockwise' - power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - duration?: number; // ms, min: 100, max: 50000, step: 100, default: 7000 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 + direction: 'clockwise' | 'counter-clockwise'; // default: 'clockwise' + power?: 'soft' | 'medium' | 'hard'; // default: 'soft' + duration?: number; // ms, min: 100, max: 50000, step: 100, default: 7000 + delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 } ``` diff --git a/packages/motion-presets/rules/presets/scroll.md b/packages/motion-presets/rules/presets/scroll.md index d1efafbf..f76a72be 100644 --- a/packages/motion-presets/rules/presets/scroll.md +++ b/packages/motion-presets/rules/presets/scroll.md @@ -1,7 +1,18 @@ --- name: Scroll Animations category: scroll -tags: [scroll, parallax, scroll-driven, viewport, scroll-reveal, on-scroll, scroll-triggered, storytelling, progressive] +tags: + [ + scroll, + parallax, + scroll-driven, + viewport, + scroll-reveal, + on-scroll, + scroll-triggered, + storytelling, + progressive, + ] --- # Scroll Animations @@ -191,24 +202,24 @@ Custom `start` and `end` values allow fine-tuning the scroll range. ### Reduced Motion Alternatives -| Original | Reduced Motion Fallback | -|----------|------------------------| -| ParallaxScroll | Disable (static position) | -| ArcScroll, FlipScroll, Spin3dScroll | FadeScroll or disable | -| SpinScroll | Disable | -| TiltScroll, TurnScroll | FadeScroll | -| GrowScroll, ShrinkScroll | FadeScroll | +| Original | Reduced Motion Fallback | +| ----------------------------------- | ------------------------- | +| ParallaxScroll | Disable (static position) | +| ArcScroll, FlipScroll, Spin3dScroll | FadeScroll or disable | +| SpinScroll | Disable | +| TiltScroll, TurnScroll | FadeScroll | +| GrowScroll, ShrinkScroll | FadeScroll | ### Parallels in Other Categories -| Scroll | Entrance | Ongoing | Background | -|--------|----------|---------|------------| -| FadeScroll | FadeIn | - | BgFade | -| ArcScroll | ArcIn | - | - | -| ParallaxScroll | - | - | BgParallax | -| TiltScroll | TiltIn | - | - | -| FlipScroll | FlipIn | Flip | - | -| GrowScroll | GrowIn | - | BgZoom | -| SpinScroll | SpinIn | Spin | BgRotate | -| RevealScroll | RevealIn | - | BgReveal | -| BlurScroll | BlurIn | - | - | +| Scroll | Entrance | Ongoing | Background | +| -------------- | -------- | ------- | ---------- | +| FadeScroll | FadeIn | - | BgFade | +| ArcScroll | ArcIn | - | - | +| ParallaxScroll | - | - | BgParallax | +| TiltScroll | TiltIn | - | - | +| FlipScroll | FlipIn | Flip | - | +| GrowScroll | GrowIn | - | BgZoom | +| SpinScroll | SpinIn | Spin | BgRotate | +| RevealScroll | RevealIn | - | BgReveal | +| BlurScroll | BlurIn | - | - | diff --git a/packages/motion-presets/rules/presets/scroll/arc-scroll.md b/packages/motion-presets/rules/presets/scroll/arc-scroll.md index d3fe74d2..1e58638e 100644 --- a/packages/motion-presets/rules/presets/scroll/arc-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/arc-scroll.md @@ -21,10 +21,10 @@ The rotation is tied directly to scroll position, creating a satisfying connecti ```typescript interface ArcScroll { - direction: 'horizontal' | 'vertical'; // default: 'vertical' - range?: 'in' | 'out' | 'continuous'; // default varies - start?: number; // %, scroll position start - end?: number; // %, scroll position end + direction: 'horizontal' | 'vertical'; // default: 'vertical' + range?: 'in' | 'out' | 'continuous'; // default varies + start?: number; // %, scroll position start + end?: number; // %, scroll position end } ``` diff --git a/packages/motion-presets/rules/presets/scroll/fade-scroll.md b/packages/motion-presets/rules/presets/scroll/fade-scroll.md index 25956828..53cde26f 100644 --- a/packages/motion-presets/rules/presets/scroll/fade-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/fade-scroll.md @@ -19,10 +19,10 @@ The transition is smooth and linear, tied directly to scroll position—not time ```typescript interface FadeScroll { - range: 'in' | 'out'; // default: 'in' - opacity?: number; // 0-1, min: 0, max: 1, step: 0.01, default: 0 - start?: number; // %, min: 0, max: 100, default: 0 (in) or 50 (out) - end?: number; // %, min: 0, max: 100, default: 50 (in) or 100 (out) + range: 'in' | 'out'; // default: 'in' + opacity?: number; // 0-1, min: 0, max: 1, step: 0.01, default: 0 + start?: number; // %, min: 0, max: 100, default: 0 (in) or 50 (out) + end?: number; // %, min: 0, max: 100, default: 50 (in) or 100 (out) } ``` diff --git a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md index 9e72ece1..1cd64d9b 100644 --- a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md +++ b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md @@ -19,10 +19,10 @@ This is a continuous effect that runs throughout the entire time the element is ```typescript interface ParallaxScroll { - speed?: number; // ratio, min: -1, max: 1, step: 0.05, default: 0.5 - range?: 'continuous'; // only continuous supported - start?: number; // %, min: 0, max: 0, default: 0 - end?: number; // %, min: 100, max: 100, default: 100 + speed?: number; // ratio, min: -1, max: 1, step: 0.05, default: 0.5 + range?: 'continuous'; // only continuous supported + start?: number; // %, min: 0, max: 0, default: 0 + end?: number; // %, min: 100, max: 100, default: 100 } ``` @@ -67,7 +67,7 @@ interface ParallaxScroll { // Layered depth effect (apply to different elements) // Background layer { type: 'ParallaxScroll', speed: 0.2 } -// Midground layer +// Midground layer { type: 'ParallaxScroll', speed: 0.5 } // Foreground decorative elements { type: 'ParallaxScroll', speed: 0.8 } From a0739cea004af088dd8764a20785e72797ade12e Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Sun, 25 Jan 2026 10:49:45 +0200 Subject: [PATCH 06/20] Refactor motion presets documentation for consistency and clarity - Updated descriptions, tags, and synonyms across multiple preset files to ensure uniform formatting. - Enhanced readability by standardizing bullet points and spacing. - Improved accessibility considerations and decision guides in category files for better user guidance. --- packages/motion-presets/rules/presets/PLAN.md | 79 +++++++--- .../rules/presets/background-scroll.md | 72 ++++----- .../motion-presets/rules/presets/entrance.md | 138 +++++++++--------- .../motion-presets/rules/presets/mouse.md | 72 ++++----- .../motion-presets/rules/presets/ongoing.md | 84 +++++------ .../motion-presets/rules/presets/scroll.md | 114 +++++++-------- 6 files changed, 299 insertions(+), 260 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 8da84d42..5b78a7db 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -81,9 +81,15 @@ Update the 15 pilot preset files to the simplified format: LLM decision flow is a waterfall - it won't read all preset descriptions before selecting. It needs: 1. First: "Which category?" → Read category file -2. Then: "Which preset?" → Use decision table in category file +2. Then: "Which preset?" → Use decision guide in category file 3. Finally: "How to configure?" → Read specific preset file +**LLM Decision Checklist:** + +- [ ] Category selected based on trigger type (page load, scroll, continuous, mouse, background) +- [ ] Preset selected using decision guide (by tone, use case, or element type) +- [ ] Parameters configured using preset file details + ## Category File Format Each category file guides the LLM to select the right preset. @@ -163,15 +169,15 @@ Each preset as a block with description, tags, and synonyms for LLM matching: ### FadeIn -**Description**: Gradual opacity transition from invisible to visible. Universal, subtle, accessibility-safe. -**Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear` -**Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance +- **Description**: Gradual opacity transition from invisible to visible. Universal, subtle, accessibility-safe. +- **Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear` +- **Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance ### ArcIn -**Description**: 3D curved swing like a door opening. Dramatic, cinematic, creates depth. -**Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium` -**Synonyms**: arc entrance, curved reveal, swing in, cinematic entrance, perspective reveal +- **Description**: 3D curved swing like a door opening. Dramatic, cinematic, creates depth. +- **Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium` +- **Synonyms**: arc entrance, curved reveal, swing in, cinematic entrance, perspective reveal ... ``` @@ -345,14 +351,31 @@ category: entrance ## Available Presets -| Preset | Description | -| -------- | ------------------------------------------------ | -| FadeIn | Gradual opacity transition, subtle and universal | -| ArcIn | 3D curved swing, dramatic and cinematic | -| BounceIn | Playful bouncing, energetic | -| SlideIn | Straight movement from direction | -| FlipIn | 3D flip rotation | -| ... | ... | +### FadeIn + +- **Description**: Gradual opacity transition from invisible to visible. Universal, subtle, accessibility-safe. +- **Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear` +- **Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance + +### ArcIn + +- **Description**: 3D curved swing like a door opening. Dramatic, cinematic, creates depth. +- **Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium` +- **Synonyms**: arc entrance, curved reveal, swing in, cinematic entrance, perspective reveal + +### BounceIn + +- **Description**: Playful bouncing entrance with spring physics. Energetic, fun, attention-grabbing. +- **Tags**: `bounce`, `spring`, `playful`, `energetic`, `fun`, `attention` +- **Synonyms**: bounce in, spring entrance, playful reveal, elastic entrance + +### SlideIn + +- **Description**: Straight movement from direction. Clean, professional, versatile. +- **Tags**: `slide`, `move`, `direction`, `clean`, `professional`, `versatile` +- **Synonyms**: slide in, move in, glide entrance, directional reveal + +... ## Decision Guide @@ -464,7 +487,7 @@ rules/presets/ 2. **Description & Synonyms**: Verbose overview with alternative phrasings 3. **When to Use / When NOT to Use**: Clear guidance on category selection 4. **Accessibility Considerations**: Reduced motion, vestibular safety, duration guidelines -5. **Preset List**: Brief 1-line descriptions for quick scanning +5. **Preset List**: Description + Tags + Synonyms per preset for LLM intent matching 6. **Decision Guide**: Group by tone, use case, reduced-motion alternatives, cross-category parallels ### Preset Files (Verbose) @@ -480,6 +503,16 @@ rules/presets/ - **Constraints**: `effects-kit/src/effects/{category}/{preset}.ts` - **Base params**: `effects-kit/src/effects/baseParams.ts` +### Validation Checklist + +Before finalizing each preset file, verify: + +- [ ] Parameter defaults match source in `effects-kit` +- [ ] Min/max/step values are accurate +- [ ] Enum options (direction, power, easing) match TypeScript types +- [ ] Direction type is correct (FourDirections, FiveDirections, EightDirections) +- [ ] Easing exclusions noted for clipped animations + ### Notes on Parameter Subsets - Direction types vary: FourDirections, FiveDirections (adds center), EightDirections (adds diagonals) @@ -487,7 +520,13 @@ rules/presets/ ### Accessibility Guidelines -- Always mention `prefers-reduced-motion` media query support -- Recommend FadeIn as universal fallback -- Note vestibular triggers (spinning, parallax, large movement) -- Duration guidance: <500ms functional, <1200ms decorative +**Must include in every category file:** + +- [ ] `prefers-reduced-motion` media query support mentioned +- [ ] Reduced-motion fallback specified (typically FadeIn or no animation) +- [ ] Vestibular trigger warnings for: spinning, parallax, large-scale movement, 3D transforms + +**Must include in every preset file:** + +- [ ] Reduced-motion alternative noted if preset has vestibular triggers +- [ ] Duration recommendation (functional UI: <500ms, decorative: <1200ms) diff --git a/packages/motion-presets/rules/presets/background-scroll.md b/packages/motion-presets/rules/presets/background-scroll.md index d30b5461..3ae8678a 100644 --- a/packages/motion-presets/rules/presets/background-scroll.md +++ b/packages/motion-presets/rules/presets/background-scroll.md @@ -47,75 +47,75 @@ background animation, bg scroll effect, background parallax, section background, ### BgParallax -**Description**: Background moves slower than scroll creating depth illusion. Like background is further away than foreground content. -**Tags**: `parallax`, `depth`, `movement`, `slow`, `layer`, `distance`, `immersive` -**Synonyms**: background parallax, bg parallax, background scroll, parallax background, depth background +- **Description**: Background moves slower than scroll creating depth illusion. Like background is further away than foreground content. +- **Tags**: `parallax`, `depth`, `movement`, `slow`, `layer`, `distance`, `immersive` +- **Synonyms**: background parallax, bg parallax, background scroll, parallax background, depth background ### BgZoom -**Description**: Background zooms in/out as user scrolls. Cinematic dolly-like effect, camera moving towards/away. -**Tags**: `zoom`, `scale`, `dolly`, `cinematic`, `dramatic`, `approach`, `retreat` -**Synonyms**: background zoom, bg zoom, zoom scroll, dolly zoom, zoom effect background, ken burns scroll +- **Description**: Background zooms in/out as user scrolls. Cinematic dolly-like effect, camera moving towards/away. +- **Tags**: `zoom`, `scale`, `dolly`, `cinematic`, `dramatic`, `approach`, `retreat` +- **Synonyms**: background zoom, bg zoom, zoom scroll, dolly zoom, zoom effect background, ken burns scroll ### BgFade -**Description**: Background opacity transition on scroll. Subtle fade in/out as section enters/exits viewport. -**Tags**: `fade`, `opacity`, `transition`, `subtle`, `reveal`, `in`, `out` -**Synonyms**: background fade, bg fade, fade background, background opacity, background reveal +- **Description**: Background opacity transition on scroll. Subtle fade in/out as section enters/exits viewport. +- **Tags**: `fade`, `opacity`, `transition`, `subtle`, `reveal`, `in`, `out` +- **Synonyms**: background fade, bg fade, fade background, background opacity, background reveal ### BgFadeBack -**Description**: Fade targeting back layer specifically. For layered backgrounds with separate fade control. -**Tags**: `fade`, `back`, `layer`, `opacity`, `separate`, `control` -**Synonyms**: bg fade back, back layer fade, layered fade, separate layer fade +- **Description**: Fade targeting back layer specifically. For layered backgrounds with separate fade control. +- **Tags**: `fade`, `back`, `layer`, `opacity`, `separate`, `control` +- **Synonyms**: bg fade back, back layer fade, layered fade, separate layer fade ### BgPan -**Description**: Horizontal/vertical background panning. Background slides across as user scrolls. -**Tags**: `pan`, `horizontal`, `vertical`, `slide`, `movement`, `traverse` -**Synonyms**: background pan, bg pan, pan scroll, horizontal background, sliding background +- **Description**: Horizontal/vertical background panning. Background slides across as user scrolls. +- **Tags**: `pan`, `horizontal`, `vertical`, `slide`, `movement`, `traverse` +- **Synonyms**: background pan, bg pan, pan scroll, horizontal background, sliding background ### BgRotate -**Description**: Background rotation driven by scroll. Dynamic unusual effect, background spins with scroll. -**Tags**: `rotate`, `spin`, `dynamic`, `unusual`, `creative`, `turn` -**Synonyms**: background rotate, bg rotate, spin background, rotation scroll, turning background +- **Description**: Background rotation driven by scroll. Dynamic unusual effect, background spins with scroll. +- **Tags**: `rotate`, `spin`, `dynamic`, `unusual`, `creative`, `turn` +- **Synonyms**: background rotate, bg rotate, spin background, rotation scroll, turning background ### BgSkew -**Description**: Background skew distortion on scroll. Experimental angled distortion effect. -**Tags**: `skew`, `distortion`, `angle`, `experimental`, `warp`, `tilt` -**Synonyms**: background skew, bg skew, skew scroll, distortion background, angled background +- **Description**: Background skew distortion on scroll. Experimental angled distortion effect. +- **Tags**: `skew`, `distortion`, `angle`, `experimental`, `warp`, `tilt` +- **Synonyms**: background skew, bg skew, skew scroll, distortion background, angled background ### BgReveal -**Description**: Clip-based background reveal. Theatrical curtain-like unveiling of background. -**Tags**: `reveal`, `clip`, `mask`, `theatrical`, `curtain`, `unveil`, `progressive` -**Synonyms**: background reveal, bg reveal, clip reveal, curtain background, unveiling background +- **Description**: Clip-based background reveal. Theatrical curtain-like unveiling of background. +- **Tags**: `reveal`, `clip`, `mask`, `theatrical`, `curtain`, `unveil`, `progressive` +- **Synonyms**: background reveal, bg reveal, clip reveal, curtain background, unveiling background ### BgCloseUp -**Description**: Alternative zoom implementation. Cinematic close-up approach effect on background. -**Tags**: `closeup`, `zoom`, `cinematic`, `approach`, `alternative`, `scale` -**Synonyms**: bg close up, close up zoom, cinematic closeup, approach zoom +- **Description**: Alternative zoom implementation. Cinematic close-up approach effect on background. +- **Tags**: `closeup`, `zoom`, `cinematic`, `approach`, `alternative`, `scale` +- **Synonyms**: bg close up, close up zoom, cinematic closeup, approach zoom ### BgPullBack -**Description**: Reverse zoom (pulling away). Expansive revealing effect, camera retreating from background. -**Tags**: `pullback`, `zoom`, `reverse`, `expansive`, `retreat`, `reveal`, `wide` -**Synonyms**: bg pull back, pull back zoom, reverse zoom, expansive reveal, retreat zoom +- **Description**: Reverse zoom (pulling away). Expansive revealing effect, camera retreating from background. +- **Tags**: `pullback`, `zoom`, `reverse`, `expansive`, `retreat`, `reveal`, `wide` +- **Synonyms**: bg pull back, pull back zoom, reverse zoom, expansive reveal, retreat zoom ### BgFake3D -**Description**: Simulated 3D depth layers. Immersive parallax-enhanced depth simulation. -**Tags**: `fake3d`, `depth`, `layers`, `immersive`, `3d`, `parallax`, `simulation` -**Synonyms**: bg fake 3d, simulated 3d, depth layers, immersive background, 3d parallax +- **Description**: Simulated 3D depth layers. Immersive parallax-enhanced depth simulation. +- **Tags**: `fake3d`, `depth`, `layers`, `immersive`, `3d`, `parallax`, `simulation` +- **Synonyms**: bg fake 3d, simulated 3d, depth layers, immersive background, 3d parallax ### ImageParallax -**Description**: Parallax for regular img elements (not CSS backgrounds). Same parallax effect for inline images. -**Tags**: `image`, `parallax`, `img`, `inline`, `element`, `depth` -**Synonyms**: image parallax, img parallax, inline image parallax, element parallax +- **Description**: Parallax for regular img elements (not CSS backgrounds). Same parallax effect for inline images. +- **Tags**: `image`, `parallax`, `img`, `inline`, `element`, `depth` +- **Synonyms**: image parallax, img parallax, inline image parallax, element parallax ## Decision Guide diff --git a/packages/motion-presets/rules/presets/entrance.md b/packages/motion-presets/rules/presets/entrance.md index c672553a..a150dd75 100644 --- a/packages/motion-presets/rules/presets/entrance.md +++ b/packages/motion-presets/rules/presets/entrance.md @@ -60,141 +60,141 @@ appear animation, reveal effect, intro animation, show animation, enter animatio ### FadeIn -**Description**: Gradual opacity transition from invisible to visible. No movement or shape changes - just smooth materialization. The simplest and most universally applicable entrance. -**Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear`, `universal`, `accessible` -**Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance, dissolve in +- **Description**: Gradual opacity transition from invisible to visible. No movement or shape changes - just smooth materialization. The simplest and most universally applicable entrance. +- **Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear`, `universal`, `accessible` +- **Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance, dissolve in ### ArcIn -**Description**: 3D curved swing like a door opening towards you. Starts tilted away and gradually flattens as it settles. Dramatic, cinematic, creates depth. -**Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium`, `hero` -**Synonyms**: arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective reveal, dramatic arc, door opening +- **Description**: 3D curved swing like a door opening towards you. Starts tilted away and gradually flattens as it settles. Dramatic, cinematic, creates depth. +- **Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium`, `hero` +- **Synonyms**: arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective reveal, dramatic arc, door opening ### BlurIn -**Description**: Element transitions from blurry to sharp focus while fading in. Soft, dreamy, draws attention to the sharpening moment. -**Tags**: `blur`, `focus`, `soft`, `dreamy`, `gentle`, `elegant`, `attention` -**Synonyms**: blur reveal, focus in, soft reveal, dreamy entrance, blur to focus, defocus to focus +- **Description**: Element transitions from blurry to sharp focus while fading in. Soft, dreamy, draws attention to the sharpening moment. +- **Tags**: `blur`, `focus`, `soft`, `dreamy`, `gentle`, `elegant`, `attention` +- **Synonyms**: blur reveal, focus in, soft reveal, dreamy entrance, blur to focus, defocus to focus ### BounceIn -**Description**: Playful bouncing physics - overshoots landing spot then bounces smaller and smaller until settled. Fun, energetic, attention-grabbing. -**Tags**: `bounce`, `playful`, `energetic`, `fun`, `elastic`, `spring`, `attention`, `physics` -**Synonyms**: bounce entrance, bouncy reveal, spring in, elastic entrance, playful appear, jump in, hop in +- **Description**: Playful bouncing physics - overshoots landing spot then bounces smaller and smaller until settled. Fun, energetic, attention-grabbing. +- **Tags**: `bounce`, `playful`, `energetic`, `fun`, `elastic`, `spring`, `attention`, `physics` +- **Synonyms**: bounce entrance, bouncy reveal, spring in, elastic entrance, playful appear, jump in, hop in ### CircleIn -**Description**: Circular mask expanding from center point to reveal element. Geometric, modern, spotlight-like effect. -**Tags**: `circle`, `mask`, `geometric`, `modern`, `spotlight`, `radial`, `reveal` -**Synonyms**: circle reveal, radial reveal, spotlight entrance, circular mask, expanding circle +- **Description**: Circular mask expanding from center point to reveal element. Geometric, modern, spotlight-like effect. +- **Tags**: `circle`, `mask`, `geometric`, `modern`, `spotlight`, `radial`, `reveal` +- **Synonyms**: circle reveal, radial reveal, spotlight entrance, circular mask, expanding circle ### CurveIn -**Description**: Alternative curved 3D motion path. Similar to ArcIn but with different trajectory characteristics. -**Tags**: `3d`, `curve`, `path`, `motion`, `trajectory`, `cinematic` -**Synonyms**: curved entrance, path reveal, curved motion, trajectory entrance +- **Description**: Alternative curved 3D motion path. Similar to ArcIn but with different trajectory characteristics. +- **Tags**: `3d`, `curve`, `path`, `motion`, `trajectory`, `cinematic` +- **Synonyms**: curved entrance, path reveal, curved motion, trajectory entrance ### DropIn -**Description**: Falls from above with subtle scale/bounce on landing. Gravity-like, natural feeling entrance with soft impact. -**Tags**: `drop`, `fall`, `gravity`, `natural`, `scale`, `bounce`, `impact`, `landing` -**Synonyms**: drop entrance, fall in, gravity drop, landing animation, drop down +- **Description**: Falls from above with subtle scale/bounce on landing. Gravity-like, natural feeling entrance with soft impact. +- **Tags**: `drop`, `fall`, `gravity`, `natural`, `scale`, `bounce`, `impact`, `landing` +- **Synonyms**: drop entrance, fall in, gravity drop, landing animation, drop down ### ExpandIn -**Description**: Expands outward from center point. Growing, revealing, spotlight-like emergence effect. -**Tags**: `expand`, `grow`, `center`, `scale`, `emergence`, `spotlight`, `reveal` -**Synonyms**: expand entrance, growing reveal, center expand, emergence, outward growth +- **Description**: Expands outward from center point. Growing, revealing, spotlight-like emergence effect. +- **Tags**: `expand`, `grow`, `center`, `scale`, `emergence`, `spotlight`, `reveal` +- **Synonyms**: expand entrance, growing reveal, center expand, emergence, outward growth ### FlipIn -**Description**: 3D card flip rotation to reveal element. Dramatic, reveals "other side", card-like metaphor. -**Tags**: `flip`, `3d`, `rotation`, `card`, `dramatic`, `reveal`, `turn` -**Synonyms**: flip entrance, card flip, 3d flip, flip reveal, turn over, flip animation +- **Description**: 3D card flip rotation to reveal element. Dramatic, reveals "other side", card-like metaphor. +- **Tags**: `flip`, `3d`, `rotation`, `card`, `dramatic`, `reveal`, `turn` +- **Synonyms**: flip entrance, card flip, 3d flip, flip reveal, turn over, flip animation ### FloatIn -**Description**: Gentle floating/drifting entrance. Ethereal, light, dreamy movement as if carried by air. -**Tags**: `float`, `drift`, `ethereal`, `light`, `dreamy`, `gentle`, `air`, `soft` -**Synonyms**: float entrance, drift in, floating reveal, ethereal entrance, airy entrance +- **Description**: Gentle floating/drifting entrance. Ethereal, light, dreamy movement as if carried by air. +- **Tags**: `float`, `drift`, `ethereal`, `light`, `dreamy`, `gentle`, `air`, `soft` +- **Synonyms**: float entrance, drift in, floating reveal, ethereal entrance, airy entrance ### FoldIn -**Description**: Paper-folding 3D effect. Origami-like, creative, element unfolds into view. -**Tags**: `fold`, `3d`, `paper`, `origami`, `creative`, `unfold`, `dimensional` -**Synonyms**: fold entrance, paper fold, origami reveal, unfold animation, folding entrance +- **Description**: Paper-folding 3D effect. Origami-like, creative, element unfolds into view. +- **Tags**: `fold`, `3d`, `paper`, `origami`, `creative`, `unfold`, `dimensional` +- **Synonyms**: fold entrance, paper fold, origami reveal, unfold animation, folding entrance ### GlideIn -**Description**: Smooth 2D glide from direction with angle control. Clean, directional, professional movement. -**Tags**: `glide`, `slide`, `smooth`, `directional`, `clean`, `professional`, `angle` -**Synonyms**: glide entrance, smooth slide, directional glide, angled entrance, sliding reveal +- **Description**: Smooth 2D glide from direction with angle control. Clean, directional, professional movement. +- **Tags**: `glide`, `slide`, `smooth`, `directional`, `clean`, `professional`, `angle` +- **Synonyms**: glide entrance, smooth slide, directional glide, angled entrance, sliding reveal ### GlitchIn -**Description**: Digital glitch/distortion effect. Edgy, tech-inspired, disruptive visual entrance. -**Tags**: `glitch`, `digital`, `distortion`, `edgy`, `tech`, `disruption`, `modern`, `cyber` -**Synonyms**: glitch entrance, digital reveal, distortion entrance, tech glitch, cyber entrance +- **Description**: Digital glitch/distortion effect. Edgy, tech-inspired, disruptive visual entrance. +- **Tags**: `glitch`, `digital`, `distortion`, `edgy`, `tech`, `disruption`, `modern`, `cyber` +- **Synonyms**: glitch entrance, digital reveal, distortion entrance, tech glitch, cyber entrance ### GrowIn -**Description**: Scale from small to full size. Expanding, emerging, element grows into existence. -**Tags**: `grow`, `scale`, `expand`, `emerge`, `size`, `zoom`, `magnify` -**Synonyms**: grow entrance, scale up, expanding entrance, zoom in, size grow, emergence +- **Description**: Scale from small to full size. Expanding, emerging, element grows into existence. +- **Tags**: `grow`, `scale`, `expand`, `emerge`, `size`, `zoom`, `magnify` +- **Synonyms**: grow entrance, scale up, expanding entrance, zoom in, size grow, emergence ### PunchIn -**Description**: Corner-based scale with energy and impact. Impactful, attention-grabbing, punchy entrance. -**Tags**: `punch`, `impact`, `corner`, `scale`, `energy`, `attention`, `bold`, `strong` -**Synonyms**: punch entrance, impact reveal, corner punch, bold entrance, powerful entrance +- **Description**: Corner-based scale with energy and impact. Impactful, attention-grabbing, punchy entrance. +- **Tags**: `punch`, `impact`, `corner`, `scale`, `energy`, `attention`, `bold`, `strong` +- **Synonyms**: punch entrance, impact reveal, corner punch, bold entrance, powerful entrance ### RevealIn -**Description**: Directional clip/mask reveal like a curtain opening. Theatrical, unveiling, directional exposure. -**Tags**: `reveal`, `clip`, `mask`, `curtain`, `directional`, `theatrical`, `unveil` -**Synonyms**: reveal entrance, curtain reveal, clip reveal, unveiling, mask reveal, wipe in +- **Description**: Directional clip/mask reveal like a curtain opening. Theatrical, unveiling, directional exposure. +- **Tags**: `reveal`, `clip`, `mask`, `curtain`, `directional`, `theatrical`, `unveil` +- **Synonyms**: reveal entrance, curtain reveal, clip reveal, unveiling, mask reveal, wipe in ### ShapeIn -**Description**: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise, customizable mask shapes. -**Tags**: `shape`, `mask`, `geometric`, `circle`, `square`, `diamond`, `precise`, `custom` -**Synonyms**: shape reveal, geometric reveal, mask entrance, shape mask, custom shape reveal +- **Description**: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise, customizable mask shapes. +- **Tags**: `shape`, `mask`, `geometric`, `circle`, `square`, `diamond`, `precise`, `custom` +- **Synonyms**: shape reveal, geometric reveal, mask entrance, shape mask, custom shape reveal ### ShuttersIn -**Description**: Venetian blind strip reveal. Segmented, rhythmic, strips revealing content progressively. -**Tags**: `shutters`, `blinds`, `strips`, `segmented`, `rhythmic`, `venetian`, `progressive` -**Synonyms**: shutters reveal, blind reveal, strip entrance, venetian entrance, segmented reveal +- **Description**: Venetian blind strip reveal. Segmented, rhythmic, strips revealing content progressively. +- **Tags**: `shutters`, `blinds`, `strips`, `segmented`, `rhythmic`, `venetian`, `progressive` +- **Synonyms**: shutters reveal, blind reveal, strip entrance, venetian entrance, segmented reveal ### SlideIn -**Description**: Straight movement from direction. Clean, simple, versatile directional entrance. -**Tags**: `slide`, `move`, `directional`, `clean`, `simple`, `versatile`, `translate` -**Synonyms**: slide entrance, slide in, directional slide, movement entrance, translate in +- **Description**: Straight movement from direction. Clean, simple, versatile directional entrance. +- **Tags**: `slide`, `move`, `directional`, `clean`, `simple`, `versatile`, `translate` +- **Synonyms**: slide entrance, slide in, directional slide, movement entrance, translate in ### SpinIn -**Description**: Rotating entrance with spin. Dynamic, playful, attention-grabbing rotation into view. -**Tags**: `spin`, `rotate`, `dynamic`, `playful`, `attention`, `rotation`, `turn` -**Synonyms**: spin entrance, rotating reveal, spin in, rotation entrance, twirl in +- **Description**: Rotating entrance with spin. Dynamic, playful, attention-grabbing rotation into view. +- **Tags**: `spin`, `rotate`, `dynamic`, `playful`, `attention`, `rotation`, `turn` +- **Synonyms**: spin entrance, rotating reveal, spin in, rotation entrance, twirl in ### TiltIn -**Description**: 3D tilt into view. Subtle depth, elegant perspective shift as element appears. -**Tags**: `tilt`, `3d`, `subtle`, `depth`, `elegant`, `perspective`, `angle` -**Synonyms**: tilt entrance, perspective tilt, 3d tilt, angled reveal, subtle 3d +- **Description**: 3D tilt into view. Subtle depth, elegant perspective shift as element appears. +- **Tags**: `tilt`, `3d`, `subtle`, `depth`, `elegant`, `perspective`, `angle` +- **Synonyms**: tilt entrance, perspective tilt, 3d tilt, angled reveal, subtle 3d ### TurnIn -**Description**: Corner-pivot 3D rotation. Complex, dramatic, premium feeling entrance with pivot point. -**Tags**: `turn`, `3d`, `corner`, `pivot`, `dramatic`, `premium`, `complex`, `rotation` -**Synonyms**: turn entrance, corner turn, pivot reveal, 3d turn, corner rotation +- **Description**: Corner-pivot 3D rotation. Complex, dramatic, premium feeling entrance with pivot point. +- **Tags**: `turn`, `3d`, `corner`, `pivot`, `dramatic`, `premium`, `complex`, `rotation` +- **Synonyms**: turn entrance, corner turn, pivot reveal, 3d turn, corner rotation ### WinkIn -**Description**: Split-in-half reveal from center. Unique, eye-like opening, center-split entrance. -**Tags**: `wink`, `split`, `center`, `unique`, `eye`, `opening`, `divide` -**Synonyms**: wink entrance, split reveal, center split, eye opening, divide reveal +- **Description**: Split-in-half reveal from center. Unique, eye-like opening, center-split entrance. +- **Tags**: `wink`, `split`, `center`, `unique`, `eye`, `opening`, `divide` +- **Synonyms**: wink entrance, split reveal, center split, eye opening, divide reveal ## Decision Guide diff --git a/packages/motion-presets/rules/presets/mouse.md b/packages/motion-presets/rules/presets/mouse.md index 06074a07..125bc32e 100644 --- a/packages/motion-presets/rules/presets/mouse.md +++ b/packages/motion-presets/rules/presets/mouse.md @@ -47,75 +47,75 @@ cursor animation, hover effect, mouse follow, cursor tracking, mouse parallax, i ### Tilt3DMouse -**Description**: Element tilts towards cursor like holding a card and angling it. 3D perspective rotation following mouse position. -**Tags**: `tilt`, `3d`, `perspective`, `card`, `rotate`, `angle`, `premium`, `interactive` -**Synonyms**: 3d tilt, mouse tilt, perspective tilt, interactive tilt, hover tilt, card tilt, gyroscope effect +- **Description**: Element tilts towards cursor like holding a card and angling it. 3D perspective rotation following mouse position. +- **Tags**: `tilt`, `3d`, `perspective`, `card`, `rotate`, `angle`, `premium`, `interactive` +- **Synonyms**: 3d tilt, mouse tilt, perspective tilt, interactive tilt, hover tilt, card tilt, gyroscope effect ### TrackMouse -**Description**: Element follows cursor position, moving in same direction. Floating object that drifts towards where you point. -**Tags**: `track`, `follow`, `translate`, `movement`, `parallax`, `float`, `drift` -**Synonyms**: mouse tracking, follow cursor, cursor follow, mouse movement, parallax mouse, floating follow +- **Description**: Element follows cursor position, moving in same direction. Floating object that drifts towards where you point. +- **Tags**: `track`, `follow`, `translate`, `movement`, `parallax`, `float`, `drift` +- **Synonyms**: mouse tracking, follow cursor, cursor follow, mouse movement, parallax mouse, floating follow ### BounceMouse -**Description**: Bouncy/elastic cursor following. Overshoots and wobbles before settling, springy playful motion. -**Tags**: `bounce`, `elastic`, `spring`, `playful`, `wobble`, `overshoot`, `jelly` -**Synonyms**: bouncy mouse, elastic follow, spring mouse, bouncy cursor effect, elastic tracking +- **Description**: Bouncy/elastic cursor following. Overshoots and wobbles before settling, springy playful motion. +- **Tags**: `bounce`, `elastic`, `spring`, `playful`, `wobble`, `overshoot`, `jelly` +- **Synonyms**: bouncy mouse, elastic follow, spring mouse, bouncy cursor effect, elastic tracking ### Track3DMouse -**Description**: Combined translation + 3D rotation following mouse. Complex immersive effect with movement and tilt. -**Tags**: `track`, `3d`, `translate`, `rotate`, `complex`, `immersive`, `combined` -**Synonyms**: 3d track mouse, combined mouse effect, translate and tilt, immersive mouse +- **Description**: Combined translation + 3D rotation following mouse. Complex immersive effect with movement and tilt. +- **Tags**: `track`, `3d`, `translate`, `rotate`, `complex`, `immersive`, `combined` +- **Synonyms**: 3d track mouse, combined mouse effect, translate and tilt, immersive mouse ### SpinMouse -**Description**: Rotation following mouse angle. Element spins/rotates based on cursor position around element. -**Tags**: `spin`, `rotate`, `angle`, `circular`, `dynamic`, `follow` -**Synonyms**: mouse spin, rotation follow, angle mouse, spinning cursor effect +- **Description**: Rotation following mouse angle. Element spins/rotates based on cursor position around element. +- **Tags**: `spin`, `rotate`, `angle`, `circular`, `dynamic`, `follow` +- **Synonyms**: mouse spin, rotation follow, angle mouse, spinning cursor effect ### ScaleMouse -**Description**: Scale based on cursor distance. Element grows/shrinks depending on how close mouse is. -**Tags**: `scale`, `zoom`, `distance`, `proximity`, `grow`, `shrink`, `size` -**Synonyms**: scale mouse, zoom mouse, proximity scale, distance zoom, hover scale +- **Description**: Scale based on cursor distance. Element grows/shrinks depending on how close mouse is. +- **Tags**: `scale`, `zoom`, `distance`, `proximity`, `grow`, `shrink`, `size` +- **Synonyms**: scale mouse, zoom mouse, proximity scale, distance zoom, hover scale ### SwivelMouse -**Description**: Z-axis rotation following cursor. Unique gyroscope-like rotation on vertical axis. -**Tags**: `swivel`, `z-axis`, `rotate`, `gyroscope`, `unique`, `vertical` -**Synonyms**: swivel mouse, z rotation, gyroscope mouse, vertical rotation +- **Description**: Z-axis rotation following cursor. Unique gyroscope-like rotation on vertical axis. +- **Tags**: `swivel`, `z-axis`, `rotate`, `gyroscope`, `unique`, `vertical` +- **Synonyms**: swivel mouse, z rotation, gyroscope mouse, vertical rotation ### SkewMouse -**Description**: Skew distortion following cursor. Experimental angular distortion based on mouse position. -**Tags**: `skew`, `distortion`, `angle`, `experimental`, `warp`, `tilt` -**Synonyms**: skew mouse, distortion mouse, angle skew, warp mouse +- **Description**: Skew distortion following cursor. Experimental angular distortion based on mouse position. +- **Tags**: `skew`, `distortion`, `angle`, `experimental`, `warp`, `tilt` +- **Synonyms**: skew mouse, distortion mouse, angle skew, warp mouse ### BlurMouse -**Description**: Blur based on cursor distance. Focus/defocus effect depending on mouse proximity. -**Tags**: `blur`, `focus`, `distance`, `proximity`, `defocus`, `depth` -**Synonyms**: blur mouse, focus mouse, proximity blur, distance focus +- **Description**: Blur based on cursor distance. Focus/defocus effect depending on mouse proximity. +- **Tags**: `blur`, `focus`, `distance`, `proximity`, `defocus`, `depth` +- **Synonyms**: blur mouse, focus mouse, proximity blur, distance focus ### AiryMouse -**Description**: Floating/airy cursor response. Ethereal, light movement as if carried by air currents. -**Tags**: `airy`, `float`, `ethereal`, `light`, `gentle`, `drift`, `soft` -**Synonyms**: airy mouse, floating mouse, ethereal cursor, light follow, gentle drift +- **Description**: Floating/airy cursor response. Ethereal, light movement as if carried by air currents. +- **Tags**: `airy`, `float`, `ethereal`, `light`, `gentle`, `drift`, `soft` +- **Synonyms**: airy mouse, floating mouse, ethereal cursor, light follow, gentle drift ### BlobMouse -**Description**: Organic blob-like deformation. Experimental fluid shape distortion following cursor. -**Tags**: `blob`, `organic`, `fluid`, `deform`, `experimental`, `shape`, `morph` -**Synonyms**: blob mouse, organic deform, fluid mouse, shape morph, blob effect +- **Description**: Organic blob-like deformation. Experimental fluid shape distortion following cursor. +- **Tags**: `blob`, `organic`, `fluid`, `deform`, `experimental`, `shape`, `morph` +- **Synonyms**: blob mouse, organic deform, fluid mouse, shape morph, blob effect ### CustomMouse -**Description**: Configurable custom behavior. Flexible preset for custom mouse-driven transformations. -**Tags**: `custom`, `configurable`, `flexible`, `advanced`, `custom-behavior` -**Synonyms**: custom mouse, configurable mouse, flexible mouse effect, advanced mouse +- **Description**: Configurable custom behavior. Flexible preset for custom mouse-driven transformations. +- **Tags**: `custom`, `configurable`, `flexible`, `advanced`, `custom-behavior` +- **Synonyms**: custom mouse, configurable mouse, flexible mouse effect, advanced mouse ## Decision Guide diff --git a/packages/motion-presets/rules/presets/ongoing.md b/packages/motion-presets/rules/presets/ongoing.md index 138c32c9..1a0d6bda 100644 --- a/packages/motion-presets/rules/presets/ongoing.md +++ b/packages/motion-presets/rules/presets/ongoing.md @@ -48,87 +48,87 @@ continuous animation, looping animation, infinite animation, repeating animation ### Pulse -**Description**: Gentle scale oscillation, heartbeat-like rhythm. Shrinks and expands continuously. Subtle, universal attention indicator. -**Tags**: `pulse`, `scale`, `heartbeat`, `throb`, `attention`, `subtle`, `status`, `breathing` -**Synonyms**: pulse effect, heartbeat, throb, breathing, scale pulse, attention pulse, pulsing +- **Description**: Gentle scale oscillation, heartbeat-like rhythm. Shrinks and expands continuously. Subtle, universal attention indicator. +- **Tags**: `pulse`, `scale`, `heartbeat`, `throb`, `attention`, `subtle`, `status`, `breathing` +- **Synonyms**: pulse effect, heartbeat, throb, breathing, scale pulse, attention pulse, pulsing ### Bounce -**Description**: Vertical bouncing motion like a ball on trampoline. Playful, energetic, attention-grabbing continuous motion. -**Tags**: `bounce`, `vertical`, `movement`, `playful`, `energetic`, `jump`, `hop`, `spring` -**Synonyms**: bouncing, jumping, hopping, vertical bounce, continuous bounce, bouncy animation +- **Description**: Vertical bouncing motion like a ball on trampoline. Playful, energetic, attention-grabbing continuous motion. +- **Tags**: `bounce`, `vertical`, `movement`, `playful`, `energetic`, `jump`, `hop`, `spring` +- **Synonyms**: bouncing, jumping, hopping, vertical bounce, continuous bounce, bouncy animation ### Spin -**Description**: Continuous rotation around center. Like a wheel or loading spinner. Mechanical, precise circular motion. -**Tags**: `spin`, `rotate`, `loading`, `circular`, `wheel`, `continuous`, `mechanical` -**Synonyms**: spinning, rotating, rotation, circular motion, revolve, turn continuously +- **Description**: Continuous rotation around center. Like a wheel or loading spinner. Mechanical, precise circular motion. +- **Tags**: `spin`, `rotate`, `loading`, `circular`, `wheel`, `continuous`, `mechanical` +- **Synonyms**: spinning, rotating, rotation, circular motion, revolve, turn continuously ### Breathe -**Description**: Slow scale in/out like breathing rhythm. Calm, organic, meditative expansion and contraction. -**Tags**: `breathe`, `scale`, `slow`, `calm`, `organic`, `meditative`, `expansion`, `zen` -**Synonyms**: breathing animation, slow pulse, meditation, calm scale, organic rhythm +- **Description**: Slow scale in/out like breathing rhythm. Calm, organic, meditative expansion and contraction. +- **Tags**: `breathe`, `scale`, `slow`, `calm`, `organic`, `meditative`, `expansion`, `zen` +- **Synonyms**: breathing animation, slow pulse, meditation, calm scale, organic rhythm ### Flash -**Description**: Opacity pulsing/blinking effect. Attention, warning, notification indicator through visibility changes. -**Tags**: `flash`, `blink`, `opacity`, `attention`, `warning`, `notification`, `visibility` -**Synonyms**: flashing, blinking, blink animation, attention flash, warning blink +- **Description**: Opacity pulsing/blinking effect. Attention, warning, notification indicator through visibility changes. +- **Tags**: `flash`, `blink`, `opacity`, `attention`, `warning`, `notification`, `visibility` +- **Synonyms**: flashing, blinking, blink animation, attention flash, warning blink ### Swing -**Description**: Rotation oscillation like a pendulum. Back and forth pivoting motion, playful rhythmic movement. -**Tags**: `swing`, `pendulum`, `oscillation`, `rotation`, `pivot`, `rhythmic`, `back-forth` -**Synonyms**: swinging, pendulum motion, oscillating, pivot swing, back and forth +- **Description**: Rotation oscillation like a pendulum. Back and forth pivoting motion, playful rhythmic movement. +- **Tags**: `swing`, `pendulum`, `oscillation`, `rotation`, `pivot`, `rhythmic`, `back-forth` +- **Synonyms**: swinging, pendulum motion, oscillating, pivot swing, back and forth ### Wiggle -**Description**: Horizontal shake/wiggle motion. Side-to-side movement for attention, playful "notice me" effect. -**Tags**: `wiggle`, `shake`, `horizontal`, `attention`, `playful`, `notice`, `side-to-side` -**Synonyms**: wiggling, shaking, horizontal shake, side wiggle, shake animation +- **Description**: Horizontal shake/wiggle motion. Side-to-side movement for attention, playful "notice me" effect. +- **Tags**: `wiggle`, `shake`, `horizontal`, `attention`, `playful`, `notice`, `side-to-side` +- **Synonyms**: wiggling, shaking, horizontal shake, side wiggle, shake animation ### Flip -**Description**: Periodic 180° flips. Card-like rotation showing front/back, dramatic periodic turn. -**Tags**: `flip`, `rotation`, `180`, `card`, `periodic`, `turn`, `front-back` -**Synonyms**: flipping, card flip, periodic flip, turn animation, flip cycle +- **Description**: Periodic 180° flips. Card-like rotation showing front/back, dramatic periodic turn. +- **Tags**: `flip`, `rotation`, `180`, `card`, `periodic`, `turn`, `front-back` +- **Synonyms**: flipping, card flip, periodic flip, turn animation, flip cycle ### Fold -**Description**: 3D folding motion. Paper-like folding and unfolding, creative dimensional movement. -**Tags**: `fold`, `3d`, `paper`, `dimensional`, `creative`, `unfold` -**Synonyms**: folding, paper fold, 3d fold, origami motion, fold animation +- **Description**: 3D folding motion. Paper-like folding and unfolding, creative dimensional movement. +- **Tags**: `fold`, `3d`, `paper`, `dimensional`, `creative`, `unfold` +- **Synonyms**: folding, paper fold, 3d fold, origami motion, fold animation ### Jello -**Description**: Wobbly elastic deformation. Jiggly, bouncy distortion like gelatin wobbling. -**Tags**: `jello`, `wobble`, `elastic`, `jiggly`, `bouncy`, `gelatin`, `deform` -**Synonyms**: jello wobble, jiggly, elastic wobble, bouncy deform, gelatin shake +- **Description**: Wobbly elastic deformation. Jiggly, bouncy distortion like gelatin wobbling. +- **Tags**: `jello`, `wobble`, `elastic`, `jiggly`, `bouncy`, `gelatin`, `deform` +- **Synonyms**: jello wobble, jiggly, elastic wobble, bouncy deform, gelatin shake ### Rubber -**Description**: Elastic stretch effect. Springy stretching and snapping back, rubbery distortion. -**Tags**: `rubber`, `elastic`, `stretch`, `spring`, `snap`, `distortion` -**Synonyms**: rubber stretch, elastic animation, stretchy, springy, snap back +- **Description**: Elastic stretch effect. Springy stretching and snapping back, rubbery distortion. +- **Tags**: `rubber`, `elastic`, `stretch`, `spring`, `snap`, `distortion` +- **Synonyms**: rubber stretch, elastic animation, stretchy, springy, snap back ### Poke -**Description**: Quick scale bump like being tapped. Brief attention "boop" effect, momentary scale spike. -**Tags**: `poke`, `bump`, `tap`, `quick`, `attention`, `boop`, `spike` -**Synonyms**: poke effect, bump animation, tap, boop, attention tap, quick bump +- **Description**: Quick scale bump like being tapped. Brief attention "boop" effect, momentary scale spike. +- **Tags**: `poke`, `bump`, `tap`, `quick`, `attention`, `boop`, `spike` +- **Synonyms**: poke effect, bump animation, tap, boop, attention tap, quick bump ### Cross -**Description**: X-pattern diagonal movement. Unique geometric motion crossing diagonally. -**Tags**: `cross`, `diagonal`, `x-pattern`, `geometric`, `unique`, `movement` -**Synonyms**: cross movement, diagonal cross, x-pattern, crossing animation +- **Description**: X-pattern diagonal movement. Unique geometric motion crossing diagonally. +- **Tags**: `cross`, `diagonal`, `x-pattern`, `geometric`, `unique`, `movement` +- **Synonyms**: cross movement, diagonal cross, x-pattern, crossing animation ### DVD -**Description**: Corner-to-corner bounce (DVD screensaver). Nostalgic bouncing around container, retro effect. -**Tags**: `dvd`, `screensaver`, `corner`, `bounce`, `nostalgic`, `retro`, `container` -**Synonyms**: dvd bounce, screensaver, corner bounce, retro bounce, dvd logo +- **Description**: Corner-to-corner bounce (DVD screensaver). Nostalgic bouncing around container, retro effect. +- **Tags**: `dvd`, `screensaver`, `corner`, `bounce`, `nostalgic`, `retro`, `container` +- **Synonyms**: dvd bounce, screensaver, corner bounce, retro bounce, dvd logo ## Decision Guide diff --git a/packages/motion-presets/rules/presets/scroll.md b/packages/motion-presets/rules/presets/scroll.md index f76a72be..3a9263fc 100644 --- a/packages/motion-presets/rules/presets/scroll.md +++ b/packages/motion-presets/rules/presets/scroll.md @@ -58,117 +58,117 @@ scroll-driven animation, scroll-triggered effect, parallax effect, scroll reveal ### ParallaxScroll -**Description**: Element moves slower/faster than scroll, creating depth illusion. Like looking through a window where distant objects move slower. -**Tags**: `parallax`, `depth`, `layered`, `continuous`, `movement`, `distance`, `speed` -**Synonyms**: parallax effect, scroll parallax, depth scroll, layered scroll, differential scroll, scroll movement +- **Description**: Element moves slower/faster than scroll, creating depth illusion. Like looking through a window where distant objects move slower. +- **Tags**: `parallax`, `depth`, `layered`, `continuous`, `movement`, `distance`, `speed` +- **Synonyms**: parallax effect, scroll parallax, depth scroll, layered scroll, differential scroll, scroll movement ### FadeScroll -**Description**: Opacity transition tied to scroll position. Fade in on enter, fade out on exit. Smooth, cinematic content reveals. -**Tags**: `fade`, `opacity`, `reveal`, `in`, `out`, `transition`, `subtle` -**Synonyms**: scroll fade, fade on scroll, opacity scroll, scroll reveal, scroll disappear +- **Description**: Opacity transition tied to scroll position. Fade in on enter, fade out on exit. Smooth, cinematic content reveals. +- **Tags**: `fade`, `opacity`, `reveal`, `in`, `out`, `transition`, `subtle` +- **Synonyms**: scroll fade, fade on scroll, opacity scroll, scroll reveal, scroll disappear ### ArcScroll -**Description**: 3D tilt/rotation as user scrolls. Like a card tilting towards or away. Dramatic, cinematic depth effect. -**Tags**: `3d`, `arc`, `rotation`, `perspective`, `tilt`, `cinematic`, `dramatic` -**Synonyms**: scroll arc, 3d scroll, tilt scroll, rotation scroll, perspective scroll +- **Description**: 3D tilt/rotation as user scrolls. Like a card tilting towards or away. Dramatic, cinematic depth effect. +- **Tags**: `3d`, `arc`, `rotation`, `perspective`, `tilt`, `cinematic`, `dramatic` +- **Synonyms**: scroll arc, 3d scroll, tilt scroll, rotation scroll, perspective scroll ### BlurScroll -**Description**: Blur/unblur effect controlled by scroll position. Creates focus/defocus transitions tied to scroll. -**Tags**: `blur`, `focus`, `defocus`, `soft`, `transition`, `depth` -**Synonyms**: scroll blur, blur on scroll, focus scroll, defocus scroll, blur transition +- **Description**: Blur/unblur effect controlled by scroll position. Creates focus/defocus transitions tied to scroll. +- **Tags**: `blur`, `focus`, `defocus`, `soft`, `transition`, `depth` +- **Synonyms**: scroll blur, blur on scroll, focus scroll, defocus scroll, blur transition ### FlipScroll -**Description**: Full 3D card flip driven by scroll. Dramatic rotation revealing content as user scrolls. -**Tags**: `flip`, `3d`, `rotation`, `card`, `dramatic`, `turn`, `reveal` -**Synonyms**: scroll flip, 3d flip scroll, card flip scroll, flip on scroll +- **Description**: Full 3D card flip driven by scroll. Dramatic rotation revealing content as user scrolls. +- **Tags**: `flip`, `3d`, `rotation`, `card`, `dramatic`, `turn`, `reveal` +- **Synonyms**: scroll flip, 3d flip scroll, card flip scroll, flip on scroll ### GrowScroll -**Description**: Scale up as element enters viewport. Element grows larger tied to scroll progress. -**Tags**: `grow`, `scale`, `zoom`, `expand`, `size`, `enlarge`, `in` -**Synonyms**: scroll grow, scale scroll, zoom scroll, grow on scroll, expand scroll +- **Description**: Scale up as element enters viewport. Element grows larger tied to scroll progress. +- **Tags**: `grow`, `scale`, `zoom`, `expand`, `size`, `enlarge`, `in` +- **Synonyms**: scroll grow, scale scroll, zoom scroll, grow on scroll, expand scroll ### ShrinkScroll -**Description**: Scale down as element exits viewport. Element shrinks tied to scroll progress. -**Tags**: `shrink`, `scale`, `reduce`, `minimize`, `size`, `out` -**Synonyms**: scroll shrink, scale down scroll, shrink on scroll, minimize scroll +- **Description**: Scale down as element exits viewport. Element shrinks tied to scroll progress. +- **Tags**: `shrink`, `scale`, `reduce`, `minimize`, `size`, `out` +- **Synonyms**: scroll shrink, scale down scroll, shrink on scroll, minimize scroll ### MoveScroll -**Description**: General translation movement on scroll. Move element in any direction tied to scroll position. -**Tags**: `move`, `translate`, `position`, `movement`, `direction`, `shift` -**Synonyms**: scroll move, translate scroll, movement scroll, position scroll +- **Description**: General translation movement on scroll. Move element in any direction tied to scroll position. +- **Tags**: `move`, `translate`, `position`, `movement`, `direction`, `shift` +- **Synonyms**: scroll move, translate scroll, movement scroll, position scroll ### PanScroll -**Description**: Horizontal or vertical panning effect. Element slides across tied to scroll. -**Tags**: `pan`, `horizontal`, `vertical`, `slide`, `traverse`, `sweep` -**Synonyms**: scroll pan, pan on scroll, horizontal scroll, sliding scroll +- **Description**: Horizontal or vertical panning effect. Element slides across tied to scroll. +- **Tags**: `pan`, `horizontal`, `vertical`, `slide`, `traverse`, `sweep` +- **Synonyms**: scroll pan, pan on scroll, horizontal scroll, sliding scroll ### RevealScroll -**Description**: Clip-based directional reveal on scroll. Content unveils progressively as user scrolls. -**Tags**: `reveal`, `clip`, `mask`, `directional`, `unveil`, `progressive`, `wipe` -**Synonyms**: scroll reveal, clip scroll, wipe scroll, unveil scroll, mask reveal scroll +- **Description**: Clip-based directional reveal on scroll. Content unveils progressively as user scrolls. +- **Tags**: `reveal`, `clip`, `mask`, `directional`, `unveil`, `progressive`, `wipe` +- **Synonyms**: scroll reveal, clip scroll, wipe scroll, unveil scroll, mask reveal scroll ### ShapeScroll -**Description**: Shape mask reveal controlled by scroll. Geometric shapes expanding/contracting on scroll. -**Tags**: `shape`, `mask`, `geometric`, `circle`, `expand`, `contract` -**Synonyms**: shape scroll, mask scroll, geometric reveal scroll, shape reveal +- **Description**: Shape mask reveal controlled by scroll. Geometric shapes expanding/contracting on scroll. +- **Tags**: `shape`, `mask`, `geometric`, `circle`, `expand`, `contract` +- **Synonyms**: shape scroll, mask scroll, geometric reveal scroll, shape reveal ### ShuttersScroll -**Description**: Venetian blind strips revealing on scroll. Segmented progressive reveal tied to scroll. -**Tags**: `shutters`, `blinds`, `strips`, `segmented`, `progressive`, `venetian` -**Synonyms**: shutters scroll, blind scroll, strip reveal scroll, venetian scroll +- **Description**: Venetian blind strips revealing on scroll. Segmented progressive reveal tied to scroll. +- **Tags**: `shutters`, `blinds`, `strips`, `segmented`, `progressive`, `venetian` +- **Synonyms**: shutters scroll, blind scroll, strip reveal scroll, venetian scroll ### SkewPanScroll -**Description**: Panning with skew distortion effect. Movement plus angular distortion on scroll. -**Tags**: `skew`, `pan`, `distortion`, `angle`, `movement`, `warp` -**Synonyms**: skew scroll, skew pan, distortion scroll, angled pan scroll +- **Description**: Panning with skew distortion effect. Movement plus angular distortion on scroll. +- **Tags**: `skew`, `pan`, `distortion`, `angle`, `movement`, `warp` +- **Synonyms**: skew scroll, skew pan, distortion scroll, angled pan scroll ### SlideScroll -**Description**: Slide movement tied to scroll position. Directional sliding as user scrolls. -**Tags**: `slide`, `move`, `directional`, `translate`, `shift` -**Synonyms**: scroll slide, slide on scroll, directional slide scroll +- **Description**: Slide movement tied to scroll position. Directional sliding as user scrolls. +- **Tags**: `slide`, `move`, `directional`, `translate`, `shift` +- **Synonyms**: scroll slide, slide on scroll, directional slide scroll ### Spin3dScroll -**Description**: 3D rotation around axis on scroll. Element rotates in 3D space as user scrolls. -**Tags**: `spin`, `3d`, `rotation`, `axis`, `revolve`, `orbit` -**Synonyms**: 3d spin scroll, rotation scroll, spin on scroll, 3d rotate scroll +- **Description**: 3D rotation around axis on scroll. Element rotates in 3D space as user scrolls. +- **Tags**: `spin`, `3d`, `rotation`, `axis`, `revolve`, `orbit` +- **Synonyms**: 3d spin scroll, rotation scroll, spin on scroll, 3d rotate scroll ### SpinScroll -**Description**: 2D rotation driven by scroll. Element spins flat as user scrolls. -**Tags**: `spin`, `rotate`, `2d`, `turn`, `circular` -**Synonyms**: scroll spin, rotate scroll, 2d spin scroll, turning scroll +- **Description**: 2D rotation driven by scroll. Element spins flat as user scrolls. +- **Tags**: `spin`, `rotate`, `2d`, `turn`, `circular` +- **Synonyms**: scroll spin, rotate scroll, 2d spin scroll, turning scroll ### StretchScroll -**Description**: Stretch/squeeze deformation on scroll. Element distorts proportionally tied to scroll. -**Tags**: `stretch`, `squeeze`, `deform`, `distort`, `elastic`, `proportion` -**Synonyms**: stretch scroll, squeeze scroll, deform scroll, elastic scroll +- **Description**: Stretch/squeeze deformation on scroll. Element distorts proportionally tied to scroll. +- **Tags**: `stretch`, `squeeze`, `deform`, `distort`, `elastic`, `proportion` +- **Synonyms**: stretch scroll, squeeze scroll, deform scroll, elastic scroll ### TiltScroll -**Description**: 3D tilt effect as user scrolls. Subtle perspective shift tied to scroll position. -**Tags**: `tilt`, `3d`, `perspective`, `angle`, `subtle`, `depth` -**Synonyms**: scroll tilt, 3d tilt scroll, perspective scroll, angle scroll +- **Description**: 3D tilt effect as user scrolls. Subtle perspective shift tied to scroll position. +- **Tags**: `tilt`, `3d`, `perspective`, `angle`, `subtle`, `depth` +- **Synonyms**: scroll tilt, 3d tilt scroll, perspective scroll, angle scroll ### TurnScroll -**Description**: Corner-pivot 3D rotation on scroll. Complex rotation with pivot point on scroll. -**Tags**: `turn`, `3d`, `corner`, `pivot`, `rotation`, `complex` -**Synonyms**: turn scroll, corner turn scroll, pivot scroll, 3d turn scroll +- **Description**: Corner-pivot 3D rotation on scroll. Complex rotation with pivot point on scroll. +- **Tags**: `turn`, `3d`, `corner`, `pivot`, `rotation`, `complex` +- **Synonyms**: turn scroll, corner turn scroll, pivot scroll, 3d turn scroll ## Decision Guide From a911e5e6c7825d0b40fa1d3c343c3d103bbfa18d Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Wed, 28 Jan 2026 14:03:16 +0200 Subject: [PATCH 07/20] Add power-controlled params documentation and update PLAN.md as source of truth - Add power-controlled params notes to all presets (Entrance, Scroll, Ongoing, Mouse) - Update PLAN.md with complete power mappings for regeneration - Consolidate documentation structure with presets-reference.md --- packages/motion-presets/rules/presets/PLAN.md | 624 ++----- .../rules/presets/background-scroll.md | 179 +- .../presets/background-scroll/bg-fade.md | 66 - .../presets/background-scroll/bg-parallax.md | 60 - .../presets/background-scroll/bg-zoom.md | 65 - .../motion-presets/rules/presets/entrance.md | 256 +-- .../rules/presets/entrance/arc-in.md | 77 - .../rules/presets/entrance/bounce-in.md | 76 - .../rules/presets/entrance/fade-in.md | 62 - .../motion-presets/rules/presets/mouse.md | 185 +- .../rules/presets/mouse/bounce-mouse.md | 70 - .../rules/presets/mouse/tilt-3d-mouse.md | 83 - .../rules/presets/mouse/track-mouse.md | 87 - .../motion-presets/rules/presets/ongoing.md | 187 +- .../rules/presets/ongoing/bounce.md | 71 - .../rules/presets/ongoing/pulse.md | 71 - .../rules/presets/ongoing/spin.md | 73 - .../rules/presets/presets-reference.md | 1635 +++++++++++++++++ .../motion-presets/rules/presets/scroll.md | 237 +-- .../rules/presets/scroll/arc-scroll.md | 73 - .../rules/presets/scroll/fade-scroll.md | 74 - .../rules/presets/scroll/parallax-scroll.md | 74 - 22 files changed, 1933 insertions(+), 2452 deletions(-) delete mode 100644 packages/motion-presets/rules/presets/background-scroll/bg-fade.md delete mode 100644 packages/motion-presets/rules/presets/background-scroll/bg-parallax.md delete mode 100644 packages/motion-presets/rules/presets/background-scroll/bg-zoom.md delete mode 100644 packages/motion-presets/rules/presets/entrance/arc-in.md delete mode 100644 packages/motion-presets/rules/presets/entrance/bounce-in.md delete mode 100644 packages/motion-presets/rules/presets/entrance/fade-in.md delete mode 100644 packages/motion-presets/rules/presets/mouse/bounce-mouse.md delete mode 100644 packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md delete mode 100644 packages/motion-presets/rules/presets/mouse/track-mouse.md delete mode 100644 packages/motion-presets/rules/presets/ongoing/bounce.md delete mode 100644 packages/motion-presets/rules/presets/ongoing/pulse.md delete mode 100644 packages/motion-presets/rules/presets/ongoing/spin.md create mode 100644 packages/motion-presets/rules/presets/presets-reference.md delete mode 100644 packages/motion-presets/rules/presets/scroll/arc-scroll.md delete mode 100644 packages/motion-presets/rules/presets/scroll/fade-scroll.md delete mode 100644 packages/motion-presets/rules/presets/scroll/parallax-scroll.md diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 5b78a7db..7194664d 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -1,532 +1,178 @@ --- -name: Generate LLM Preset Rules -overview: Create two-level rule files (category + preset) optimized for LLM decision flow. -todos: - - id: restructure - content: 'Restructure: Create category files, update existing preset files to new format' - status: pending - - id: category-entrance - content: 'Create entrance.md category file with decision guide' - status: pending - - id: category-scroll - content: 'Create scroll.md category file with decision guide' - status: pending - - id: category-ongoing - content: 'Create ongoing.md category file with decision guide' - status: pending - - id: category-mouse - content: 'Create mouse.md category file with decision guide' - status: pending - - id: category-background - content: 'Create background-scroll.md category file with decision guide' - status: pending - - id: update-presets - content: 'Update existing preset files to simplified format (remove when-to-use, alternatives)' - status: pending - - id: review - content: 'Review new structure with user' - status: pending - - id: generate-remaining - content: 'Generate remaining preset files' - status: pending +name: LLM Preset Rules +overview: Consolidated single-file reference with lightweight trigger entry points. +status: completed --- -# Generate LLM Rules for Motion Presets +# LLM Rules for Motion Presets -## Execution Phases +This file serves as the **source of truth** for regenerating `presets-reference.md` when presets change. -### Phase 1: Create Category Files (Current) +## Structure -Create 5 category-level files with decision guides: - -- `entrance.md` - Decision guide for 24 entrance presets -- `scroll.md` - Decision guide for 20 scroll presets -- `ongoing.md` - Decision guide for 14 ongoing presets -- `mouse.md` - Decision guide for 13 mouse presets -- `background-scroll.md` - Decision guide for 12 background-scroll presets - -### Phase 2: Update Existing Preset Files - -Update the 15 pilot preset files to the simplified format: - -- Remove: When to Use, When NOT to Use, Related Presets, Decision Hints -- Keep: Visual Description, Parameters, Examples - -### Phase 3: Review & Complete - -- Review new structure with user -- Generate remaining ~70 preset files - ---- - -## Structure Overview - -**Two-level hierarchy optimized for LLM decision flow:** - -### Level 1: Category Files (Decision Layer) - -- `rules/presets/entrance.md` - When to use entrance, comparison of all 24 presets -- `rules/presets/scroll.md` - When to use scroll, comparison of all 20 presets -- `rules/presets/ongoing.md` - When to use ongoing, comparison of all 14 presets -- `rules/presets/mouse.md` - When to use mouse, comparison of all 13 presets -- `rules/presets/background-scroll.md` - When to use background-scroll, comparison of all 12 presets - -### Level 2: Preset Files (Detail Layer) - -- `rules/presets/entrance/arc-in.md` - Visual description, parameters, examples -- `rules/presets/entrance/fade-in.md` - Visual description, parameters, examples -- etc. - -**Why this structure?** -LLM decision flow is a waterfall - it won't read all preset descriptions before selecting. It needs: - -1. First: "Which category?" → Read category file -2. Then: "Which preset?" → Use decision guide in category file -3. Finally: "How to configure?" → Read specific preset file - -**LLM Decision Checklist:** - -- [ ] Category selected based on trigger type (page load, scroll, continuous, mouse, background) -- [ ] Preset selected using decision guide (by tone, use case, or element type) -- [ ] Parameters configured using preset file details - -## Category File Format - -Each category file guides the LLM to select the right preset. - ---- - -### Category File Sections - -#### 1. Header (YAML frontmatter) - -```yaml -name: Entrance Animations -category: entrance -tags: [appear, reveal, enter, load, show, intro, page-load, modal, popup] -``` - -Tags help LLM match user intent via semantic search. - -#### 2. Description & Synonyms - -Verbose overview of the category with alternative phrasings: - -```markdown -## Description - -Entrance animations bring elements into view for the first time. They create the initial -impression and set the tone for user interaction. These are one-shot animations that play -once when an element first appears. - -## Synonyms - -appear animation, reveal effect, intro animation, show animation, enter animation, -page load animation, element appearance, fade in effect, loading animation -``` - -#### 3. When to Use This Category - -When should an LLM choose this category over others: - -```markdown -## When to Use Entrance Animations - -- Elements appearing for the first time on page load -- Modal/overlay/popup appearances -- Content revealing after user action (click, tab switch) -- Elements entering viewport (triggered once, not scroll-driven) -- First-time visibility of lazy-loaded content - -## When NOT to Use - -- Scroll-driven reveals → use Scroll animations -- Continuous/looping animations → use Ongoing animations -- Mouse-reactive elements → use Mouse animations -- Background media → use Background Scroll animations -``` - -#### 4. Accessibility Considerations - -Important for inclusive design: - -```markdown -## Accessibility Considerations - -- **Respect prefers-reduced-motion**: Use FadeIn as fallback or disable animations entirely -- **Duration guidelines**: Keep under 500ms for functional UI, up to 1200ms for decorative -- **Avoid vestibular triggers**: Limit large-scale movement, spinning, parallax for motion-sensitive users -- **Focus management**: Ensure animated elements don't interfere with keyboard focus order -- **Screen readers**: Animations are visual-only; ensure content is accessible without them -``` - -#### 5. Preset List with Tags and Synonyms - -Each preset as a block with description, tags, and synonyms for LLM matching: - -```markdown -## Available Presets - -### FadeIn - -- **Description**: Gradual opacity transition from invisible to visible. Universal, subtle, accessibility-safe. -- **Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear` -- **Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance - -### ArcIn - -- **Description**: 3D curved swing like a door opening. Dramatic, cinematic, creates depth. -- **Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium` -- **Synonyms**: arc entrance, curved reveal, swing in, cinematic entrance, perspective reveal - -... -``` - -This format is optimal for LLM intent matching - tags and synonyms are explicitly labeled and grouped with each preset. - -#### 6. Decision Guide - -Help LLM choose between presets: - -```markdown -## Decision Guide - -### By Tone - -- **Subtle/Professional**: FadeIn, BlurIn, SlideIn -- **Dramatic/Cinematic**: ArcIn, FlipIn, TurnIn -- **Playful/Energetic**: BounceIn, SpinIn, PunchIn - -### By Use Case - -- **Hero sections**: ArcIn, ExpandIn, GrowIn -- **Modals/Overlays**: FadeIn, DropIn -- **List items**: FadeIn, SlideIn (with stagger) -- **Notifications**: BounceIn, PunchIn - -### Reduced Motion Alternatives - -Always provide a reduced-motion fallback: - -- Complex animations → FadeIn -- Movement-based → FadeIn or no animation -- 3D/Spinning → FadeIn - -### Parallels in Other Categories - -| Entrance | Scroll Equivalent | Mouse Equivalent | -| -------- | ----------------- | ---------------- | -| ArcIn | ArcScroll | - | -| FadeIn | FadeScroll | - | -| SpinIn | SpinScroll | SpinMouse | -``` - ---- - -### Preset File Sections - -Each preset file contains the details needed AFTER the LLM has decided to use this preset. -Since category files handle decision-making, preset files can be more verbose about implementation details. - -#### 1. Preset Header (YAML frontmatter) - -```yaml -name: ArcIn -category: entrance -``` - -#### 2. Visual Description (Human-written, verbose) - -**Describe what the user SEES in plain, non-technical language.** Be detailed and use analogies. - -**DO describe:** - -- What the element looks like at the start, middle, and end -- The path or direction of movement -- The overall feeling (smooth, bouncy, dramatic) -- Real-world analogies (like a door opening, a ball bouncing, etc.) -- How opacity, scale, rotation, and position change - -**DO NOT reference:** - -- CSS properties (translateY, perspective, rotateX) -- Keyframe percentages or offsets -- Easing function names (unless explaining power/easing parameter) -- Internal implementation details - -**Example:** - -> Element swings into view along a curved path, like a door opening towards you. At the start, -> the element is invisible and tilted away (as if rotated back into the screen). As the animation -> plays, it gradually rotates forward while simultaneously fading in. The element follows an arc -> trajectory rather than moving in a straight line, creating a sense of depth and dimension. -> By the end, it settles flat and fully visible in its final position. The motion feels cinematic -> and dramatic, best suited for hero elements that need to make an impression. - -#### 3. Parameters (detailed) - -**Use TypeScript notation.** Pull min/max/step/enum from `@wix/effects-kit`. -Include comprehensive parameter impact notes explaining what each value does visually. - -```typescript -interface ArcIn { - direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 -} +```text +rules/presets/ +├── presets-reference.md # Comprehensive reference (all presets, all info) +├── entrance.md # Lightweight trigger entry point +├── scroll.md # Lightweight trigger entry point +├── ongoing.md # Lightweight trigger entry point +├── mouse.md # Lightweight trigger entry point +└── background-scroll.md # Lightweight trigger entry point ``` -**Parameter Impact (verbose):** +## Key Constraints -- `direction`: Controls which edge the element appears to swing from - - `top`: Element tilts forward (rotates on X-axis), appears to fall into place from above - - `bottom`: Element tilts backward, appears to rise up from below - - `left`: Element tilts sideways (rotates on Y-axis), swings in from the left - - `right`: Element tilts opposite direction, swings in from the right -- `power`: Controls how dramatic the rotation and arc appear - - `soft`: Subtle 15° rotation, gentle arc - good for supporting content - - `medium`: Balanced 30° rotation - the sweet spot for most uses - - `hard`: Dramatic 45° rotation with slight overshoot - attention-grabbing -- `duration`: How long the animation takes (1200ms default is cinematic, 600ms is snappy) -- `delay`: Wait time before animation starts (useful for staggered sequences) +### Trigger Mechanisms -#### 4. Best Practices +| Trigger | Mechanism | Notes | +| --------- | ----------- | ------- | +| entrance | `viewEnter` (intersection observer) | Plays once when element enters viewport | +| scroll | Scroll position binding | Tied to scroll progress (0-100%) | +| ongoing | Continuous loop | Runs indefinitely until stopped | +| mouse | Pointer position binding | Desktop only, real-time response | +| background-scroll | Scroll position for CSS backgrounds | Specifically for background media | -Tips for effective use of this specific preset: - -```markdown -## Best Practices +**Important:** Entrance animations only support the `viewEnter` trigger natively. For click, toggle, or other event-based triggers, implement triggering logic separately. -- Use on single focal elements, not multiple simultaneous items -- Combine with stagger delay for sequential reveals -- Consider `power: 'soft'` for mobile devices -- Pair with complementary exit animation if element will be removed -``` +### Combining Animations -#### 5. Examples (with context) +| Combination | Support | +| ------------- | --------- | +| Entrance + Ongoing | Single element (native support) | +| Entrance + Mouse | Requires nested containers | +| Entrance + Scroll | Requires nested containers | +| Scroll + Mouse | Requires nested containers | +| Any other combination | Requires multiple containers | -Include examples with explanatory comments: +### Common Parameters -```typescript -// Basic usage - element swings in from bottom -{ type: 'ArcIn', direction: 'bottom' } +**All Entrance presets:** -// Hero section - dramatic entrance from side -{ type: 'ArcIn', direction: 'left', power: 'hard' } +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) -// Subtle supporting content -{ type: 'ArcIn', direction: 'top', power: 'soft', duration: 800 } +**Most Scroll presets:** -// Staggered cards (apply to each with increasing delay) -{ type: 'ArcIn', direction: 'bottom', delay: 0 } // Card 1 -{ type: 'ArcIn', direction: 'bottom', delay: 100 } // Card 2 -{ type: 'ArcIn', direction: 'bottom', delay: 200 } // Card 3 -``` +- `range`: 'in' | 'out' | 'continuous' +- `start`: 0-100% +- `end`: 0-100% -**Note:** "When to use", "When not to use", "Alternatives", and "Decision hints" remain in the **category file**. +**Most Ongoing presets:** ---- +- `duration`: 100-4000ms +- `delay`: 0-8000ms --- -## Sample Files +## Power Parameter Mappings + +`power: 'soft' | 'medium' | 'hard'` **overrides** fine-grained parameters when set. + +### Entrance Presets + +| Preset | Power Controls | soft | medium | hard | +| -------- | --------------- | ------ | -------- | ------ | +| ArcIn | easing curve | subtle | balanced | dramatic | +| BlurIn | blur | 6px | 25px | 50px | +| BounceIn | distanceFactor | 1 | 2 | 3 | +| DropIn | scale, easing | 1.2/cubicInOut | 1.6/quintInOut | 2/backOut | +| ExpandIn | scale, easing | subtle | balanced | dramatic | +| FlipIn | initialRotate | 45deg | 90deg | 270deg | +| FoldIn | initialRotate | 35deg | 60deg | 90deg | +| GlideIn | easing curve | subtle | balanced | dramatic | +| GlitchIn | glitch intensity | subtle | balanced | dramatic | +| GrowIn | scale, easing | subtle | balanced | dramatic | +| PunchIn | easing | sineIn | quadIn | quintIn | +| ShuttersIn | easing curve | subtle | balanced | dramatic | +| SlideIn | easing curve | subtle | balanced | dramatic | +| SpinIn | easing curve | subtle | balanced | dramatic | + +### Scroll Presets + +| Preset | Power Controls | soft | medium | hard | +| -------- | --------------- | ------ | -------- | ------ | +| BlurScroll | blur | 6px | 25px | 50px | +| FlipScroll | rotate | 60deg | 120deg | 420deg | +| GrowScroll | scaleFrom/scaleTo | 0.8-1.2 | 0.3-1.7 | 0-4 | +| MoveScroll | distance | 150px | 400px | 800px | +| ShapeScroll | clipPath intensity | varies by shape | | | +| ShrinkScroll | scaleFrom/scaleTo | 1.2-0.8 | 1.7-0.3 | 3.5-0 | +| SkewPanScroll | skew | 10deg | 17deg | 24deg | +| Spin3dScroll | rotationZ/travelY | 45/0 | 100/0.5 | 200/1 | +| SpinScroll | scale | 1 | 0.7 | 0.4 | +| StretchScroll | scaleX/scaleY | 0.8/1.2 | 0.6/1.5 | 0.4/2 | +| TiltScroll | distance | 0 | 0.5 | 1 | +| TurnScroll | scaleFrom/scaleTo | 1/1 | 0.7/1.3 | 0.4/1.6 | + +### Ongoing Presets + +| Preset | Power Controls | soft | medium | hard | +| -------- | --------------- | ------ | -------- | ------ | +| Bounce | bounceFactor | 1 | 2 | 3 | +| Flip | easing curve | subtle | balanced | dramatic | +| Fold | angle | 15deg | 30deg | 45deg | +| Jello | jelloFactor | 1 | 2 | 4 | +| Poke | pokeFactor | 1 | 2 | 4 | +| Pulse | pulseOffset | 0 | 0.06 | 0.12 | +| Rubber | rubberOffset | 0 | 0.05 | 0.1 | +| Spin | easing curve | linear | eased | bouncy | +| Swing | swing angle | 20deg | 40deg | 60deg | +| Wiggle | wiggleFactor | 1 | 2 | 4 | + +### Mouse Presets + +| Preset | Power Controls | soft | medium | hard | +| -------- | --------------- | ------ | -------- | ------ | +| AiryMouse | angle | 10deg | 50deg | 85deg | +| BlobMouse | scale | 1.2 | 1.6 | 2.4 | +| BlurMouse | angle/scale | 0/1 | 25/0.7 | 65/0.25 | +| BounceMouse | spring easing | subtle | balanced | dramatic | +| ScaleMouse | scale (varies by direction) | down: 0.85, up: 1.2 | down: 0.5, up: 1.6 | down: 0, up: 2.4 | +| SkewMouse | angle | 10deg | 20deg | 45deg | +| SpinMouse | rotation intensity | subtle | balanced | dramatic | +| SwivelMouse | angle/perspective | 25/1000 | 50/700 | 85/300 | +| Tilt3DMouse | angle/perspective | 25/1000 | 50/500 | 85/200 | +| Track3DMouse | angle/perspective | 25/1000 | 50/500 | 85/333 | +| TrackMouse | easing | linear | easeOut | hardBackOut | -### Sample Category File: entrance.md - -```markdown --- -name: Entrance Animations -category: entrance ---- - -# Entrance Animations - -## When to Use Entrance Animations - -- Elements appearing for the first time on page load -- Modal/overlay appearances -- Content revealing after user action -- Triggered once (not continuous or scroll-driven) - -## Available Presets - -### FadeIn - -- **Description**: Gradual opacity transition from invisible to visible. Universal, subtle, accessibility-safe. -- **Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear` -- **Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance - -### ArcIn - -- **Description**: 3D curved swing like a door opening. Dramatic, cinematic, creates depth. -- **Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium` -- **Synonyms**: arc entrance, curved reveal, swing in, cinematic entrance, perspective reveal - -### BounceIn - -- **Description**: Playful bouncing entrance with spring physics. Energetic, fun, attention-grabbing. -- **Tags**: `bounce`, `spring`, `playful`, `energetic`, `fun`, `attention` -- **Synonyms**: bounce in, spring entrance, playful reveal, elastic entrance - -### SlideIn - -- **Description**: Straight movement from direction. Clean, professional, versatile. -- **Tags**: `slide`, `move`, `direction`, `clean`, `professional`, `versatile` -- **Synonyms**: slide in, move in, glide entrance, directional reveal - -... -## Decision Guide +## Preset Entry Format -### By Tone - -- **Subtle/Professional**: FadeIn, BlurIn, SlideIn -- **Dramatic/Cinematic**: ArcIn, FlipIn, TurnIn -- **Playful/Energetic**: BounceIn, SpinIn, PunchIn - -### By Use Case - -- **Hero sections**: ArcIn, ExpandIn, GrowIn -- **Modals/Overlays**: FadeIn, DropIn -- **List items (staggered)**: FadeIn, SlideIn -- **Notifications/Badges**: BounceIn, PunchIn - -### Parallels in Other Categories - -| Entrance | Scroll | Mouse | -| -------- | -------------- | ---------- | -| ArcIn | ArcScroll | - | -| FadeIn | FadeScroll | - | -| SpinIn | SpinScroll | SpinMouse | -| - | ParallaxScroll | TrackMouse | -``` - ---- - -### Sample Preset File: entrance/arc-in.md +For each preset in presets-reference.md: ```markdown ---- -name: ArcIn -category: entrance ---- - -# ArcIn +#### PresetName -## Visual Description +Visual: [1-2 sentences describing what user SEES] -Element swings into view along a curved path, like a door opening towards you. -It starts tilted away and gradually flattens as it settles into place. -Fades in while moving. The effect feels dramatic and cinematic. +Parameters: +- `param1`: type/range (default: value) +- `param2`: type/range (default: value) +- `power`: soft | medium | hard (if supported) -## Parameters +**When `power` is set:** overrides `paramX` (soft=value, medium=value, hard=value) \`\`\`typescript -interface ArcIn { -direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' -power?: 'soft' | 'medium' | 'hard'; // default: 'medium' -duration?: number; // min: 0, max: 4000, default: 1200 -delay?: number; // min: 0, max: 8000, default: 0 -} -\`\`\` - -**Parameter Impact:** - -- `direction`: top/bottom tilts forward/back, left/right tilts sideways -- `power`: soft = subtle, medium = noticeable, hard = dramatic - -## Examples - -\`\`\`typescript -// Basic -{ type: 'ArcIn', direction: 'bottom' } - -// Side entry (tilts on different axis) -{ type: 'ArcIn', direction: 'left' } +{ type: 'PresetName', param1: 'value' } \`\`\` ``` --- -## File Organization - -```text -rules/presets/ -├── README.md # Master index -├── entrance.md # Category: when to use, decision guide -├── scroll.md # Category: when to use, decision guide -├── ongoing.md # Category: when to use, decision guide -├── mouse.md # Category: when to use, decision guide -├── background-scroll.md # Category: when to use, decision guide -├── entrance/ # Preset details (24 files) -│ ├── fade-in.md -│ ├── arc-in.md -│ └── ... -├── scroll/ # Preset details (20 files) -│ ├── parallax-scroll.md -│ └── ... -├── ongoing/ # Preset details (14 files) -│ ├── pulse.md -│ └── ... -├── mouse/ # Preset details (13 files) -│ ├── tilt-3d-mouse.md -│ └── ... -└── background-scroll/ # Preset details (12 files) - ├── bg-parallax.md - └── ... -``` - ---- - -## Implementation Notes - -### Category Files (Verbose) - -1. **Header**: Include tags for semantic search matching -2. **Description & Synonyms**: Verbose overview with alternative phrasings -3. **When to Use / When NOT to Use**: Clear guidance on category selection -4. **Accessibility Considerations**: Reduced motion, vestibular safety, duration guidelines -5. **Preset List**: Description + Tags + Synonyms per preset for LLM intent matching -6. **Decision Guide**: Group by tone, use case, reduced-motion alternatives, cross-category parallels - -### Preset Files (Verbose) - -1. **Visual Description**: Detailed, use analogies, describe start/middle/end states -2. **Parameters**: TypeScript notation with comprehensive impact notes for each value -3. **Best Practices**: Tips specific to this preset -4. **Examples**: Multiple examples with explanatory comments, including stagger patterns - -### Data Sources - -- **Types**: `motion-presets/src/types.ts` -- **Constraints**: `effects-kit/src/effects/{category}/{preset}.ts` -- **Base params**: `effects-kit/src/effects/baseParams.ts` - -### Validation Checklist - -Before finalizing each preset file, verify: - -- [ ] Parameter defaults match source in `effects-kit` -- [ ] Min/max/step values are accurate -- [ ] Enum options (direction, power, easing) match TypeScript types -- [ ] Direction type is correct (FourDirections, FiveDirections, EightDirections) -- [ ] Easing exclusions noted for clipped animations - -### Notes on Parameter Subsets - -- Direction types vary: FourDirections, FiveDirections (adds center), EightDirections (adds diagonals) -- Clipped animations (ShapeIn, RevealIn, ShuttersIn, WinkIn) exclude back easings - -### Accessibility Guidelines +## Data Sources -**Must include in every category file:** +To regenerate presets-reference.md: -- [ ] `prefers-reduced-motion` media query support mentioned -- [ ] Reduced-motion fallback specified (typically FadeIn or no animation) -- [ ] Vestibular trigger warnings for: spinning, parallax, large-scale movement, 3D transforms +1. **Preset list**: `motion-presets/src/types.ts` - EntranceAnimation, ScrollAnimation, OngoingAnimation, MouseAnimation, BackgroundScrollAnimation unions +2. **Parameter constraints**: `effects-kit/src/effects/{category}/{preset}.ts` - min/max/step/defaults +3. **Power mappings**: This file (PLAN.md) - see tables above +4. **Base params**: `effects-kit/src/effects/baseParams.ts` -**Must include in every preset file:** +## Regeneration Steps -- [ ] Reduced-motion alternative noted if preset has vestibular triggers -- [ ] Duration recommendation (functional UI: <500ms, decorative: <1200ms) +1. Read preset list from types.ts +2. For each preset, get params from effects-kit +3. Apply power mappings from this file +4. Generate using preset entry format above +5. Organize by trigger category diff --git a/packages/motion-presets/rules/presets/background-scroll.md b/packages/motion-presets/rules/presets/background-scroll.md index 3ae8678a..85ba7a3b 100644 --- a/packages/motion-presets/rules/presets/background-scroll.md +++ b/packages/motion-presets/rules/presets/background-scroll.md @@ -1,168 +1,51 @@ --- name: Background Scroll Animations -category: backgroundScroll -tags: [background, bg, scroll, section, hero, media, image, video, fullwidth, cinematic] +trigger: backgroundScroll --- # Background Scroll Animations -## Description +Scroll animations specifically for CSS background images/videos. -Background Scroll animations are specifically designed for animating background media (images and videos) in response to scroll position. They're optimized for full-width section backgrounds and create immersive, cinematic effects as users scroll through a page. +## When to Use -These differ from regular Scroll animations in that they target the background layer of a container rather than the element itself. They're perfect for hero sections, full-bleed images, and creating depth between content and backgrounds. +- Hero sections with background depth +- Full-width section backgrounds +- Cinematic storytelling +- Section transitions -## Synonyms +## When NOT to Use -background animation, bg scroll effect, background parallax, section background, hero background, scroll background, media background animation, full-width background, background reveal, cinematic background - -## When to Use Background Scroll Animations - -- **Hero sections**: Landing page heroes with depth/movement -- **Full-width section backgrounds**: Sections with background images/videos -- **Cinematic storytelling**: Narrative pages with immersive backgrounds -- **Portfolio/Photography**: Showcasing images with scroll-driven effects -- **Section transitions**: Visual interest between content sections -- **Depth/Layering**: Creating separation between background and content - -## When NOT to Use Background Scroll Animations - -- **Regular content elements** → use Scroll animations instead -- **Non-media backgrounds** → color backgrounds don't benefit from these -- **Mobile with performance concerns** → background effects are heavy; test carefully -- **Text-heavy sections** → effects may distract from reading -- **Multiple animated backgrounds** → performance and visual overload -- **Small background areas** → effects are less noticeable, not worth the cost - -## Accessibility Considerations - -- **Respect `prefers-reduced-motion`**: Disable all background scroll animations or use only subtle BgFade -- **Vestibular triggers**: BgParallax, BgZoom, BgRotate, and BgFake3D can trigger motion sickness. These effects are particularly problematic because they affect large areas of the screen -- **Performance on low-end devices**: Background animations are computationally expensive. Provide graceful degradation -- **Content readability**: Ensure text overlaying animated backgrounds remains readable throughout the scroll range -- **Contrast maintenance**: Animated backgrounds shouldn't cause text contrast to drop below WCAG requirements -- **Video backgrounds**: If using video, ensure it doesn't autoplay with sound and provide pause controls +- Regular content elements → see [Scroll](presets-reference.md#scroll) +- Non-media backgrounds (solid colors) +- Multiple animated backgrounds +- Mobile with performance concerns ## Available Presets -### BgParallax - -- **Description**: Background moves slower than scroll creating depth illusion. Like background is further away than foreground content. -- **Tags**: `parallax`, `depth`, `movement`, `slow`, `layer`, `distance`, `immersive` -- **Synonyms**: background parallax, bg parallax, background scroll, parallax background, depth background - -### BgZoom - -- **Description**: Background zooms in/out as user scrolls. Cinematic dolly-like effect, camera moving towards/away. -- **Tags**: `zoom`, `scale`, `dolly`, `cinematic`, `dramatic`, `approach`, `retreat` -- **Synonyms**: background zoom, bg zoom, zoom scroll, dolly zoom, zoom effect background, ken burns scroll - -### BgFade - -- **Description**: Background opacity transition on scroll. Subtle fade in/out as section enters/exits viewport. -- **Tags**: `fade`, `opacity`, `transition`, `subtle`, `reveal`, `in`, `out` -- **Synonyms**: background fade, bg fade, fade background, background opacity, background reveal - -### BgFadeBack - -- **Description**: Fade targeting back layer specifically. For layered backgrounds with separate fade control. -- **Tags**: `fade`, `back`, `layer`, `opacity`, `separate`, `control` -- **Synonyms**: bg fade back, back layer fade, layered fade, separate layer fade - -### BgPan - -- **Description**: Horizontal/vertical background panning. Background slides across as user scrolls. -- **Tags**: `pan`, `horizontal`, `vertical`, `slide`, `movement`, `traverse` -- **Synonyms**: background pan, bg pan, pan scroll, horizontal background, sliding background - -### BgRotate - -- **Description**: Background rotation driven by scroll. Dynamic unusual effect, background spins with scroll. -- **Tags**: `rotate`, `spin`, `dynamic`, `unusual`, `creative`, `turn` -- **Synonyms**: background rotate, bg rotate, spin background, rotation scroll, turning background - -### BgSkew - -- **Description**: Background skew distortion on scroll. Experimental angled distortion effect. -- **Tags**: `skew`, `distortion`, `angle`, `experimental`, `warp`, `tilt` -- **Synonyms**: background skew, bg skew, skew scroll, distortion background, angled background - -### BgReveal - -- **Description**: Clip-based background reveal. Theatrical curtain-like unveiling of background. -- **Tags**: `reveal`, `clip`, `mask`, `theatrical`, `curtain`, `unveil`, `progressive` -- **Synonyms**: background reveal, bg reveal, clip reveal, curtain background, unveiling background - -### BgCloseUp - -- **Description**: Alternative zoom implementation. Cinematic close-up approach effect on background. -- **Tags**: `closeup`, `zoom`, `cinematic`, `approach`, `alternative`, `scale` -- **Synonyms**: bg close up, close up zoom, cinematic closeup, approach zoom - -### BgPullBack - -- **Description**: Reverse zoom (pulling away). Expansive revealing effect, camera retreating from background. -- **Tags**: `pullback`, `zoom`, `reverse`, `expansive`, `retreat`, `reveal`, `wide` -- **Synonyms**: bg pull back, pull back zoom, reverse zoom, expansive reveal, retreat zoom - -### BgFake3D - -- **Description**: Simulated 3D depth layers. Immersive parallax-enhanced depth simulation. -- **Tags**: `fake3d`, `depth`, `layers`, `immersive`, `3d`, `parallax`, `simulation` -- **Synonyms**: bg fake 3d, simulated 3d, depth layers, immersive background, 3d parallax - -### ImageParallax - -- **Description**: Parallax for regular img elements (not CSS backgrounds). Same parallax effect for inline images. -- **Tags**: `image`, `parallax`, `img`, `inline`, `element`, `depth` -- **Synonyms**: image parallax, img parallax, inline image parallax, element parallax - -## Decision Guide - -### By Effect Type - -- **Movement/Depth**: BgParallax, BgPan, ImageParallax, BgFake3D -- **Scale/Zoom**: BgZoom, BgCloseUp, BgPullBack -- **Opacity**: BgFade, BgFadeBack -- **Rotation**: BgRotate -- **Distortion**: BgSkew -- **Reveal/Mask**: BgReveal - -### By Use Case - -- **Depth/Immersion**: BgParallax (most common), BgFake3D -- **Cinematic reveals**: BgZoom, BgCloseUp, BgReveal, BgPullBack -- **Section transitions**: BgFade, BgFadeBack -- **Creative/Experimental**: BgSkew, BgRotate -- **Horizontal storytelling**: BgPan +See [Background Scroll Presets](presets-reference.md#background-scroll-presets) for full details: -### Background vs Regular Element Animations +BgParallax, BgZoom, BgFade, BgFadeBack, BgPan, BgRotate, BgSkew, BgReveal, BgCloseUp, BgPullBack, BgFake3D, ImageParallax -| Use Background Scroll for... | Use regular Scroll for... | -| ---------------------------------- | ------------------------------ | -| `background-image` on sections | `` elements in flow | -| CSS background media | Content that scrolls with page | -| Full-width/full-height backgrounds | Individual elements | -| Media behind content | Media as content | +## Quick Decision -**Exception**: `ImageParallax` is in this category but works on regular `` elements, not CSS backgrounds. +| Effect Type | Presets | +| ------------- | --------- | +| Depth/Movement | BgParallax, BgPan, BgFake3D | +| Scale/Zoom | BgZoom, BgCloseUp, BgPullBack | +| Opacity | BgFade, BgFadeBack | +| Rotation | BgRotate | +| Reveal | BgReveal | -### Reduced Motion Alternatives +## Common Use Cases -| Original | Reduced Motion Fallback | -| ----------------------------- | --------------------------- | -| BgParallax | Static background (disable) | -| BgZoom, BgCloseUp, BgPullBack | BgFade or static | -| BgRotate, BgSkew | Disable | -| BgFake3D | Static or subtle BgParallax | -| BgFade | Keep (it's already subtle) | +| Use Case | Recommended | +| ---------- | ------------- | +| Depth/Immersion | BgParallax (speed: 0.2-0.4) | +| Cinematic reveals | BgZoom, BgCloseUp, BgReveal | +| Section transitions | BgFade | +| Creative/Experimental | BgSkew, BgRotate | -### Parallels in Other Categories +## Note -| Background | Scroll | Entrance | -| ---------- | -------------- | -------- | -| BgParallax | ParallaxScroll | - | -| BgZoom | GrowScroll | GrowIn | -| BgFade | FadeScroll | FadeIn | -| BgReveal | RevealScroll | RevealIn | -| BgRotate | SpinScroll | SpinIn | +`ImageParallax` is for regular `` elements, not CSS backgrounds. diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md b/packages/motion-presets/rules/presets/background-scroll/bg-fade.md deleted file mode 100644 index 52191bf0..00000000 --- a/packages/motion-presets/rules/presets/background-scroll/bg-fade.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -name: BgFade -category: backgroundScroll ---- - -# BgFade - -## Visual Description - -Background opacity changes in response to scroll position, fading in as the section enters the viewport or fading out as it exits. This is the scroll-driven equivalent of FadeIn, applied specifically to background media. - -**`range: 'in'`**: Background starts invisible (or semi-transparent) and gradually becomes fully visible as the user scrolls into the section. Creates a smooth reveal effect. - -**`range: 'out'`**: Background starts visible and gradually becomes invisible as the user scrolls past the section. Creates a graceful dismissal effect. - -**The visual effect**: Subtle and elegant. BgFade transitions backgrounds smoothly without the drama of zoom or parallax. It's perfect for section transitions, layered reveals, or guiding focus. - -This is one of the safest background scroll effects—it's subtle, doesn't cause motion sickness, and degrades gracefully. - -## Parameters - -```typescript -interface BgFade { - range: 'in' | 'out'; // required - start?: number; // %, min: 0, max: 100, default: 0 (in) or 50 (out) - end?: number; // %, min: 0, max: 100, default: 50 (in) or 100 (out) -} -``` - -**Parameter Impact:** - -- `range`: Fade direction (required) - - `in`: Background fades from transparent to visible as section enters - - `out`: Background fades from visible to transparent as section exits -- `start`/`end`: Scroll position range for the fade (0-100) - - Values represent percentage of element visibility in viewport - - **For `in`**: Default 0-50 means fade completes by mid-viewport - - **For `out`**: Default 50-100 means fade starts at mid-viewport - - Wider range = slower fade; narrower range = faster fade - -## Best Practices - -- **Combine in + out for full lifecycle**: Apply both for backgrounds that fade in and out -- **Adjust timing with start/end**: Want fade to complete earlier? Lower the `end` value -- **Use for section transitions**: Fade backgrounds between sections for smooth visual flow -- **Safe for reduced motion**: BgFade is subtle enough to keep in most cases -- **Test overlap with content**: Ensure fading background doesn't make content unreadable at any point - -## Examples - -```typescript -// Basic - fade in as section enters -{ type: 'BgFade', range: 'in' } - -// Fade out as section exits -{ type: 'BgFade', range: 'out' } - -// Quick fade in (completes early) -{ type: 'BgFade', range: 'in', start: 0, end: 25 } - -// Slow fade in (completes late) -{ type: 'BgFade', range: 'in', start: 0, end: 75 } - -// Delayed fade out (starts later) -{ type: 'BgFade', range: 'out', start: 70, end: 100 } -``` diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md b/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md deleted file mode 100644 index 21d5fab9..00000000 --- a/packages/motion-presets/rules/presets/background-scroll/bg-parallax.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -name: BgParallax -category: backgroundScroll ---- - -# BgParallax - -## Visual Description - -Background image or video moves at a different rate than the page scroll, creating an illusion of depth. As users scroll, the background shifts slower than the content in front of it, making it feel like it's further away—like distant scenery through a window. - -**How it works**: The background's vertical position is adjusted based on scroll position, but at a slower rate than the scroll itself. When you scroll 100 pixels down, the background might only move 20-50 pixels. - -**The visual effect**: Subtle depth and dimension without being distracting. The background feels "behind" the content, creating layers of depth. It's one of the most widely used scroll effects because it adds polish without overwhelming. - -This is specifically for CSS background images/videos on containers, not for regular `` elements in the content flow. - -## Parameters - -```typescript -interface BgParallax { - speed?: number; // ratio, min: 0.05, max: 0.95, step: 0.01, default: 0.2 - range?: 'continuous'; // only continuous supported -} -``` - -**Parameter Impact:** - -- `speed`: Rate of background movement relative to scroll (0.05-0.95) - - **0.05-0.2**: Very subtle, barely noticeable—safe, professional - - **0.2 (default)**: Subtle but perceptible—ideal starting point - - **0.3-0.5**: Noticeable depth effect—clearly parallax - - **0.6-0.95**: Strong parallax, dramatic movement—use carefully - - **Visual rule**: Lower speed = background feels further away -- `range`: Only `continuous` is supported - - Effect runs throughout entire time section is in viewport - -## Best Practices - -- **Start subtle (0.2)**: Increase only if depth effect isn't noticeable enough -- **Test on real content**: Parallax can make text over backgrounds harder to read -- **Consider mobile**: Background parallax can be janky on mobile—test or disable -- **One section at a time**: Multiple parallax backgrounds competing can feel chaotic -- **Use high-quality images**: Parallax reveals more of the background—ensure images are large enough and high-res - -## Examples - -```typescript -// Basic - subtle parallax (default) -{ type: 'BgParallax' } - -// Very subtle (barely noticeable) -{ type: 'BgParallax', speed: 0.1 } - -// Noticeable depth effect -{ type: 'BgParallax', speed: 0.4 } - -// Strong parallax (use sparingly) -{ type: 'BgParallax', speed: 0.6 } -``` diff --git a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md b/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md deleted file mode 100644 index c7adb484..00000000 --- a/packages/motion-presets/rules/presets/background-scroll/bg-zoom.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: BgZoom -category: backgroundScroll ---- - -# BgZoom - -## Visual Description - -Background image scales up or down as the user scrolls, creating a cinematic dolly-like effect. The background appears to move toward you (zooming in) or away from you (zooming out) as you scroll through the section. - -**`direction: 'in'`**: Background starts at normal scale and gradually zooms in as scroll progresses. Creates a "moving closer" sensation, like approaching something. - -**`direction: 'out'`**: Background starts zoomed in and gradually zooms out. Creates an "expanding view" sensation, like pulling back to reveal more. - -**The visual effect**: Dramatic, cinematic, and immersive. BgZoom transforms a static background into an active part of the scroll experience. It's attention-grabbing and best used for hero sections or focal points. - -## Parameters - -```typescript -interface BgZoom { - direction: 'in' | 'out'; // default: 'in' - zoom?: number; // multiplier, min: 0.1, max: 10, step: 0.1, default: 10 - range?: 'continuous'; // only continuous supported -} -``` - -**Parameter Impact:** - -- `direction`: Zoom behavior - - `in` (default): Background zooms in as scroll progresses—feels like approaching - - `out`: Background zooms out—feels like pulling back/revealing -- `zoom`: Maximum zoom magnitude (0.1-10) - - **1-3**: Subtle zoom, barely noticeable—safe for most uses - - **4-6**: Medium zoom, clearly cinematic—good for hero sections - - **7-10**: Dramatic zoom—very attention-grabbing, use sparingly - - **10 (default)**: Maximum drama—ensure this fits your design -- `range`: Only `continuous` is supported - -## Best Practices - -- **Default zoom (10) is dramatic**: Consider starting with 3-5 for more subtle effect -- **One zooming background per page**: Multiple competing zooms are overwhelming -- **Ensure image resolution**: Zooming in reveals imperfections—use high-res images -- **Consider content overlap**: Ensure zooming doesn't make text over background harder to read -- **Test on mobile**: Zoom effects can be performance-heavy - -## Examples - -```typescript -// Basic - zooms in as you scroll -{ type: 'BgZoom', direction: 'in' } - -// Zoom out (revealing, expanding view) -{ type: 'BgZoom', direction: 'out' } - -// Subtle zoom in -{ type: 'BgZoom', direction: 'in', zoom: 3 } - -// Medium dramatic zoom -{ type: 'BgZoom', direction: 'in', zoom: 6 } - -// Dramatic full zoom -{ type: 'BgZoom', direction: 'in', zoom: 10 } -``` diff --git a/packages/motion-presets/rules/presets/entrance.md b/packages/motion-presets/rules/presets/entrance.md index a150dd75..5fdf12b0 100644 --- a/packages/motion-presets/rules/presets/entrance.md +++ b/packages/motion-presets/rules/presets/entrance.md @@ -1,245 +1,67 @@ --- name: Entrance Animations -category: entrance -tags: - [ - entrance, - appear, - reveal, - enter, - load, - show, - intro, - page-load, - modal, - popup, - first-time, - visibility, - ] +trigger: entrance --- # Entrance Animations -## Description +One-shot animations that play once when an element first enters the viewport. -Entrance animations bring elements into view for the first time. They create the initial impression and set the tone for user interaction. These are one-shot animations that play once when an element first appears, whether on page load, after a user action, or when content becomes visible. +## Trigger Mechanism -Entrance animations are the most commonly used animation category. They help establish visual hierarchy, guide user attention, and make interfaces feel polished and responsive. A well-chosen entrance animation can make the difference between a static, lifeless page and an engaging, dynamic experience. +Uses the `viewEnter` trigger (intersection observer). Plays automatically when element scrolls into view for the first time. -## Synonyms +**Note:** For click, toggle, or other event-based triggers, implement the triggering logic separately and call the animation programmatically. -appear animation, reveal effect, intro animation, show animation, enter animation, page load animation, element appearance, fade in effect, loading animation, first-time visibility, content reveal, emergence effect +## When to Use -## When to Use Entrance Animations +- Element reveals on viewport entry +- First-time visibility animations +- Content appearing as user scrolls down -- **Page load reveals**: Elements appearing when the page first loads -- **Modal/overlay/popup appearances**: Dialogs, tooltips, dropdowns appearing -- **Content revealing after user action**: Click, tab switch, accordion expand -- **Elements entering viewport once**: Triggered once (not scroll-driven continuous) -- **Lazy-loaded content**: Images, cards, or sections loading asynchronously -- **State transitions**: Empty → populated states, loading → loaded +## When NOT to Use -## When NOT to Use Entrance Animations - -- **Scroll-driven reveals** → use Scroll animations instead -- **Continuous/looping animations** → use Ongoing animations instead -- **Mouse-reactive elements** → use Mouse animations instead -- **Background media** → use Background Scroll animations instead -- **Frequently toggled elements** → may cause animation fatigue - -## Accessibility Considerations - -- **Respect `prefers-reduced-motion`**: Always provide FadeIn as fallback or disable animations entirely for users who prefer reduced motion -- **Duration guidelines**: Keep animations under 500ms for functional UI elements (buttons, modals), up to 1200ms for decorative/hero content -- **Avoid vestibular triggers**: Limit large-scale movement, spinning (SpinIn), and 3D rotations for motion-sensitive users. BounceIn, ArcIn, FlipIn, and TurnIn can trigger vestibular disorders -- **Focus management**: Ensure animated elements don't interfere with keyboard focus order. Modal entrances should trap focus appropriately -- **Screen readers**: Animations are visual-only; ensure all content is accessible without them. Use `aria-live` regions for dynamic content -- **Reduced motion fallback order**: SpinIn/FlipIn → FadeIn, BounceIn → FadeIn or SlideIn, ArcIn → FadeIn +- Scroll-driven reveals → see [Scroll](presets-reference.md#scroll) +- Continuous/looping → see [Ongoing](presets-reference.md#ongoing) +- Mouse-reactive → see [Mouse](presets-reference.md#mouse) ## Available Presets -### FadeIn - -- **Description**: Gradual opacity transition from invisible to visible. No movement or shape changes - just smooth materialization. The simplest and most universally applicable entrance. -- **Tags**: `fade`, `opacity`, `subtle`, `simple`, `professional`, `minimal`, `appear`, `universal`, `accessible` -- **Synonyms**: fade in, appear, materialize, opacity transition, gentle reveal, soft entrance, dissolve in - -### ArcIn - -- **Description**: 3D curved swing like a door opening towards you. Starts tilted away and gradually flattens as it settles. Dramatic, cinematic, creates depth. -- **Tags**: `3d`, `arc`, `curved`, `dramatic`, `cinematic`, `perspective`, `rotation`, `premium`, `hero` -- **Synonyms**: arc entrance, curved reveal, 3d arc, swing in, cinematic entrance, perspective reveal, dramatic arc, door opening - -### BlurIn - -- **Description**: Element transitions from blurry to sharp focus while fading in. Soft, dreamy, draws attention to the sharpening moment. -- **Tags**: `blur`, `focus`, `soft`, `dreamy`, `gentle`, `elegant`, `attention` -- **Synonyms**: blur reveal, focus in, soft reveal, dreamy entrance, blur to focus, defocus to focus - -### BounceIn - -- **Description**: Playful bouncing physics - overshoots landing spot then bounces smaller and smaller until settled. Fun, energetic, attention-grabbing. -- **Tags**: `bounce`, `playful`, `energetic`, `fun`, `elastic`, `spring`, `attention`, `physics` -- **Synonyms**: bounce entrance, bouncy reveal, spring in, elastic entrance, playful appear, jump in, hop in - -### CircleIn - -- **Description**: Circular mask expanding from center point to reveal element. Geometric, modern, spotlight-like effect. -- **Tags**: `circle`, `mask`, `geometric`, `modern`, `spotlight`, `radial`, `reveal` -- **Synonyms**: circle reveal, radial reveal, spotlight entrance, circular mask, expanding circle - -### CurveIn - -- **Description**: Alternative curved 3D motion path. Similar to ArcIn but with different trajectory characteristics. -- **Tags**: `3d`, `curve`, `path`, `motion`, `trajectory`, `cinematic` -- **Synonyms**: curved entrance, path reveal, curved motion, trajectory entrance - -### DropIn - -- **Description**: Falls from above with subtle scale/bounce on landing. Gravity-like, natural feeling entrance with soft impact. -- **Tags**: `drop`, `fall`, `gravity`, `natural`, `scale`, `bounce`, `impact`, `landing` -- **Synonyms**: drop entrance, fall in, gravity drop, landing animation, drop down - -### ExpandIn - -- **Description**: Expands outward from center point. Growing, revealing, spotlight-like emergence effect. -- **Tags**: `expand`, `grow`, `center`, `scale`, `emergence`, `spotlight`, `reveal` -- **Synonyms**: expand entrance, growing reveal, center expand, emergence, outward growth - -### FlipIn - -- **Description**: 3D card flip rotation to reveal element. Dramatic, reveals "other side", card-like metaphor. -- **Tags**: `flip`, `3d`, `rotation`, `card`, `dramatic`, `reveal`, `turn` -- **Synonyms**: flip entrance, card flip, 3d flip, flip reveal, turn over, flip animation - -### FloatIn - -- **Description**: Gentle floating/drifting entrance. Ethereal, light, dreamy movement as if carried by air. -- **Tags**: `float`, `drift`, `ethereal`, `light`, `dreamy`, `gentle`, `air`, `soft` -- **Synonyms**: float entrance, drift in, floating reveal, ethereal entrance, airy entrance - -### FoldIn - -- **Description**: Paper-folding 3D effect. Origami-like, creative, element unfolds into view. -- **Tags**: `fold`, `3d`, `paper`, `origami`, `creative`, `unfold`, `dimensional` -- **Synonyms**: fold entrance, paper fold, origami reveal, unfold animation, folding entrance - -### GlideIn - -- **Description**: Smooth 2D glide from direction with angle control. Clean, directional, professional movement. -- **Tags**: `glide`, `slide`, `smooth`, `directional`, `clean`, `professional`, `angle` -- **Synonyms**: glide entrance, smooth slide, directional glide, angled entrance, sliding reveal - -### GlitchIn - -- **Description**: Digital glitch/distortion effect. Edgy, tech-inspired, disruptive visual entrance. -- **Tags**: `glitch`, `digital`, `distortion`, `edgy`, `tech`, `disruption`, `modern`, `cyber` -- **Synonyms**: glitch entrance, digital reveal, distortion entrance, tech glitch, cyber entrance - -### GrowIn - -- **Description**: Scale from small to full size. Expanding, emerging, element grows into existence. -- **Tags**: `grow`, `scale`, `expand`, `emerge`, `size`, `zoom`, `magnify` -- **Synonyms**: grow entrance, scale up, expanding entrance, zoom in, size grow, emergence - -### PunchIn - -- **Description**: Corner-based scale with energy and impact. Impactful, attention-grabbing, punchy entrance. -- **Tags**: `punch`, `impact`, `corner`, `scale`, `energy`, `attention`, `bold`, `strong` -- **Synonyms**: punch entrance, impact reveal, corner punch, bold entrance, powerful entrance - -### RevealIn - -- **Description**: Directional clip/mask reveal like a curtain opening. Theatrical, unveiling, directional exposure. -- **Tags**: `reveal`, `clip`, `mask`, `curtain`, `directional`, `theatrical`, `unveil` -- **Synonyms**: reveal entrance, curtain reveal, clip reveal, unveiling, mask reveal, wipe in - -### ShapeIn - -- **Description**: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise, customizable mask shapes. -- **Tags**: `shape`, `mask`, `geometric`, `circle`, `square`, `diamond`, `precise`, `custom` -- **Synonyms**: shape reveal, geometric reveal, mask entrance, shape mask, custom shape reveal - -### ShuttersIn - -- **Description**: Venetian blind strip reveal. Segmented, rhythmic, strips revealing content progressively. -- **Tags**: `shutters`, `blinds`, `strips`, `segmented`, `rhythmic`, `venetian`, `progressive` -- **Synonyms**: shutters reveal, blind reveal, strip entrance, venetian entrance, segmented reveal - -### SlideIn - -- **Description**: Straight movement from direction. Clean, simple, versatile directional entrance. -- **Tags**: `slide`, `move`, `directional`, `clean`, `simple`, `versatile`, `translate` -- **Synonyms**: slide entrance, slide in, directional slide, movement entrance, translate in - -### SpinIn - -- **Description**: Rotating entrance with spin. Dynamic, playful, attention-grabbing rotation into view. -- **Tags**: `spin`, `rotate`, `dynamic`, `playful`, `attention`, `rotation`, `turn` -- **Synonyms**: spin entrance, rotating reveal, spin in, rotation entrance, twirl in - -### TiltIn - -- **Description**: 3D tilt into view. Subtle depth, elegant perspective shift as element appears. -- **Tags**: `tilt`, `3d`, `subtle`, `depth`, `elegant`, `perspective`, `angle` -- **Synonyms**: tilt entrance, perspective tilt, 3d tilt, angled reveal, subtle 3d - -### TurnIn - -- **Description**: Corner-pivot 3D rotation. Complex, dramatic, premium feeling entrance with pivot point. -- **Tags**: `turn`, `3d`, `corner`, `pivot`, `dramatic`, `premium`, `complex`, `rotation` -- **Synonyms**: turn entrance, corner turn, pivot reveal, 3d turn, corner rotation +See [Entrance Presets](presets-reference.md#entrance-presets) for full details: -### WinkIn +FadeIn, ArcIn, BlurIn, BounceIn, CircleIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, GlitchIn, GrowIn, PunchIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn -- **Description**: Split-in-half reveal from center. Unique, eye-like opening, center-split entrance. -- **Tags**: `wink`, `split`, `center`, `unique`, `eye`, `opening`, `divide` -- **Synonyms**: wink entrance, split reveal, center split, eye opening, divide reveal +## Common Parameters -## Decision Guide +All entrance presets share: -### By Tone +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) -- **Subtle/Professional**: FadeIn, BlurIn, SlideIn, GlideIn, TiltIn -- **Dramatic/Cinematic**: ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn -- **Playful/Energetic**: BounceIn, SpinIn, PunchIn, GlitchIn -- **Geometric/Modern**: CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn -- **Soft/Dreamy**: FloatIn, BlurIn, FadeIn +See [Common Parameters](presets-reference.md#common-parameters) for details on `power` behavior. -### By Use Case +## Quick Decision -- **Hero sections**: ArcIn, ExpandIn, GrowIn, FloatIn, RevealIn -- **Modals/Overlays**: FadeIn, DropIn, GrowIn, SlideIn -- **List items (staggered)**: FadeIn, SlideIn, GlideIn -- **Notifications/Badges**: BounceIn, PunchIn, DropIn -- **Cards**: FlipIn, ArcIn, TiltIn, FadeIn -- **Images/Media**: RevealIn, ShapeIn, ShuttersIn, CircleIn, BlurIn -- **Text content**: FadeIn, SlideIn, BlurIn -- **CTAs/Buttons**: BounceIn, PunchIn, GrowIn +| Tone | Presets | +| ------ | --------- | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | +| Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | +| Geometric/Modern | CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn | -### Reduced Motion Alternatives +## Common Use Cases -Always provide a reduced-motion fallback. Recommended mappings: +| Use Case | Recommended | +| ---------- | ------------- | +| Hero sections | ArcIn, ExpandIn, FloatIn | +| Modals/Popups | FadeIn, DropIn, GrowIn | +| List items (staggered) | FadeIn, SlideIn with delay | +| Notifications | BounceIn, PunchIn | +| Cards | FlipIn, ArcIn, TiltIn | -| Original | Reduced Motion Fallback | -| ------------------------- | -------------------------------------- | -| BounceIn, SpinIn, PunchIn | FadeIn | -| ArcIn, FlipIn, TurnIn | FadeIn | -| SlideIn, GlideIn | FadeIn (or keep with shorter duration) | -| ShuttersIn, ShapeIn | FadeIn | -| GlitchIn | FadeIn | +## Combining with Ongoing -### Parallels in Other Categories +Entrance + Ongoing is the only combination supported on a single element. Example: -| Entrance | Scroll | Ongoing | Mouse | -| -------- | ------------ | ------- | ----------- | -| ArcIn | ArcScroll | - | - | -| FadeIn | FadeScroll | Flash | - | -| SpinIn | SpinScroll | Spin | SpinMouse | -| BounceIn | - | Bounce | BounceMouse | -| TiltIn | TiltScroll | - | Tilt3DMouse | -| FlipIn | FlipScroll | Flip | - | -| GrowIn | GrowScroll | - | ScaleMouse | -| SlideIn | SlideScroll | - | TrackMouse | -| BlurIn | BlurScroll | - | BlurMouse | -| RevealIn | RevealScroll | - | - | +- BounceIn plays on viewport entry +- Pulse continues indefinitely after diff --git a/packages/motion-presets/rules/presets/entrance/arc-in.md b/packages/motion-presets/rules/presets/entrance/arc-in.md deleted file mode 100644 index 650c329b..00000000 --- a/packages/motion-presets/rules/presets/entrance/arc-in.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: ArcIn -category: entrance ---- - -# ArcIn - -## Visual Description - -Element swings into view along a curved arc path, like a door opening towards you or a card being dealt onto a table. The motion has a sense of depth and dimension—the element appears to exist in 3D space, rotating on an axis as it enters. - -**At the start**: The element is invisible and tilted away from the viewer. Depending on the direction, it's either rotated back (like looking at the top of a tilted card), forward (like seeing the bottom edge), or sideways (like a door partially open). - -**During the animation**: The element simultaneously fades in and rotates toward its final flat position. The rotation follows a smooth arc trajectory, not a linear path, which creates the cinematic "swinging" feel. The opacity increases as the rotation progresses. - -**At the end**: The element is fully visible and flat (no rotation), settled in its final position. - -The effect feels dramatic, premium, and cinematic—best suited for hero elements, featured content, or moments where you want to make an impression. - -## Parameters - -```typescript -interface ArcIn { - direction: 'top' | 'right' | 'bottom' | 'left'; // default: 'left' - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 -} -``` - -**Parameter Impact:** - -- `direction`: Determines the rotation axis and where the element appears to come from - - `top`: Rotates on X-axis, element tilts forward as if falling into place from above - - `bottom`: Rotates on X-axis opposite direction, element rises up from below - - `left`: Rotates on Y-axis, element swings in from the left like a door opening - - `right`: Rotates on Y-axis opposite direction, swings in from the right - - **Visual tip**: `left`/`right` feel like hinged doors; `top`/`bottom` feel like flaps or lids -- `power`: Controls the intensity of the rotation and easing - - `soft`: ~15° rotation, gentle easing—subtle, elegant, good for supporting content - - `medium`: ~30° rotation, balanced easing—the sweet spot for most uses - - `hard`: ~45° rotation with slight overshoot—dramatic, attention-grabbing, use sparingly -- `duration`: Animation length - - **800-1000ms**: Snappy but still cinematic - - **1200ms (default)**: Balanced cinematic feel - - **1500-2000ms**: Very slow, dramatic, use for hero moments only -- `delay`: Pre-animation wait time, useful for sequencing - -## Best Practices - -- **Use on single focal elements**—ArcIn is dramatic and competes for attention. Don't use on multiple simultaneous elements -- **Consider mobile**: Use `power: 'soft'` on mobile devices for better performance and reduced motion intensity -- **Match direction to layout**: If content comes from the left side of the screen, use `direction: 'left'` -- **Pair with stagger for sequences**: If animating multiple items, use increasing `delay` values -- **Have a simpler fallback**: Use FadeIn for reduced-motion preference - -## Examples - -```typescript -// Basic - swings in from left (default) -{ type: 'ArcIn' } - -// Hero section - dramatic entrance from bottom -{ type: 'ArcIn', direction: 'bottom', power: 'hard' } - -// Subtle supporting content -{ type: 'ArcIn', direction: 'left', power: 'soft', duration: 800 } - -// Side-by-side cards with stagger -{ type: 'ArcIn', direction: 'left', delay: 0 } // Left card -{ type: 'ArcIn', direction: 'right', delay: 150 } // Right card - -// Sequential vertical reveal -{ type: 'ArcIn', direction: 'top', delay: 0 } -{ type: 'ArcIn', direction: 'top', delay: 200 } -{ type: 'ArcIn', direction: 'top', delay: 400 } -``` diff --git a/packages/motion-presets/rules/presets/entrance/bounce-in.md b/packages/motion-presets/rules/presets/entrance/bounce-in.md deleted file mode 100644 index 15f66a33..00000000 --- a/packages/motion-presets/rules/presets/entrance/bounce-in.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -name: BounceIn -category: entrance ---- - -# BounceIn - -## Visual Description - -Element bounces into view with playful, physics-inspired motion that mimics a ball dropping and bouncing to rest. The animation creates an energetic, fun, attention-grabbing entrance that feels alive and dynamic. - -**At the start**: The element is invisible and positioned away from its final location (based on direction). If coming from `top`, it's above; if from `center`, it's scaled down like approaching from far away. - -**During the animation**: The element moves toward its final position but overshoots it, then bounces back. This bounce-settle pattern repeats with decreasing amplitude—each bounce is smaller than the last—until the element comes to rest. Simultaneously, the element fades in during the initial approach. - -**At the end**: The element is fully visible, in its final position, completely settled with no residual motion. - -The effect feels playful, energetic, and attention-grabbing. It's perfect for elements that should feel fun, alive, or important enough to demand attention. - -## Parameters - -```typescript -interface BounceIn { - direction: 'top' | 'right' | 'bottom' | 'left' | 'center'; // default: 'top' - power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - distanceFactor?: number; // min: 1, max: 4, step: 0.1, default: 1 - duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 -} -``` - -**Parameter Impact:** - -- `direction`: Origin point of the bounce - - `top`: Bounces down from above, like something dropping from the ceiling - - `bottom`: Bounces up from below, like something popping up from the ground - - `left`/`right`: Bounces horizontally, like something thrown from the side - - `center`: Bounces on Z-axis with 3D perspective—element appears to bounce toward the viewer from far away. Most dramatic option -- `power`: Controls bounce amplitude (how far it overshoots) - - `soft` (default): Factor 1, subtle bounces—professional enough for business contexts - - `medium`: Factor 2, noticeable bounces—clearly playful - - `hard`: Factor 3, dramatic large bounces—very energetic, potentially distracting -- `distanceFactor`: Fine-grained control over bounce travel distance (1-4) - - Lower values = tighter, more contained bounces - - Higher values = larger, more exaggerated bounces -- `duration`: Total animation time including all bounces - - **800-1000ms**: Quick, snappy bounces - - **1200ms (default)**: Balanced timing - - **1500ms+**: Slow, deliberate bounces - -## Best Practices - -- **Use for attention**: BounceIn demands attention—reserve for elements that deserve it (notifications, CTAs, rewards) -- **Limit to one element**: Multiple simultaneous bounces create visual chaos -- **Consider the context**: BounceIn is inherently playful; it may feel unprofessional in corporate/serious contexts -- **`center` direction is most dramatic**: Use for maximum impact, but it's also the most intense for motion-sensitive users -- **Reduced motion**: Always provide FadeIn fallback—bouncing can trigger vestibular discomfort - -## Examples - -```typescript -// Basic - bounces down from above -{ type: 'BounceIn' } - -// Notification badge - subtle but noticeable -{ type: 'BounceIn', direction: 'top', power: 'soft' } - -// Reward/Achievement popup - dramatic center bounce -{ type: 'BounceIn', direction: 'center', power: 'medium' } - -// Playful CTA button -{ type: 'BounceIn', direction: 'bottom', power: 'medium', duration: 1000 } - -// Chat message appearing (from side) -{ type: 'BounceIn', direction: 'left', power: 'soft', duration: 800 } -``` diff --git a/packages/motion-presets/rules/presets/entrance/fade-in.md b/packages/motion-presets/rules/presets/entrance/fade-in.md deleted file mode 100644 index 60dba287..00000000 --- a/packages/motion-presets/rules/presets/entrance/fade-in.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -name: FadeIn -category: entrance ---- - -# FadeIn - -## Visual Description - -Element transitions smoothly from completely invisible (opacity 0) to fully visible (opacity 1). This is the simplest and most universal animation—there's no movement, rotation, scale change, or any other transformation. The element simply materializes in place, like a gentle reveal or a light gradually turning on. - -At the start, the element is entirely transparent. During the animation, opacity increases linearly until the element reaches full visibility. The effect is subtle, clean, and professional. It draws minimal attention to the animation itself, instead letting the content take focus. - -FadeIn is the safest animation choice—it works everywhere, doesn't trigger motion sensitivity issues, and serves as the ideal fallback for more complex animations when reduced motion is preferred. - -## Parameters - -```typescript -interface FadeIn { - duration?: number; // ms, min: 0, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 -} -``` - -**Parameter Impact:** - -- `duration`: Controls how quickly the opacity transition completes - - **200-400ms**: Snappy, barely noticeable—good for functional UI elements like tooltips, dropdowns - - **500-800ms**: Balanced, noticeable but not slow—good for modals, cards - - **1000-1500ms**: Slow, deliberate—good for hero content, dramatic reveals - - **1200ms (default)**: The sweet spot for most decorative uses -- `delay`: Time before animation starts - - **0ms**: Immediate start - - **100-300ms**: Slight pause, useful for staggered sequences - - **500ms+**: Noticeable wait, use intentionally for dramatic effect - -## Best Practices - -- Use as the **default reduced-motion fallback** for all other entrance animations -- Keep duration under 500ms for functional UI (modals, dropdowns, tooltips) -- Combine with `delay` for elegant staggered list reveals -- Consider even shorter durations (200-300ms) for frequently shown/hidden elements -- Don't overthink it—FadeIn is often the right choice when you're unsure - -## Examples - -```typescript -// Basic - default settings work for most cases -{ type: 'FadeIn' } - -// Quick functional fade (modal, dropdown) -{ type: 'FadeIn', duration: 300 } - -// Slow dramatic reveal (hero content) -{ type: 'FadeIn', duration: 1500 } - -// Staggered list items -{ type: 'FadeIn', delay: 0 } // Item 1 -{ type: 'FadeIn', delay: 100 } // Item 2 -{ type: 'FadeIn', delay: 200 } // Item 3 -{ type: 'FadeIn', delay: 300 } // Item 4 -``` diff --git a/packages/motion-presets/rules/presets/mouse.md b/packages/motion-presets/rules/presets/mouse.md index 125bc32e..88e41a79 100644 --- a/packages/motion-presets/rules/presets/mouse.md +++ b/packages/motion-presets/rules/presets/mouse.md @@ -1,174 +1,53 @@ --- name: Mouse Animations -category: mouse -tags: [mouse, cursor, hover, interactive, follow, track, pointer, mousemove, desktop, response] +trigger: mouse --- # Mouse Animations -## Description +Animations that respond to cursor position. Desktop-only. -Mouse animations respond to cursor position, creating interactive elements that follow, tilt, or transform based on where the user's mouse is located. These animations create a sense of depth, interactivity, and playfulness that makes interfaces feel responsive and alive. +## When to Use -Mouse animations are **desktop-only**—they require a mouse or trackpad and have no effect on touch devices. Always consider mobile fallbacks when using mouse animations. +- Interactive cards/products (tilt effect) +- Parallax depth with cursor +- Hero section interactivity +- Playful/game-like interfaces -## Synonyms +## When NOT to Use -cursor animation, hover effect, mouse follow, cursor tracking, mouse parallax, interactive hover, pointer animation, mousemove effect, cursor response, mouse-driven animation, hover interaction - -## When to Use Mouse Animations - -- **Interactive cards/products**: Tilt effect on product images, cards -- **Parallax depth with cursor**: Layered elements responding to mouse -- **Hero section interactivity**: Adding depth and engagement to landing pages -- **Portfolio/showcase**: Interactive image galleries, project previews -- **Playful interfaces**: Game-like interactions, fun micro-interactions -- **Premium/luxury feel**: Subtle tilt effects convey quality - -## When NOT to Use Mouse Animations - -- **Mobile-first designs** → these simply won't work on touch devices -- **Clickable/interactive elements** → may interfere with click targets -- **Accessibility-critical interfaces** → mouse animations exclude keyboard users -- **Performance-sensitive pages** → constant calculations on mousemove -- **Multiple simultaneous effects** → visual overload, performance issues -- **Essential functionality** → never rely on mouse animation for core features - -## Accessibility Considerations - -- **Desktop-only limitation**: Mouse animations don't work on touch devices, keyboard navigation, or for users who can't use a mouse. Always ensure content is fully accessible without them -- **Respect `prefers-reduced-motion`**: Disable mouse animations entirely for users who prefer reduced motion -- **Vestibular concerns**: Tilt3DMouse, SpinMouse, and Track3DMouse with large values can cause discomfort. Keep effects subtle -- **Don't interfere with interaction**: Mouse animations shouldn't make it harder to click buttons, links, or form elements -- **Provide visual feedback alternatives**: If hover effects are important for understanding UI state, provide non-motion alternatives -- **Keyboard users excluded**: Mouse animations are invisible to keyboard navigators—don't use them to convey important information +- Mobile-first designs (won't work on touch) +- Accessibility-critical interfaces +- Essential functionality +- Multiple simultaneous effects ## Available Presets -### Tilt3DMouse - -- **Description**: Element tilts towards cursor like holding a card and angling it. 3D perspective rotation following mouse position. -- **Tags**: `tilt`, `3d`, `perspective`, `card`, `rotate`, `angle`, `premium`, `interactive` -- **Synonyms**: 3d tilt, mouse tilt, perspective tilt, interactive tilt, hover tilt, card tilt, gyroscope effect - -### TrackMouse - -- **Description**: Element follows cursor position, moving in same direction. Floating object that drifts towards where you point. -- **Tags**: `track`, `follow`, `translate`, `movement`, `parallax`, `float`, `drift` -- **Synonyms**: mouse tracking, follow cursor, cursor follow, mouse movement, parallax mouse, floating follow - -### BounceMouse - -- **Description**: Bouncy/elastic cursor following. Overshoots and wobbles before settling, springy playful motion. -- **Tags**: `bounce`, `elastic`, `spring`, `playful`, `wobble`, `overshoot`, `jelly` -- **Synonyms**: bouncy mouse, elastic follow, spring mouse, bouncy cursor effect, elastic tracking - -### Track3DMouse - -- **Description**: Combined translation + 3D rotation following mouse. Complex immersive effect with movement and tilt. -- **Tags**: `track`, `3d`, `translate`, `rotate`, `complex`, `immersive`, `combined` -- **Synonyms**: 3d track mouse, combined mouse effect, translate and tilt, immersive mouse - -### SpinMouse - -- **Description**: Rotation following mouse angle. Element spins/rotates based on cursor position around element. -- **Tags**: `spin`, `rotate`, `angle`, `circular`, `dynamic`, `follow` -- **Synonyms**: mouse spin, rotation follow, angle mouse, spinning cursor effect - -### ScaleMouse - -- **Description**: Scale based on cursor distance. Element grows/shrinks depending on how close mouse is. -- **Tags**: `scale`, `zoom`, `distance`, `proximity`, `grow`, `shrink`, `size` -- **Synonyms**: scale mouse, zoom mouse, proximity scale, distance zoom, hover scale - -### SwivelMouse - -- **Description**: Z-axis rotation following cursor. Unique gyroscope-like rotation on vertical axis. -- **Tags**: `swivel`, `z-axis`, `rotate`, `gyroscope`, `unique`, `vertical` -- **Synonyms**: swivel mouse, z rotation, gyroscope mouse, vertical rotation - -### SkewMouse - -- **Description**: Skew distortion following cursor. Experimental angular distortion based on mouse position. -- **Tags**: `skew`, `distortion`, `angle`, `experimental`, `warp`, `tilt` -- **Synonyms**: skew mouse, distortion mouse, angle skew, warp mouse - -### BlurMouse - -- **Description**: Blur based on cursor distance. Focus/defocus effect depending on mouse proximity. -- **Tags**: `blur`, `focus`, `distance`, `proximity`, `defocus`, `depth` -- **Synonyms**: blur mouse, focus mouse, proximity blur, distance focus - -### AiryMouse - -- **Description**: Floating/airy cursor response. Ethereal, light movement as if carried by air currents. -- **Tags**: `airy`, `float`, `ethereal`, `light`, `gentle`, `drift`, `soft` -- **Synonyms**: airy mouse, floating mouse, ethereal cursor, light follow, gentle drift - -### BlobMouse - -- **Description**: Organic blob-like deformation. Experimental fluid shape distortion following cursor. -- **Tags**: `blob`, `organic`, `fluid`, `deform`, `experimental`, `shape`, `morph` -- **Synonyms**: blob mouse, organic deform, fluid mouse, shape morph, blob effect - -### CustomMouse - -- **Description**: Configurable custom behavior. Flexible preset for custom mouse-driven transformations. -- **Tags**: `custom`, `configurable`, `flexible`, `advanced`, `custom-behavior` -- **Synonyms**: custom mouse, configurable mouse, flexible mouse effect, advanced mouse - -## Decision Guide - -### By Effect Type - -- **Translation/Movement**: TrackMouse, BounceMouse, AiryMouse -- **3D Rotation/Tilt**: Tilt3DMouse, Track3DMouse, SwivelMouse -- **2D Rotation**: SpinMouse -- **Scale**: ScaleMouse -- **Distortion**: SkewMouse, BlobMouse -- **Blur**: BlurMouse - -### By Tone - -- **Professional/Premium**: Tilt3DMouse (subtle), TrackMouse (subtle), ScaleMouse -- **Playful/Fun**: BounceMouse, BlobMouse, AiryMouse -- **Game-like/Dynamic**: SpinMouse, Track3DMouse, SkewMouse -- **Experimental/Creative**: BlobMouse, SkewMouse - -### By Use Case +See [Mouse Presets](presets-reference.md#mouse-presets) for full details: -- **Product cards/Images**: Tilt3DMouse, ScaleMouse -- **Hero section depth**: TrackMouse (multiple layers with different distances) -- **Interactive portfolios**: Tilt3DMouse, Track3DMouse -- **Playful interfaces**: BounceMouse, BlobMouse, AiryMouse -- **Decorative elements**: TrackMouse, SpinMouse -- **Focus/Attention**: ScaleMouse, BlurMouse +Tilt3DMouse, TrackMouse, BounceMouse, Track3DMouse, SpinMouse, ScaleMouse, SwivelMouse, SkewMouse, BlurMouse, AiryMouse, BlobMouse, CustomMouse -### Important: Mobile Fallback Strategies +## Quick Decision -Since mouse animations don't work on touch devices: +| Tone | Presets | +|------|---------| +| Professional/Premium | Tilt3DMouse (soft), TrackMouse, ScaleMouse | +| Playful/Fun | BounceMouse, BlobMouse, AiryMouse | +| Game-like/Dynamic | SpinMouse, Track3DMouse, SkewMouse | -1. **Do nothing**: Element remains static on mobile (acceptable for decorative effects) -2. **Use entrance animation**: Apply FadeIn or similar on mobile instead -3. **Use device orientation**: Some effects can map to device tilt (advanced) -4. **Touch-based alternative**: Respond to touch position (requires custom implementation) +## Common Use Cases -### Reduced Motion Alternatives +| Use Case | Recommended | +|----------|-------------| +| Product cards | Tilt3DMouse, ScaleMouse | +| Hero depth layers | TrackMouse with different distances | +| Interactive portfolios | Tilt3DMouse, Track3DMouse | +| Playful interfaces | BounceMouse, BlobMouse | -| Original | Reduced Motion Fallback | -| ------------------------- | ---------------------------- | -| Tilt3DMouse, Track3DMouse | Disable or very subtle scale | -| TrackMouse, BounceMouse | Disable | -| SpinMouse | Disable | -| All mouse animations | Static state | +## Mobile Fallback -### Parallels in Other Categories +Mouse animations don't work on touch devices. Options: -| Mouse | Entrance | Scroll | Ongoing | -| ----------- | -------- | -------------- | ------- | -| Tilt3DMouse | TiltIn | TiltScroll | - | -| TrackMouse | GlideIn | ParallaxScroll | - | -| BounceMouse | BounceIn | - | Bounce | -| SpinMouse | SpinIn | SpinScroll | Spin | -| ScaleMouse | GrowIn | GrowScroll | Pulse | -| BlurMouse | BlurIn | BlurScroll | - | +1. Do nothing (static on mobile) +2. Use entrance animation instead +3. Use device orientation (advanced) diff --git a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md b/packages/motion-presets/rules/presets/mouse/bounce-mouse.md deleted file mode 100644 index 6ac9cc13..00000000 --- a/packages/motion-presets/rules/presets/mouse/bounce-mouse.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -name: BounceMouse -category: mouse ---- - -# BounceMouse - -## Visual Description - -Element follows the mouse cursor with a bouncy, elastic motion. Instead of moving directly to follow the cursor, the element overshoots its target and wobbles back and forth before settling—like a jelly or rubber ball being pulled by an invisible string. - -**How it works**: Like TrackMouse, the element's position responds to cursor location. But instead of smooth easing, BounceMouse uses elastic/spring physics that cause the element to overshoot and oscillate before coming to rest. - -**The visual effect**: Playful, springy, and game-like. The bouncing creates a sense of fun and energy, like the element is alive and excited to follow your cursor. It's inherently casual and not suited for serious professional contexts. - -**The difference from TrackMouse**: TrackMouse smoothly follows; BounceMouse bounces and wobbles. TrackMouse feels responsive and professional; BounceMouse feels playful and energetic. - -## Parameters - -```typescript -interface BounceMouse { - distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // default: { value: 80, type: 'px' } - axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' - inverted?: boolean; // default: false - transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 - transitionEasing?: 'elastic' | 'bounce'; // default: 'elastic' -} -``` - -**Parameter Impact:** - -- `distance`: Maximum translation distance (smaller default than TrackMouse) - - Default 80px is intentionally smaller—bouncy motion with large distances can be overwhelming - - Keep values moderate (50-150px) for best results -- `axis`: Constrain movement direction - - `both` (default): Bounces in 2D - - `horizontal`/`vertical`: Constrains to one axis -- `inverted`: Reverse movement direction - - Creates "repelled" bouncy effect -- `transitionDuration`: Affects bounce timing -- `transitionEasing`: Spring behavior type - - `elastic` (default): Smooth spring with overshoot and gentle settle - - `bounce`: Multiple distinct bounces before settling—more energetic - -## Best Practices - -- **Keep distances small**: Bouncy motion amplifies perceived distance—start with 50-100px -- **Match playful contexts**: BounceMouse screams "fun"—ensure it fits your brand -- **One bouncing element**: Multiple bouncing elements are visually overwhelming -- **Consider `elastic` vs `bounce`**: `elastic` is smoother; `bounce` is more cartoonish -- **Reduced motion**: Disable entirely—bouncy motion can cause discomfort - -## Examples - -```typescript -// Basic - bouncy cursor following -{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } - -// Smaller, more contained bounce -{ type: 'BounceMouse', distance: { value: 50, type: 'px' }, axis: 'both' } - -// Horizontal only bounce -{ type: 'BounceMouse', distance: { value: 100, type: 'px' }, axis: 'horizontal' } - -// More cartoonish bounce easing -{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both', transitionEasing: 'bounce' } - -// Inverted (bounces away from cursor) -{ type: 'BounceMouse', distance: { value: 60, type: 'px' }, axis: 'both', inverted: true } -``` diff --git a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md b/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md deleted file mode 100644 index bbd09285..00000000 --- a/packages/motion-presets/rules/presets/mouse/tilt-3d-mouse.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -name: Tilt3DMouse -category: mouse ---- - -# Tilt3DMouse - -## Visual Description - -Element tilts in 3D space toward the mouse cursor, like holding a physical card and angling it to catch the light. Moving the mouse left makes the element tilt left; moving up makes it tilt back. The effect creates an interactive, premium feel where elements respond to cursor position. - -**How it works**: The element's rotation is calculated based on the cursor's position relative to the element's center. The closer to an edge, the more pronounced the tilt. Moving the cursor away from the element returns it to flat. - -**The visual effect**: The element feels tangible and responsive, like a physical object you can manipulate. It creates depth and interactivity, making the interface feel premium and engaging. Commonly used for product cards, images, and interactive showcases. - -**Inverted mode**: When inverted, the element tilts away from the cursor instead of toward it—creating a "repelled" rather than "attracted" feel. - -## Parameters - -```typescript -interface Tilt3DMouse { - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - angle?: number; // degrees, min: 5, max: 85, step: 1, default: 50 - perspective?: number; // px, min: 200, max: 1000, step: 50, default: 800 - inverted?: boolean; // default: false - transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 - transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' -} -``` - -**Parameter Impact:** - -- `power`: Preset combinations for quick setup - - `soft`: 25° max angle, 1000px perspective—subtle, professional - - `medium` (default): 50° max angle, 500px perspective—balanced, noticeable - - `hard`: 85° max angle, 200px perspective—dramatic, attention-grabbing -- `angle`: Maximum rotation degrees (5-85) - - Lower values (5-25): Subtle tilt, professional feel - - Medium values (30-50): Noticeable, engaging - - High values (60-85): Dramatic, can feel exaggerated -- `perspective`: 3D depth perception (200-1000px) - - Lower values (200-400): Dramatic perspective, close-up feel - - Higher values (800-1000): Subtle perspective, more natural -- `inverted`: Reverses tilt direction - - `false` (default): Tilts toward cursor - - `true`: Tilts away from cursor -- `transitionDuration`: Smoothing delay for tilt changes (0-5000ms) - - Lower values: Snappy response - - Higher values: Smooth, laggy response -- `transitionEasing`: Easing curve for transitions - -## Best Practices - -- **Use on cards and images**: Tilt3DMouse is perfect for product cards, portfolio items, and interactive images -- **Keep it subtle in professional contexts**: Use `power: 'soft'` or low `angle` values for business sites -- **Consider hover area**: Works best when element has space around it for mouse movement -- **Add shadow for depth**: Combine with dynamic shadows that shift with tilt for extra realism -- **Desktop only**: Remember this doesn't work on touch devices—ensure content is accessible without it - -## Examples - -```typescript -// Basic - balanced tilt effect -{ type: 'Tilt3DMouse' } - -// Subtle professional effect -{ type: 'Tilt3DMouse', power: 'soft' } - -// Dramatic interactive card -{ type: 'Tilt3DMouse', power: 'hard' } - -// Custom subtle tilt -{ type: 'Tilt3DMouse', angle: 15, perspective: 1000 } - -// Inverted (tilts away from cursor) -{ type: 'Tilt3DMouse', inverted: true } - -// Snappy response -{ type: 'Tilt3DMouse', transitionDuration: 100 } - -// Smooth, dreamy response -{ type: 'Tilt3DMouse', transitionDuration: 800, transitionEasing: 'easeOut' } -``` diff --git a/packages/motion-presets/rules/presets/mouse/track-mouse.md b/packages/motion-presets/rules/presets/mouse/track-mouse.md deleted file mode 100644 index 635ee4ea..00000000 --- a/packages/motion-presets/rules/presets/mouse/track-mouse.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -name: TrackMouse -category: mouse ---- - -# TrackMouse - -## Visual Description - -Element follows the mouse cursor, translating its position based on cursor location. Like a floating object that drifts toward where you point, the element moves in the direction of the cursor within defined bounds. - -**How it works**: As the cursor moves across the viewport, the element shifts position proportionally. The `distance` parameter defines how far the element can move from its center position. Movement can be constrained to horizontal, vertical, or both axes. - -**The visual effect**: Creates a responsive, floating feel. Multiple elements with different distances create parallax-like depth. The effect feels interactive and playful, like objects following your gaze. - -**Inverted mode**: When inverted, the element moves in the opposite direction—cursor goes right, element goes left. This can create interesting "repelling" effects. - -## Parameters - -```typescript -interface TrackMouse { - distance: { value: number; type: 'px' | 'percentage' | 'vh' | 'vw' }; // default: { value: 250, type: 'px' } - axis: 'horizontal' | 'vertical' | 'both'; // default: 'both' - power?: 'soft' | 'medium' | 'hard'; // default: 'medium' - inverted?: boolean; // default: false - transitionDuration?: number; // ms, min: 0, max: 5000, step: 20, default: 500 - transitionEasing?: 'linear' | 'easeOut' | 'hardBackOut'; // default: 'easeOut' -} -``` - -**Parameter Impact:** - -- `distance`: Maximum translation distance from center position - - `value`: How far the element can move (5-800) - - `type`: Unit of measurement - - `px`: Fixed pixel distance - - `percentage`: Relative to element size - - `vh`/`vw`: Relative to viewport - - Larger values = more dramatic movement -- `axis`: Constrain movement direction - - `both` (default): Element moves in 2D, following cursor anywhere - - `horizontal`: Only left/right movement - - `vertical`: Only up/down movement -- `power`: Affects easing curve - - `soft`: Linear easing—direct, mechanical - - `medium` (default): `easeOut`—smooth, natural - - `hard`: `hardBackOut`—slight overshoot, bouncy -- `inverted`: Reverse movement direction - - `false`: Element follows cursor - - `true`: Element moves opposite to cursor -- `transitionDuration`: Smoothing delay -- `transitionEasing`: Easing curve for smooth transitions - -## Best Practices - -- **Layer multiple elements**: Apply different distances to create parallax depth (e.g., 50px, 150px, 300px) -- **Keep distances reasonable**: Very large distances can make elements move off-screen -- **Constrain axis when appropriate**: Horizontal-only is great for decorative elements in hero sections -- **Inverted creates depth**: Use inverted on "background" elements to create separation from "foreground" -- **Desktop only**: Always ensure content is usable without mouse tracking - -## Examples - -```typescript -// Basic - follows mouse in all directions -{ type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } - -// Horizontal only (good for hero backgrounds) -{ type: 'TrackMouse', distance: { value: 100, type: 'px' }, axis: 'horizontal' } - -// Subtle background layer -{ type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'both' } - -// Dramatic foreground element -{ type: 'TrackMouse', distance: { value: 300, type: 'px' }, axis: 'both' } - -// Inverted (moves opposite to cursor) -{ type: 'TrackMouse', distance: { value: 150, type: 'px' }, axis: 'both', inverted: true } - -// Parallax depth layers (apply to different elements) -// Far background -{ type: 'TrackMouse', distance: { value: 30, type: 'px' }, axis: 'both' } -// Mid layer -{ type: 'TrackMouse', distance: { value: 80, type: 'px' }, axis: 'both' } -// Foreground -{ type: 'TrackMouse', distance: { value: 150, type: 'px' }, axis: 'both' } -``` diff --git a/packages/motion-presets/rules/presets/ongoing.md b/packages/motion-presets/rules/presets/ongoing.md index 1a0d6bda..45abe060 100644 --- a/packages/motion-presets/rules/presets/ongoing.md +++ b/packages/motion-presets/rules/presets/ongoing.md @@ -1,176 +1,47 @@ --- name: Ongoing Animations -category: ongoing -tags: - [ongoing, continuous, loop, looping, repeating, infinite, persistent, ambient, status, indicator] +trigger: ongoing --- # Ongoing Animations -## Description +Continuous looping animations that run indefinitely. -Ongoing animations run continuously in a loop, creating persistent motion on the page. Unlike entrance animations (one-shot) or scroll animations (scroll-driven), ongoing animations repeat indefinitely until stopped. They're used to draw attention, indicate status, or add ambient visual interest. +## When to Use -Use ongoing animations sparingly—they constantly draw the eye and can be distracting or fatiguing if overused. They work best for single focal points like loading indicators, status badges, or attention-grabbing CTAs. +- Loading/processing indicators +- Status indicators (live, active, recording) +- Attention-drawing elements (notifications, CTAs) +- Decorative ambient motion -## Synonyms +## When NOT to Use -continuous animation, looping animation, infinite animation, repeating animation, ambient motion, persistent animation, attention animation, status indicator, loading animation, idle animation, background motion - -## When to Use Ongoing Animations - -- **Loading/Processing indicators**: Spinners, progress indicators -- **Status indicators**: Live/active/online status, recording indicator -- **Attention-drawing elements**: Notification badges, important CTAs -- **Decorative ambient motion**: Background elements, illustrations -- **Waiting states**: While content loads or processes -- **Gamification elements**: Rewards, achievements, collectibles - -## When NOT to Use Ongoing Animations - -- **Multiple simultaneous animations** → visual chaos, distracting -- **Content that needs to be read** → motion interferes with reading -- **Professional/minimal interfaces** → may feel unprofessional -- **Mobile with battery concerns** → continuous animation drains battery -- **One-time reveals** → use Entrance animations -- **Scroll-driven effects** → use Scroll animations - -## Accessibility Considerations - -- **Respect `prefers-reduced-motion`**: Stop all ongoing animations or reduce to very subtle Pulse -- **Provide pause controls**: Users should be able to stop animations. WCAG 2.2.2 requires pause/stop for any motion lasting more than 5 seconds -- **Vestibular safety**: Spin, Bounce, Wiggle, and Swing can trigger motion sickness. Pulse and Flash (subtle) are safer -- **Avoid flashing**: Flash animation at high intensity or speed can trigger seizures. Never exceed 3 flashes per second -- **Attention interference**: Ongoing animations can distract users with ADHD or cognitive disabilities -- **Screen reader announcement**: Ensure status changes are announced, not just animated +- Multiple simultaneous animations (visual chaos) +- Content that needs to be read +- Professional/minimal interfaces +- One-time reveals → see [Entrance](presets-reference.md#entrance) ## Available Presets -### Pulse - -- **Description**: Gentle scale oscillation, heartbeat-like rhythm. Shrinks and expands continuously. Subtle, universal attention indicator. -- **Tags**: `pulse`, `scale`, `heartbeat`, `throb`, `attention`, `subtle`, `status`, `breathing` -- **Synonyms**: pulse effect, heartbeat, throb, breathing, scale pulse, attention pulse, pulsing - -### Bounce - -- **Description**: Vertical bouncing motion like a ball on trampoline. Playful, energetic, attention-grabbing continuous motion. -- **Tags**: `bounce`, `vertical`, `movement`, `playful`, `energetic`, `jump`, `hop`, `spring` -- **Synonyms**: bouncing, jumping, hopping, vertical bounce, continuous bounce, bouncy animation - -### Spin - -- **Description**: Continuous rotation around center. Like a wheel or loading spinner. Mechanical, precise circular motion. -- **Tags**: `spin`, `rotate`, `loading`, `circular`, `wheel`, `continuous`, `mechanical` -- **Synonyms**: spinning, rotating, rotation, circular motion, revolve, turn continuously - -### Breathe - -- **Description**: Slow scale in/out like breathing rhythm. Calm, organic, meditative expansion and contraction. -- **Tags**: `breathe`, `scale`, `slow`, `calm`, `organic`, `meditative`, `expansion`, `zen` -- **Synonyms**: breathing animation, slow pulse, meditation, calm scale, organic rhythm - -### Flash - -- **Description**: Opacity pulsing/blinking effect. Attention, warning, notification indicator through visibility changes. -- **Tags**: `flash`, `blink`, `opacity`, `attention`, `warning`, `notification`, `visibility` -- **Synonyms**: flashing, blinking, blink animation, attention flash, warning blink - -### Swing - -- **Description**: Rotation oscillation like a pendulum. Back and forth pivoting motion, playful rhythmic movement. -- **Tags**: `swing`, `pendulum`, `oscillation`, `rotation`, `pivot`, `rhythmic`, `back-forth` -- **Synonyms**: swinging, pendulum motion, oscillating, pivot swing, back and forth - -### Wiggle - -- **Description**: Horizontal shake/wiggle motion. Side-to-side movement for attention, playful "notice me" effect. -- **Tags**: `wiggle`, `shake`, `horizontal`, `attention`, `playful`, `notice`, `side-to-side` -- **Synonyms**: wiggling, shaking, horizontal shake, side wiggle, shake animation - -### Flip - -- **Description**: Periodic 180° flips. Card-like rotation showing front/back, dramatic periodic turn. -- **Tags**: `flip`, `rotation`, `180`, `card`, `periodic`, `turn`, `front-back` -- **Synonyms**: flipping, card flip, periodic flip, turn animation, flip cycle - -### Fold - -- **Description**: 3D folding motion. Paper-like folding and unfolding, creative dimensional movement. -- **Tags**: `fold`, `3d`, `paper`, `dimensional`, `creative`, `unfold` -- **Synonyms**: folding, paper fold, 3d fold, origami motion, fold animation - -### Jello - -- **Description**: Wobbly elastic deformation. Jiggly, bouncy distortion like gelatin wobbling. -- **Tags**: `jello`, `wobble`, `elastic`, `jiggly`, `bouncy`, `gelatin`, `deform` -- **Synonyms**: jello wobble, jiggly, elastic wobble, bouncy deform, gelatin shake - -### Rubber - -- **Description**: Elastic stretch effect. Springy stretching and snapping back, rubbery distortion. -- **Tags**: `rubber`, `elastic`, `stretch`, `spring`, `snap`, `distortion` -- **Synonyms**: rubber stretch, elastic animation, stretchy, springy, snap back - -### Poke - -- **Description**: Quick scale bump like being tapped. Brief attention "boop" effect, momentary scale spike. -- **Tags**: `poke`, `bump`, `tap`, `quick`, `attention`, `boop`, `spike` -- **Synonyms**: poke effect, bump animation, tap, boop, attention tap, quick bump - -### Cross - -- **Description**: X-pattern diagonal movement. Unique geometric motion crossing diagonally. -- **Tags**: `cross`, `diagonal`, `x-pattern`, `geometric`, `unique`, `movement` -- **Synonyms**: cross movement, diagonal cross, x-pattern, crossing animation - -### DVD - -- **Description**: Corner-to-corner bounce (DVD screensaver). Nostalgic bouncing around container, retro effect. -- **Tags**: `dvd`, `screensaver`, `corner`, `bounce`, `nostalgic`, `retro`, `container` -- **Synonyms**: dvd bounce, screensaver, corner bounce, retro bounce, dvd logo - -## Decision Guide - -### By Motion Type - -- **Scale-based**: Pulse, Breathe, Poke, Rubber -- **Movement/Position**: Bounce, Wiggle, Cross, DVD -- **Rotation**: Spin, Swing, Flip, Fold -- **Opacity**: Flash -- **Deformation**: Jello, Rubber - -### By Tone - -- **Subtle/Professional**: Pulse (soft), Breathe, Flash (soft) -- **Playful/Energetic**: Bounce, Wiggle, Jello, DVD, Rubber -- **Mechanical/Technical**: Spin, Flip, Fold -- **Attention-grabbing**: Flash, Bounce, Pulse (hard), Poke - -### By Use Case +See [Ongoing Presets](presets-reference.md#ongoing-presets) for full details: -- **Loading/Processing**: Spin, Pulse -- **Status indicator (live/active)**: Pulse, Breathe -- **Notification badge**: Bounce, Pulse, Poke, Flash -- **CTA emphasis**: Pulse, Bounce -- **Character/Mascot**: Bounce, Wiggle, Jello -- **Decorative background**: Spin (slow), Breathe, Float +Pulse, Bounce, Spin, Breathe, Flash, Swing, Wiggle, Flip, Fold, Jello, Rubber, Poke, Cross, DVD -### Reduced Motion Alternatives +## Quick Decision -| Original | Reduced Motion Fallback | -| --------------------- | ------------------------------------------ | -| Spin, Swing, Flip | Stop animation or very slow Pulse | -| Bounce, Wiggle, Jello | Pulse (soft) or stop | -| Flash | Reduce frequency, ensure <3 flashes/second | -| DVD, Cross | Stop animation | +| Tone | Presets | +|------|---------| +| Subtle/Professional | Pulse (soft), Breathe, Flash (soft) | +| Playful/Energetic | Bounce, Wiggle, Jello, DVD | +| Mechanical/Technical | Spin, Flip, Fold | +| Attention-grabbing | Flash, Bounce, Pulse (hard), Poke | -### Parallels in Other Categories +## Common Use Cases -| Ongoing | Entrance | Scroll | Mouse | -| ------- | -------- | ---------- | ----------- | -| Pulse | DropIn | GrowScroll | ScaleMouse | -| Bounce | BounceIn | - | BounceMouse | -| Spin | SpinIn | SpinScroll | SpinMouse | -| Flip | FlipIn | FlipScroll | - | -| Flash | FadeIn | FadeScroll | - | +| Use Case | Recommended | +|----------|-------------| +| Loading spinner | Spin (duration: 1500ms) | +| Status indicator | Pulse, Breathe | +| Notification badge | Bounce, Pulse, Poke | +| CTA emphasis | Pulse, Bounce | +| Character/Mascot | Bounce, Wiggle, Jello | diff --git a/packages/motion-presets/rules/presets/ongoing/bounce.md b/packages/motion-presets/rules/presets/ongoing/bounce.md deleted file mode 100644 index e9a452f6..00000000 --- a/packages/motion-presets/rules/presets/ongoing/bounce.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -name: Bounce -category: ongoing ---- - -# Bounce - -## Visual Description - -Element bounces up and down continuously in a playful, physics-inspired motion. Like a ball on a trampoline, the element jumps upward, reaches a peak, falls back down, and bounces again with decreasing height until the cycle resets. - -**The motion**: Starting from its rest position, the element moves upward, reaches its peak, falls back down past the rest position (like a ball compressing on impact), then bounces up again with less height. This continues until bounces become minimal, then the cycle restarts. - -**The visual effect**: Energetic, playful, and attention-grabbing. The bouncing feels alive, like something excited or trying to get your attention. It's inherently fun and casual—not suitable for serious or professional contexts. - -Bounce is one of the more intense ongoing animations. Use it when you want to add playful energy and don't mind the element constantly demanding attention. - -## Parameters - -```typescript -interface Bounce { - power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - intensity?: number; // 0-1, min: 0, max: 1, step: 0.1, default: 0.3 - duration?: number; // ms, min: 100, max: 4000, step: 100, default: 1200 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 1000 -} -``` - -**Parameter Impact:** - -- `power`: Preset bounce height multipliers - - `soft` (default): ~49px maximum height, contained bounces—noticeable but not wild - - `medium`: ~98px maximum height, clearly bouncy—playful and energetic - - `hard`: ~147px maximum height, dramatic bounces—very attention-grabbing, potentially annoying -- `intensity`: Fine-grained control (0-1) mapping to factor 1-3 - - 0.3 (default) = soft - - 0.5 = medium - - 1.0 = hard -- `duration`: Full bounce cycle time - - **800-1000ms**: Quick, energetic bouncing - - **1200ms (default)**: Balanced timing - - **1500ms+**: Slower, more deliberate bounces -- `delay`: Initial wait before bouncing starts - - Gives users a moment before the motion begins - -## Best Practices - -- **Use sparingly**: Bounce is inherently distracting—reserve for elements that truly need attention -- **One bouncing element**: Multiple bouncing elements create visual chaos -- **Match the brand**: Bounce is playful/casual; ensure it fits the overall tone -- **Consider the context**: Bouncing indefinitely can become annoying—consider triggering only when relevant -- **Reduced motion**: Always provide alternative (stop animation entirely or switch to subtle Pulse) - -## Examples - -```typescript -// Basic - subtle continuous bounce -{ type: 'Bounce' } - -// Playful mascot/character -{ type: 'Bounce', power: 'medium', duration: 1000 } - -// Attention indicator (jump here!) -{ type: 'Bounce', power: 'soft', duration: 1500 } - -// Game reward/achievement -{ type: 'Bounce', power: 'hard', duration: 800 } - -// Gentle notification (less intrusive) -{ type: 'Bounce', power: 'soft', intensity: 0.2, duration: 1400 } -``` diff --git a/packages/motion-presets/rules/presets/ongoing/pulse.md b/packages/motion-presets/rules/presets/ongoing/pulse.md deleted file mode 100644 index ecbf80b6..00000000 --- a/packages/motion-presets/rules/presets/ongoing/pulse.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -name: Pulse -category: ongoing ---- - -# Pulse - -## Visual Description - -Element gently expands and contracts in a continuous rhythmic pattern, like a heartbeat or something softly breathing. The scale oscillates—growing slightly larger, then shrinking back to normal size—in an endless loop. - -**The motion**: The element starts at its normal size, grows slightly (maybe 5-15% larger), then shrinks back. This cycle repeats continuously. The timing feels organic, like a pulse or breath, not mechanical. - -**The visual effect**: Creates a sense of life and activity without being aggressive or distracting. The pulsing draws attention subtly, suggesting "hey, look here" without shouting. It's the gentlest way to indicate something is active, alive, or important. - -Pulse is the most universally safe ongoing animation—it's subtle enough for professional contexts and doesn't trigger motion sensitivity as strongly as movement-based animations. - -## Parameters - -```typescript -interface Pulse { - power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - intensity?: number; // 0-1, min: 0, max: 1, step: 0.1, default: 0 - duration?: number; // ms, min: 100, max: 4000, step: 100, default: 1300 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 1000 -} -``` - -**Parameter Impact:** - -- `power`: Preset intensity levels for the pulse magnitude - - `soft` (default): Very subtle pulse, barely noticeable—professional, gentle - - `medium`: Noticeable pulse, clearly alive—good for status indicators - - `hard`: Pronounced pulse, attention-demanding—use for important alerts -- `intensity`: Fine-grained control over pulse magnitude (0-1) - - Overrides `power` if specified - - 0 = no pulse, 1 = maximum pulse - - Use for precise control when presets don't fit -- `duration`: Full pulse cycle time (expand + contract) - - **800-1000ms**: Quick, energetic pulse - - **1300ms (default)**: Balanced, natural feeling - - **2000ms+**: Slow, breathing-like rhythm -- `delay`: Initial wait before pulsing begins - - Useful for staggering multiple pulsing elements - -## Best Practices - -- **One pulsing element at a time**: Multiple simultaneous pulses are visually chaotic -- **Use for status, not content**: Pulse is for "this is active/important," not for decorating content -- **Prefer `soft` power**: Start subtle; increase only if attention isn't captured -- **Combine with color/icon**: Pulse alone may not convey meaning—pair with visual indicators -- **Safe for reduced motion**: Pulse (soft) is often acceptable even with reduced motion preference, but offer disable option - -## Examples - -```typescript -// Basic - subtle pulse indicating activity -{ type: 'Pulse' } - -// Live status indicator (streaming, recording) -{ type: 'Pulse', power: 'medium', duration: 1000 } - -// Gentle notification badge -{ type: 'Pulse', power: 'soft', duration: 1500 } - -// Attention-demanding alert -{ type: 'Pulse', power: 'hard', duration: 800 } - -// Slow, calming breathing effect -{ type: 'Pulse', power: 'soft', duration: 2500 } -``` diff --git a/packages/motion-presets/rules/presets/ongoing/spin.md b/packages/motion-presets/rules/presets/ongoing/spin.md deleted file mode 100644 index a3c8e498..00000000 --- a/packages/motion-presets/rules/presets/ongoing/spin.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: Spin -category: ongoing ---- - -# Spin - -## Visual Description - -Element rotates continuously around its center point, like a wheel, gear, or loading spinner. The rotation can be clockwise or counter-clockwise, at a constant speed or with easing variations. - -**The motion**: The element pivots around its center, completing full 360° rotations indefinitely. By default, the rotation is smooth and constant (linear easing), creating a mechanical, precise feel. With power variations, the rotation can accelerate/decelerate for a more organic feel. - -**The visual effect**: Mechanical, precise, often associated with loading or processing states. Spin is universally understood as "something is happening" or "please wait." It can also be decorative for elements like gears, wheels, or abstract shapes. - -Spin is ideal for loading indicators and decorative rotating elements, but it can be a strong vestibular trigger for motion-sensitive users. - -## Parameters - -```typescript -interface Spin { - direction: 'clockwise' | 'counter-clockwise'; // default: 'clockwise' - power?: 'soft' | 'medium' | 'hard'; // default: 'soft' - duration?: number; // ms, min: 100, max: 50000, step: 100, default: 7000 - delay?: number; // ms, min: 0, max: 8000, step: 100, default: 0 -} -``` - -**Parameter Impact:** - -- `direction`: Rotation direction - - `clockwise` (default): Rotates right, natural/expected direction for most users - - `counter-clockwise`: Rotates left, can feel like "rewinding" or unconventional -- `power`: Controls the easing curve of rotation - - `soft` (default): Linear, constant speed—mechanical, precise - - `medium`: Eased rotation (accelerate/decelerate)—more organic feel - - `hard`: Strong easing with slight overshoot—dynamic, bouncy -- `duration`: Time for one complete rotation - - **1000-2000ms**: Fast spin, energetic - - **3000-5000ms**: Medium speed, typical for loaders - - **7000ms (default)**: Slow, deliberate rotation - - **10000ms+**: Very slow, decorative/ambient -- `delay`: Wait before spinning starts - -## Best Practices - -- **Default duration is slow**: 7 seconds per rotation is intentionally calm. For loaders, consider 1000-2000ms -- **Use for loading states**: Spin is the universal "loading" indicator -- **Don't spin text**: Rotating text is unreadable and disorienting -- **Consider direction**: Clockwise feels natural; counter-clockwise may feel "wrong" to some users -- **Reduced motion**: Always provide static fallback—spinning is a strong vestibular trigger - -## Examples - -```typescript -// Basic - slow clockwise spin -{ type: 'Spin', direction: 'clockwise' } - -// Loading spinner (faster) -{ type: 'Spin', direction: 'clockwise', duration: 1500 } - -// Counter-clockwise (for variety or specific meaning) -{ type: 'Spin', direction: 'counter-clockwise' } - -// Fast energetic spin -{ type: 'Spin', direction: 'clockwise', duration: 800 } - -// Slow decorative rotation (gear, wheel) -{ type: 'Spin', direction: 'clockwise', duration: 15000 } - -// Dynamic spin with easing -{ type: 'Spin', direction: 'clockwise', power: 'medium', duration: 2000 } -``` diff --git a/packages/motion-presets/rules/presets/presets-reference.md b/packages/motion-presets/rules/presets/presets-reference.md new file mode 100644 index 00000000..8d483eb0 --- /dev/null +++ b/packages/motion-presets/rules/presets/presets-reference.md @@ -0,0 +1,1635 @@ +--- +name: Motion Presets Reference +description: Comprehensive LLM reference for Interact motion presets +--- + +# Motion Presets Reference + +## 1. Intro + +This document is a comprehensive reference for Interact motion presets. Use it to select and configure animations based on user requirements. + +### Decision Flow + +1. **Select Trigger** - What causes the animation? (viewport entry, scroll position, mouse, continuous loop) +2. **Select Preset** - Which visual effect matches the intent? +3. **Configure Parameters** - Customize direction, power, timing, etc. + +### Quick Trigger Lookup + +| User Intent | Trigger | Notes | +|-------------|---------|-------| +| "animate when element enters viewport", "reveal on scroll into view" | entrance | viewEnter trigger (intersection observer) | +| "animate based on scroll position", "parallax", "scroll-driven" | scroll | Tied to scroll progress | +| "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely | +| "react to mouse", "follow cursor", "tilt on hover" | mouse | Desktop only | +| "background image effect", "hero background", "parallax bg" | background-scroll | CSS backgrounds only | + +--- + +## 2. Triggers + +### Entrance + +One-shot animations that play once when an element first enters the viewport. + +**Trigger mechanism:** Uses the `viewEnter` trigger (intersection observer). Plays once when element first scrolls into view. + +**When to use:** + +- Element reveals on viewport entry +- First-time visibility animations + +**When NOT to use:** + +- Scroll-driven reveals → use scroll +- Continuous/looping → use ongoing +- Mouse-reactive → use mouse + +**Note:** For click, toggle, or other event-based triggers, implement the triggering logic separately and call the animation programmatically. The library only provides viewEnter as a built-in trigger for entrance animations. + +**Available presets:** FadeIn, ArcIn, BlurIn, BounceIn, CircleIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, GlitchIn, GrowIn, PunchIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn + +### Scroll + +Animations tied to scroll position. Can animate in, out, or continuously throughout scroll range. + +**When to use:** + +- Progressive content reveals on scroll +- Parallax depth effects +- Storytelling tied to scroll progress +- De-emphasizing passed content + +**When NOT to use:** + +- One-time entrance → use entrance (more performant) +- Continuous loops → use ongoing +- Background images → use background-scroll + +**Available presets:** ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll + +### Ongoing + +Continuous looping animations that run indefinitely. + +**When to use:** + +- Loading/processing indicators +- Status indicators (live, active, recording) +- Attention-drawing elements (notifications, CTAs) +- Decorative ambient motion + +**When NOT to use:** + +- Multiple simultaneous animations (visual chaos) +- Content that needs to be read +- Professional/minimal interfaces +- One-time reveals → use entrance + +**Available presets:** Pulse, Bounce, Spin, Breathe, Flash, Swing, Wiggle, Flip, Fold, Jello, Rubber, Poke, Cross, DVD + +### Mouse + +Animations that respond to cursor position. Desktop-only. + +**When to use:** + +- Interactive cards/products (tilt effect) +- Parallax depth with cursor +- Hero section interactivity +- Playful/game-like interfaces + +**When NOT to use:** + +- Mobile-first designs (won't work on touch) +- Accessibility-critical interfaces +- Essential functionality (never rely on mouse for core features) + +**Available presets:** Tilt3DMouse, TrackMouse, BounceMouse, Track3DMouse, SpinMouse, ScaleMouse, SwivelMouse, SkewMouse, BlurMouse, AiryMouse, BlobMouse, CustomMouse + +### Background Scroll + +Scroll animations specifically for CSS background images/videos. + +**When to use:** + +- Hero sections with background depth +- Full-width section backgrounds +- Cinematic storytelling +- Section transitions + +**When NOT to use:** + +- Regular content elements → use scroll +- Non-media backgrounds (solid colors) +- Multiple animated backgrounds (performance) + +**Available presets:** BgParallax, BgZoom, BgFade, BgFadeBack, BgPan, BgRotate, BgSkew, BgReveal, BgCloseUp, BgPullBack, BgFake3D, ImageParallax + +--- + +## Common Parameters + +### Shared by All Entrance Presets + +- `duration`: 0-4000ms (default: 1200) - animation length +- `delay`: 0-8000ms (default: 0) - wait before starting + +### Shared by Most Scroll Presets + +- `range`: 'in' | 'out' | 'continuous' - when animation occurs relative to viewport +- `start`: 0-100% - scroll position to start animation +- `end`: 0-100% - scroll position to end animation + +### Shared by Most Ongoing Presets + +- `duration`: 100-4000ms - single cycle length +- `delay`: 0-8000ms - initial wait before looping starts + +### The `power` Parameter + +Many presets support `power: 'soft' | 'medium' | 'hard'`. + +**Important:** `power` is a preset modifier that **overrides** fine-grained parameters when set. + +- When `power` is provided, it sets predefined values for rotation angles, distances, scale factors, and easing curves +- For fine control, **omit `power`** and use specific parameters like `intensity`, `distanceFactor`, `initialRotate`, etc. +- Pattern: if `power` is set, specific params are ignored + +```typescript +// power overrides other params +{ type: 'BounceIn', power: 'hard' } // Uses hard preset (distanceFactor: 3) +{ type: 'BounceIn', distanceFactor: 2.5 } // Fine control (no power) +{ type: 'BounceIn', power: 'hard', distanceFactor: 2.5 } // power wins, distanceFactor ignored +``` + +--- + +## 3. Trigger-Preset Relations + +### By Tone + +| Tone | Entrance | Scroll | Ongoing | Mouse | +|------|----------|--------|---------|-------| +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (soft), Breathe | Tilt3DMouse (soft), TrackMouse | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | +| Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | +| Geometric/Modern | CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | + +### By Use Case + +| Use Case | Recommended Presets | +|----------|---------------------| +| Hero sections | ArcIn, ExpandIn, FloatIn, RevealIn + BgParallax, BgZoom | +| Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | +| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | +| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | +| Notifications/Badges | BounceIn, PunchIn, DropIn + Pulse | +| CTAs/Buttons | BounceIn, PunchIn, GrowIn + Pulse | +| Loading indicators | Spin, Pulse | +| Product images | Tilt3DMouse, ScaleMouse | +| Background depth | BgParallax, ParallaxScroll, TrackMouse (layered) | + +### Cross-Category Parallels + +Effects with similar visual results across triggers: + +| Entrance | Scroll | Ongoing | Mouse | Background | +|----------|--------|---------|-------|------------| +| FadeIn | FadeScroll | Flash | - | BgFade | +| ArcIn | ArcScroll | - | - | - | +| SpinIn | SpinScroll | Spin | SpinMouse | BgRotate | +| BounceIn | - | Bounce | BounceMouse | - | +| TiltIn | TiltScroll | - | Tilt3DMouse | - | +| FlipIn | FlipScroll | Flip | - | - | +| GrowIn | GrowScroll | Pulse | ScaleMouse | BgZoom | +| SlideIn | SlideScroll | - | TrackMouse | BgPan | +| BlurIn | BlurScroll | - | BlurMouse | - | +| RevealIn | RevealScroll | - | - | BgReveal | +| - | ParallaxScroll | - | TrackMouse | BgParallax | + +### Combining Triggers + +**On a single element (natively supported):** + +- **Entrance + Ongoing only**: Element can have both entrance and ongoing animations + - Example: BounceIn on viewport entry, then Pulse continuously + +**Requires multiple containers (nested elements):** + +- Entrance + Mouse +- Entrance + Scroll +- Scroll + Mouse +- Any other combination + +These require nested elements with each animation on a separate container. Layout must ensure inner container can animate independently of outer. + +**Multi-element patterns:** + +- **Scroll + Background**: Content element uses FadeScroll, separate background element uses BgParallax +- **Layered parallax**: Multiple sibling elements with TrackMouse at different distances + +--- + +## 4. Presets + +### Entrance Presets + +#### FadeIn + +Visual: Element transitions from invisible to visible. Simple opacity change, no movement. + +Parameters: + +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'FadeIn' } +{ type: 'FadeIn', duration: 300 } // Quick functional fade +``` + +#### ArcIn + +Visual: Element swings in along a curved 3D path, like a door opening. Dramatic, cinematic. + +Parameters: + +- `direction`: top | right | bottom | left (default: left) +- `power`: soft | medium | hard (default: medium) + +**When `power` is set:** controls rotation intensity and easing curve + +```typescript +{ type: 'ArcIn', direction: 'bottom' } +{ type: 'ArcIn', direction: 'left', power: 'hard' } // Dramatic hero entrance +``` + +#### BlurIn + +Visual: Element transitions from blurry to sharp focus while fading in. Soft, dreamy. + +Parameters: + +- `blur`: blur amount in px (default varies) +- `power`: soft | medium | hard + +**When `power` is set:** overrides `blur` (soft=6, medium=25, hard=50) + +```typescript +{ type: 'BlurIn' } +{ type: 'BlurIn', power: 'soft' } +{ type: 'BlurIn', blur: 15 } // Custom blur, no power +``` + +#### BounceIn + +Visual: Element bounces into view with spring physics. Playful, attention-grabbing. + +Parameters: + +- `direction`: top | right | bottom | left | center (default: top) +- `power`: soft | medium | hard (default: soft) +- `distanceFactor`: 1-4 (default: 1) + +**When `power` is set:** overrides `distanceFactor` (soft=1, medium=2, hard=3) + +```typescript +{ type: 'BounceIn' } +{ type: 'BounceIn', direction: 'center', power: 'medium' } // Reward popup +{ type: 'BounceIn', distanceFactor: 2.5 } // Custom distance, no power +``` + +#### CircleIn + +Visual: Circular mask expanding from center to reveal element. Geometric, spotlight-like. + +Parameters: + +- `direction`: in | out (default: in) +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'CircleIn', direction: 'in' } +``` + +#### CurveIn + +Visual: Alternative curved 3D motion path. Similar to ArcIn with different trajectory. + +Parameters: + +- `direction`: left | right +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'CurveIn', direction: 'left' } +``` + +#### DropIn + +Visual: Falls from above with subtle scale/bounce on landing. Gravity-like, natural. + +Parameters: + +- `power`: soft | medium | hard +- `initialScale`: starting scale (default varies) + +**When `power` is set:** overrides `initialScale` and easing (soft: 1.2/cubicInOut, medium: 1.6/quintInOut, hard: 2/backOut) + +```typescript +{ type: 'DropIn' } +{ type: 'DropIn', power: 'medium' } +``` + +#### ExpandIn + +Visual: Expands outward from a point. Growing, revealing emergence. + +Parameters: + +- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center +- `power`: soft | medium | hard +- `initialScale`: starting scale + +**When `power` is set:** controls scale and easing intensity + +```typescript +{ type: 'ExpandIn', direction: 'center' } +{ type: 'ExpandIn', direction: 'bottom-left', power: 'hard' } +``` + +#### FlipIn + +Visual: 3D card flip rotation to reveal element. Dramatic, card-like metaphor. + +Parameters: + +- `direction`: top | right | bottom | left +- `power`: soft | medium | hard +- `initialRotate`: starting rotation degrees + +**When `power` is set:** overrides `initialRotate` (soft=45, medium=90, hard=270) + +```typescript +{ type: 'FlipIn', direction: 'left' } +{ type: 'FlipIn', direction: 'top', power: 'hard' } +``` + +#### FloatIn + +Visual: Gentle floating/drifting entrance. Ethereal, light, dreamy. + +Parameters: + +- `direction`: top | right | bottom | left +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'FloatIn', direction: 'bottom' } +``` + +#### FoldIn + +Visual: Paper-folding 3D effect. Origami-like, creative. + +Parameters: + +- `direction`: top | right | bottom | left +- `power`: soft | medium | hard +- `initialRotate`: starting rotation degrees + +**When `power` is set:** overrides `initialRotate` (soft=35, medium=60, hard=90) + +```typescript +{ type: 'FoldIn', direction: 'left' } +``` + +#### GlideIn + +Visual: Smooth 2D glide from direction with angle control. Clean, directional. + +Parameters: + +- `direction`: angle in degrees (0-360) +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `power`: soft | medium | hard +- `startFromOffScreen`: boolean + +**When `power` is set:** controls easing curve intensity + +```typescript +{ type: 'GlideIn', direction: 180, distance: { value: 100, type: 'px' } } +``` + +#### GlitchIn + +Visual: Digital glitch/distortion effect. Edgy, tech-inspired. + +Parameters: + +- `direction`: angle in degrees +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `power`: soft | medium | hard +- `startFromOffScreen`: boolean + +**When `power` is set:** controls glitch intensity + +```typescript +{ type: 'GlitchIn', direction: 0, distance: { value: 50, type: 'px' } } +``` + +#### GrowIn + +Visual: Scale from small to full size. Expanding, emerging. + +Parameters: + +- `direction`: angle in degrees +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `power`: soft | medium | hard +- `initialScale`: starting scale (0-1) + +**When `power` is set:** controls scale and easing intensity + +```typescript +{ type: 'GrowIn', direction: 0, distance: { value: 0, type: 'px' } } +``` + +#### PunchIn + +Visual: Corner-based scale with energy and impact. Punchy, attention-grabbing. + +Parameters: + +- `direction`: top-left | top-right | bottom-left | bottom-right | center +- `power`: soft | medium | hard + +**When `power` is set:** controls easing curve (soft=sineIn, medium=quadIn, hard=quintIn) + +```typescript +{ type: 'PunchIn', direction: 'center' } +{ type: 'PunchIn', direction: 'bottom-right', power: 'hard' } +``` + +#### RevealIn + +Visual: Directional clip/mask reveal like a curtain opening. Theatrical. + +Parameters: + +- `direction`: top | right | bottom | left +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'RevealIn', direction: 'left' } +``` + +#### ShapeIn + +Visual: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise. + +Parameters: + +- `shape`: circle | ellipse | rectangle | diamond | window +- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'ShapeIn', shape: 'circle', direction: 'center' } +{ type: 'ShapeIn', shape: 'diamond', direction: 'top' } +``` + +#### ShuttersIn + +Visual: Venetian blind strip reveal. Segmented, rhythmic. + +Parameters: + +- `direction`: top | right | bottom | left +- `shutters`: number of strips +- `staggered`: boolean (animate strips sequentially) +- `power`: soft | medium | hard + +**When `power` is set:** controls easing curve intensity + +```typescript +{ type: 'ShuttersIn', direction: 'left', shutters: 5, staggered: true } +``` + +#### SlideIn + +Visual: Straight movement from direction. Clean, simple, versatile. + +Parameters: + +- `direction`: top | right | bottom | left +- `power`: soft | medium | hard +- `initialTranslate`: starting offset + +**When `power` is set:** controls easing curve intensity + +```typescript +{ type: 'SlideIn', direction: 'bottom' } +{ type: 'SlideIn', direction: 'left', power: 'soft' } +``` + +#### SpinIn + +Visual: Rotating entrance with spin. Dynamic, playful. + +Parameters: + +- `direction`: clockwise | counter-clockwise +- `spins`: number of rotations +- `power`: soft | medium | hard +- `initialScale`: starting scale + +**When `power` is set:** controls easing curve intensity + +```typescript +{ type: 'SpinIn', direction: 'clockwise', spins: 1 } +``` + +#### TiltIn + +Visual: 3D tilt into view. Subtle depth, elegant perspective. + +Parameters: + +- `direction`: left | right +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'TiltIn', direction: 'left' } +``` + +#### TurnIn + +Visual: Corner-pivot 3D rotation. Complex, dramatic, premium. + +Parameters: + +- `direction`: top-left | top-right | bottom-left | bottom-right +- `power`: soft | medium | hard +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'TurnIn', direction: 'bottom-left' } +``` + +#### WinkIn + +Visual: Split-in-half reveal from center. Unique, eye-like opening. + +Parameters: + +- `direction`: vertical | horizontal +- `duration`: 0-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'WinkIn', direction: 'vertical' } +``` + +--- + +### Scroll Presets + +#### ParallaxScroll + +Visual: Element moves slower/faster than scroll, creating depth illusion. + +Parameters: + +- `speed`: -1 to 1 (default: 0.5) — positive = same direction, slower; negative = opposite direction +- `range`: continuous + +```typescript +{ type: 'ParallaxScroll' } +{ type: 'ParallaxScroll', speed: 0.3 } // Subtle depth +{ type: 'ParallaxScroll', speed: -0.2 } // Reverse parallax +``` + +#### FadeScroll + +Visual: Opacity transition tied to scroll. Fade in on enter, out on exit. + +Parameters: + +- `range`: in | out (required) +- `opacity`: 0-1 (the "other" opacity value) +- `start`: 0-100% scroll position +- `end`: 0-100% scroll position + +```typescript +{ type: 'FadeScroll', range: 'in' } +{ type: 'FadeScroll', range: 'out' } +{ type: 'FadeScroll', range: 'in', start: 0, end: 30 } // Quick fade +``` + +#### ArcScroll + +Visual: 3D tilt/rotation as user scrolls. Dramatic, cinematic. + +Parameters: + +- `direction`: vertical | horizontal +- `range`: in | out | continuous + +```typescript +{ type: 'ArcScroll', direction: 'vertical' } +{ type: 'ArcScroll', direction: 'horizontal', range: 'in' } +``` + +#### BlurScroll + +Visual: Blur/unblur effect controlled by scroll. Focus transitions. + +Parameters: + +- `power`: soft | medium | hard +- `range`: in | out | continuous +- `blur`: blur amount in px + +**When `power` is set:** overrides `blur` (soft=6, medium=25, hard=50) + +```typescript +{ type: 'BlurScroll', range: 'in' } +{ type: 'BlurScroll', range: 'out', power: 'medium' } +``` + +#### FlipScroll + +Visual: Full 3D card flip driven by scroll. Dramatic rotation. + +Parameters: + +- `direction`: vertical | horizontal +- `power`: soft | medium | hard +- `range`: in | out | continuous +- `rotate`: rotation degrees + +**When `power` is set:** overrides `rotate` (soft=60, medium=120, hard=420) + +```typescript +{ type: 'FlipScroll', direction: 'horizontal' } +{ type: 'FlipScroll', direction: 'vertical', range: 'in' } +``` + +#### GrowScroll + +Visual: Scale up as element enters viewport. + +Parameters: + +- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center +- `power`: soft | medium | hard +- `range`: in | out | continuous +- `scale`: target scale +- `speed`: animation speed + +**When `power` is set:** overrides scale range (soft: 0.8-1.2, medium: 0.3-1.7, hard: 0-4) + +```typescript +{ type: 'GrowScroll', direction: 'center' } +{ type: 'GrowScroll', direction: 'center', range: 'in' } +``` + +#### ShrinkScroll + +Visual: Scale down as element exits viewport. + +Parameters: + +- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center +- `power`: soft | medium | hard +- `range`: in | out | continuous +- `scale`: target scale +- `speed`: animation speed + +**When `power` is set:** overrides scale range (soft: 1.2-0.8, medium: 1.7-0.3, hard: 3.5-0) + +```typescript +{ type: 'ShrinkScroll', direction: 'center', range: 'out' } +``` + +#### MoveScroll + +Visual: Translation movement on scroll in any direction. + +Parameters: + +- `angle`: 0-360 degrees +- `power`: soft | medium | hard +- `range`: in | out | continuous +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } + +**When `power` is set:** overrides `distance` (soft=150px, medium=400px, hard=800px) + +```typescript +{ type: 'MoveScroll', angle: 90, distance: { value: 100, type: 'px' } } +``` + +#### PanScroll + +Visual: Horizontal or vertical panning tied to scroll. + +Parameters: + +- `direction`: left | right +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `startFromOffScreen`: boolean +- `range`: in | out | continuous + +```typescript +{ type: 'PanScroll', direction: 'left', distance: { value: 200, type: 'px' }, startFromOffScreen: false } +``` + +#### RevealScroll + +Visual: Clip-based directional reveal on scroll. + +Parameters: + +- `direction`: top | right | bottom | left +- `range`: in | out | continuous + +```typescript +{ type: 'RevealScroll', direction: 'left' } +{ type: 'RevealScroll', direction: 'bottom', range: 'in' } +``` + +#### ShapeScroll + +Visual: Shape mask reveal controlled by scroll. + +Parameters: + +- `shape`: circle | ellipse | rectangle | diamond | window +- `range`: in | out | continuous +- `power`: soft | medium | hard +- `intensity`: 0-1 + +**When `power` is set:** overrides clipPath intensity (varies by shape) + +```typescript +{ type: 'ShapeScroll', shape: 'circle' } +``` + +#### ShuttersScroll + +Visual: Venetian blind strips revealing on scroll. + +Parameters: + +- `direction`: top | right | bottom | left +- `shutters`: number of strips +- `staggered`: boolean +- `range`: in | out | continuous + +```typescript +{ type: 'ShuttersScroll', direction: 'left', shutters: 5, staggered: true } +``` + +#### SkewPanScroll + +Visual: Panning with skew distortion effect. + +Parameters: + +- `direction`: left | right +- `range`: in | out | continuous +- `power`: soft | medium | hard +- `skew`: skew angle + +**When `power` is set:** overrides `skew` (soft=10, medium=17, hard=24) + +```typescript +{ type: 'SkewPanScroll', direction: 'left' } +``` + +#### SlideScroll + +Visual: Slide movement tied to scroll position. + +Parameters: + +- `direction`: top | right | bottom | left +- `range`: in | out | continuous + +```typescript +{ type: 'SlideScroll', direction: 'bottom' } +{ type: 'SlideScroll', direction: 'left', range: 'in' } +``` + +#### Spin3dScroll + +Visual: 3D rotation around axis on scroll. + +Parameters: + +- `range`: in | out | continuous +- `power`: soft | medium | hard +- `rotate`: rotation degrees +- `speed`: animation speed + +**When `power` is set:** overrides rotation and travel (soft: 45deg/0, medium: 100deg/0.5, hard: 200deg/1) + +```typescript +{ type: 'Spin3dScroll' } +{ type: 'Spin3dScroll', range: 'continuous' } +``` + +#### SpinScroll + +Visual: 2D rotation driven by scroll. + +Parameters: + +- `direction`: clockwise | counter-clockwise +- `spins`: number of rotations +- `range`: in | out | continuous +- `power`: soft | medium | hard +- `scale`: scale factor + +**When `power` is set:** overrides `scale` (soft=1, medium=0.7, hard=0.4) + +```typescript +{ type: 'SpinScroll', direction: 'clockwise', spins: 1 } +``` + +#### StretchScroll + +Visual: Stretch/squeeze deformation on scroll. + +Parameters: + +- `power`: soft | medium | hard +- `range`: in | out | continuous +- `stretch`: stretch amount + +**When `power` is set:** overrides scaleX/scaleY (soft: 0.8/1.2, medium: 0.6/1.5, hard: 0.4/2) + +```typescript +{ type: 'StretchScroll' } +{ type: 'StretchScroll', power: 'medium' } +``` + +#### TiltScroll + +Visual: 3D tilt effect as user scrolls. Subtle perspective. + +Parameters: + +- `direction`: left | right +- `range`: in | out | continuous +- `power`: soft | medium | hard +- `distance`: tilt distance + +**When `power` is set:** overrides `distance` (soft=0, medium=0.5, hard=1) + +```typescript +{ type: 'TiltScroll', direction: 'left' } +``` + +#### TurnScroll + +Visual: Corner-pivot 3D rotation on scroll. + +Parameters: + +- `direction`: left | right +- `spin`: clockwise | counter-clockwise +- `range`: in | out | continuous +- `power`: soft | medium | hard +- `scale`: scale factor + +**When `power` is set:** overrides scale range (soft: 1/1, medium: 0.7/1.3, hard: 0.4/1.6) + +```typescript +{ type: 'TurnScroll', direction: 'left', spin: 'clockwise' } +``` + +--- + +### Ongoing Presets + +#### Pulse + +Visual: Gentle scale oscillation, heartbeat-like rhythm. Subtle, universal. + +Parameters: + +- `power`: soft | medium | hard (default: soft) +- `intensity`: 0-1 (default: 0) + +**When `power` is set:** overrides `intensity`/pulse magnitude (soft=0, medium=0.06, hard=0.12) + +```typescript +{ type: 'Pulse' } +{ type: 'Pulse', power: 'medium' } // Status indicator +{ type: 'Pulse', intensity: 0.04 } // Custom intensity, no power +``` + +#### Bounce + +Visual: Vertical bouncing motion like a ball on trampoline. Playful, energetic. + +Parameters: + +- `power`: soft | medium | hard (default: soft) +- `intensity`: 0-1 (default: 0.3) + +**When `power` is set:** overrides `intensity`/bounce factor (soft=1, medium=2, hard=3) + +```typescript +{ type: 'Bounce' } +{ type: 'Bounce', power: 'medium' } // Playful mascot +``` + +#### Spin + +Visual: Continuous rotation around center. Mechanical, precise. + +Parameters: + +- `direction`: clockwise | counter-clockwise (default: clockwise) +- `power`: soft | medium | hard (default: soft) + +**When `power` is set:** controls easing curve (linear → eased → bouncy) + +```typescript +{ type: 'Spin', direction: 'clockwise' } +{ type: 'Spin', direction: 'clockwise', duration: 1500 } // Loading spinner +``` + +#### Breathe + +Visual: Slow scale in/out like breathing. Calm, organic, meditative. + +Parameters: + +- `direction`: vertical | horizontal | center +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } + +```typescript +{ type: 'Breathe', direction: 'center', distance: { value: 10, type: 'percentage' } } +``` + +#### Flash + +Visual: Opacity pulsing/blinking. Attention, warning indicator. + +Parameters: + +- `duration`: 100-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'Flash' } +``` + +#### Swing + +Visual: Rotation oscillation like a pendulum. Back and forth rhythmic. + +Parameters: + +- `power`: soft | medium | hard +- `swing`: swing angle +- `direction`: top | right | bottom | left + +**When `power` is set:** overrides `swing` angle (soft: 20deg, medium: 40deg, hard: 60deg) + +```typescript +{ type: 'Swing' } +{ type: 'Swing', power: 'medium' } +``` + +#### Wiggle + +Visual: Horizontal shake/wiggle. Side-to-side for attention. + +Parameters: + +- `power`: soft | medium | hard +- `intensity`: 0-1 + +**When `power` is set:** overrides `intensity`/wiggle factor (soft=1, medium=2, hard=4) + +```typescript +{ type: 'Wiggle' } +{ type: 'Wiggle', power: 'soft' } +``` + +#### Flip + +Visual: Periodic 180° flips. Card-like rotation showing front/back. + +Parameters: + +- `direction`: vertical | horizontal +- `power`: soft | medium | hard + +**When `power` is set:** controls easing curve intensity + +```typescript +{ type: 'Flip', direction: 'horizontal' } +``` + +#### Fold + +Visual: 3D folding motion. Paper-like folding and unfolding. + +Parameters: + +- `direction`: top | right | bottom | left +- `power`: soft | medium | hard +- `angle`: fold angle + +**When `power` is set:** overrides `angle` (soft: 15deg, medium: 30deg, hard: 45deg) + +```typescript +{ type: 'Fold', direction: 'left' } +``` + +#### Jello + +Visual: Wobbly elastic deformation. Jiggly, bouncy distortion. + +Parameters: + +- `power`: soft | medium | hard +- `intensity`: 0-1 + +**When `power` is set:** overrides `intensity`/jello factor (soft=1, medium=2, hard=4) + +```typescript +{ type: 'Jello' } +{ type: 'Jello', power: 'medium' } +``` + +#### Rubber + +Visual: Elastic stretch effect. Springy stretching and snapping. + +Parameters: + +- `power`: soft | medium | hard +- `intensity`: 0-1 + +**When `power` is set:** overrides `intensity`/rubber offset (soft=0, medium=0.05, hard=0.1) + +```typescript +{ type: 'Rubber' } +``` + +#### Poke + +Visual: Quick scale bump like being tapped. Brief attention "boop". + +Parameters: + +- `direction`: top | right | bottom | left +- `power`: soft | medium | hard +- `intensity`: 0-1 + +**When `power` is set:** overrides `intensity`/poke factor (soft=1, medium=2, hard=4) + +```typescript +{ type: 'Poke', direction: 'top' } +``` + +#### Cross + +Visual: X-pattern diagonal movement. Unique geometric motion. + +Parameters: + +- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right + +```typescript +{ type: 'Cross', direction: 'top-left' } +``` + +#### DVD + +Visual: Corner-to-corner bounce (DVD screensaver). Nostalgic, retro. + +Parameters: + +- `power`: soft | medium | hard +- `duration`: 100-4000ms (default: 1200) +- `delay`: 0-8000ms (default: 0) + +```typescript +{ type: 'DVD' } +``` + +--- + +### Mouse Presets + +#### Tilt3DMouse + +Visual: Element tilts toward cursor in 3D, like angling a card. Premium, interactive. + +Parameters: + +- `power`: soft | medium | hard (default: medium) +- `angle`: 5-85 degrees (default: 50) +- `perspective`: 200-1000px (default: 800) +- `inverted`: boolean (default: false) + +**When `power` is set:** overrides `angle` and `perspective` (soft: 25/1000, medium: 50/500, hard: 85/200) + +```typescript +{ type: 'Tilt3DMouse' } +{ type: 'Tilt3DMouse', power: 'soft' } // Subtle professional +{ type: 'Tilt3DMouse', angle: 15, perspective: 1000 } // Custom, no power +``` + +#### TrackMouse + +Visual: Element follows cursor position. Floating, parallax-like. + +Parameters: + +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: { value: 250, type: 'px' }) +- `axis`: horizontal | vertical | both (default: both) +- `power`: soft | medium | hard (default: medium) +- `inverted`: boolean (default: false) + +**When `power` is set:** overrides easing (soft=linear, medium=easeOut, hard=hardBackOut) + +```typescript +{ type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } +{ type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'horizontal' } // Background layer +``` + +#### BounceMouse + +Visual: Bouncy/elastic cursor following. Overshoots and wobbles. + +Parameters: + +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: { value: 80, type: 'px' }) +- `axis`: horizontal | vertical | both (default: both) +- `power`: soft | medium | hard +- `inverted`: boolean (default: false) + +**When `power` is set:** controls spring easing behavior + +```typescript +{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } +``` + +#### Track3DMouse + +Visual: Combined translation + 3D rotation following mouse. Complex, immersive. + +Parameters: + +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `angle`: rotation angle +- `axis`: horizontal | vertical | both +- `perspective`: perspective distance +- `power`: soft | medium | hard +- `inverted`: boolean + +**When `power` is set:** overrides `angle` and `perspective` (soft: 25/1000, medium: 50/500, hard: 85/333) + +```typescript +{ type: 'Track3DMouse', distance: { value: 100, type: 'px' }, axis: 'both' } +``` + +#### SpinMouse + +Visual: Rotation following mouse angle. Element spins based on cursor position. + +Parameters: + +- `axis`: horizontal | vertical | both +- `power`: soft | medium | hard +- `inverted`: boolean + +**When `power` is set:** controls rotation intensity and easing + +```typescript +{ type: 'SpinMouse' } +{ type: 'SpinMouse', axis: 'both' } +``` + +#### ScaleMouse + +Visual: Scale based on cursor distance. Grows/shrinks by proximity. + +Parameters: + +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `axis`: horizontal | vertical | both +- `scale`: scale factor +- `power`: soft | medium | hard +- `scaleDirection`: in | out +- `inverted`: boolean + +**When `power` is set:** overrides `scale` (varies by scaleDirection - down: 0.85/0.5/0, up: 1.2/1.6/2.4) + +```typescript +{ type: 'ScaleMouse', distance: { value: 100, type: 'px' }, scaleDirection: 'in' } +``` + +#### SwivelMouse + +Visual: Z-axis rotation following cursor. Gyroscope-like vertical rotation. + +Parameters: + +- `angle`: rotation angle +- `perspective`: perspective distance +- `pivotAxis`: top | bottom | right | left | center-horizontal | center-vertical +- `power`: soft | medium | hard +- `inverted`: boolean + +**When `power` is set:** overrides `angle` and `perspective` (soft: 25/1000, medium: 50/700, hard: 85/300) + +```typescript +{ type: 'SwivelMouse' } +``` + +#### SkewMouse + +Visual: Skew distortion following cursor. Angular distortion. + +Parameters: + +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `angle`: skew angle +- `axis`: horizontal | vertical | both +- `power`: soft | medium | hard +- `inverted`: boolean + +**When `power` is set:** overrides `angle` (soft=10, medium=20, hard=45) + +```typescript +{ type: 'SkewMouse' } +``` + +#### BlurMouse + +Visual: Blur based on cursor distance. Focus/defocus by proximity. + +Parameters: + +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `angle`: angle +- `scale`: scale factor +- `blur`: blur amount +- `perspective`: perspective distance +- `power`: soft | medium | hard +- `inverted`: boolean + +**When `power` is set:** overrides `angle` and `scale` (soft: 0/1, medium: 25/0.7, hard: 65/0.25) + +```typescript +{ type: 'BlurMouse' } +``` + +#### AiryMouse + +Visual: Floating/airy cursor response. Ethereal, gentle drift. + +Parameters: + +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `axis`: horizontal | vertical | both +- `angle`: angle +- `power`: soft | medium | hard +- `inverted`: boolean + +**When `power` is set:** overrides `angle` (soft=10, medium=50, hard=85) + +```typescript +{ type: 'AiryMouse' } +``` + +#### BlobMouse + +Visual: Organic blob-like deformation. Fluid shape distortion. + +Parameters: + +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `scale`: scale factor +- `power`: soft | medium | hard +- `inverted`: boolean + +**When `power` is set:** overrides `scale` (soft=1.2, medium=1.6, hard=2.4) + +```typescript +{ type: 'BlobMouse' } +``` + +#### CustomMouse + +Visual: Configurable custom behavior. For advanced custom implementations. + +```typescript +{ type: 'CustomMouse' } +``` + +--- + +### Background Scroll Presets + +#### BgParallax + +Visual: Background moves slower than scroll, creating depth. Most common bg effect. + +Parameters: + +- `speed`: 0.05-0.95 (default: 0.2) — lower = further away feeling + +```typescript +{ type: 'BgParallax' } +{ type: 'BgParallax', speed: 0.4 } // Noticeable depth +``` + +#### BgZoom + +Visual: Background zooms in/out as user scrolls. Cinematic dolly effect. + +Parameters: + +- `direction`: in | out (default: in) +- `zoom`: 0.1-10 (default: 10) — start lower for subtle effect + +```typescript +{ type: 'BgZoom', direction: 'in' } +{ type: 'BgZoom', direction: 'in', zoom: 3 } // Subtle zoom +``` + +#### BgFade + +Visual: Background opacity changes on scroll. Subtle section transitions. + +Parameters: + +- `range`: in | out (required) +- `start`: 0-100% +- `end`: 0-100% + +```typescript +{ type: 'BgFade', range: 'in' } +{ type: 'BgFade', range: 'out' } +``` + +#### BgFadeBack + +Visual: Fade targeting back layer specifically. For layered backgrounds. + +Parameters: + +- `scale`: scale factor + +```typescript +{ type: 'BgFadeBack' } +``` + +#### BgPan + +Visual: Horizontal/vertical background panning on scroll. + +Parameters: + +- `direction`: left | right +- `speed`: pan speed + +```typescript +{ type: 'BgPan', direction: 'left' } +``` + +#### BgRotate + +Visual: Background rotation driven by scroll. Dynamic, unusual. + +Parameters: + +- `direction`: clockwise | counter-clockwise +- `angle`: rotation angle + +```typescript +{ type: 'BgRotate' } +{ type: 'BgRotate', direction: 'clockwise', angle: 15 } +``` + +#### BgSkew + +Visual: Background skew distortion on scroll. Experimental. + +Parameters: + +- `direction`: clockwise | counter-clockwise +- `angle`: skew angle + +```typescript +{ type: 'BgSkew' } +``` + +#### BgReveal + +Visual: Clip-based background reveal. Theatrical unveiling. + +```typescript +{ type: 'BgReveal' } +``` + +#### BgCloseUp + +Visual: Alternative zoom implementation. Cinematic close-up approach. + +Parameters: + +- `scale`: zoom scale + +```typescript +{ type: 'BgCloseUp' } +``` + +#### BgPullBack + +Visual: Reverse zoom (pulling away). Expansive revealing. + +Parameters: + +- `scale`: zoom scale + +```typescript +{ type: 'BgPullBack' } +``` + +#### BgFake3D + +Visual: Simulated 3D depth layers. Immersive parallax-enhanced depth. + +Parameters: + +- `stretch`: stretch amount +- `zoom`: zoom factor + +```typescript +{ type: 'BgFake3D' } +``` + +#### ImageParallax + +Visual: Parallax for regular `` elements (not CSS backgrounds). + +Parameters: + +- `reverse`: boolean +- `speed`: parallax speed +- `isPage`: boolean + +```typescript +{ type: 'ImageParallax' } +{ type: 'ImageParallax', speed: 0.3 } +``` + +--- + +## 5. Extras + +### Accessibility + +**Always respect `prefers-reduced-motion`:** + +- Check `window.matchMedia('(prefers-reduced-motion: reduce)')` +- Provide FadeIn as fallback for entrance animations +- Disable ongoing/scroll/mouse animations entirely for sensitive users + +**Vestibular triggers to avoid or provide alternatives:** + +- Spinning: SpinIn, Spin, SpinScroll, SpinMouse +- Bouncing: BounceIn, Bounce, BounceMouse +- 3D rotations: ArcIn, FlipIn, ArcScroll, FlipScroll, Tilt3DMouse +- Large-scale parallax: ParallaxScroll, BgParallax at high speeds +- Flashing: Flash (never exceed 3 flashes/second) + +**Duration guidelines:** + +- Functional UI (modals, dropdowns): under 500ms +- Decorative content: up to 1200ms +- Hero moments: up to 2000ms + +### Reduced Motion Fallback Table + +| Original | Fallback | +|----------|----------| +| BounceIn, SpinIn, PunchIn | FadeIn | +| ArcIn, FlipIn, TurnIn | FadeIn | +| GlitchIn | FadeIn | +| Spin, Bounce, Wiggle | Stop or subtle Pulse | +| Flash | Reduce frequency (<3/sec) | +| ParallaxScroll | Static position | +| ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | +| BgParallax, BgZoom | Static background | +| All mouse animations | Static state | + +### Stagger Patterns + +For lists/grids, apply increasing `delay` values: + +```typescript +// List items with 100ms stagger +items.forEach((item, i) => ({ + type: 'FadeIn', + delay: i * 100 +})) + +// Faster stagger (50ms) +items.forEach((item, i) => ({ + type: 'SlideIn', + direction: 'bottom', + delay: i * 50 +})) +``` + +### Performance Notes + +- **Scroll animations run continuously**: use sparingly, test on low-end devices +- **Mouse animations calculate on every mousemove**: limit to 1-3 elements +- **Background animations are heavy**: avoid multiple simultaneous bg effects +- **3D transforms require GPU**: can cause jank on older devices +- **Prefer `transform` and `opacity`**: these are GPU-accelerated + +### Combining Animations + +**Single element (natively supported):** + +- Entrance + Ongoing only: `{ entrance: 'BounceIn', ongoing: 'Pulse' }` + +**Requires nested containers:** + +- Entrance + Mouse: Outer container has entrance, inner has mouse effect +- Entrance + Scroll: Separate containers for each +- Any other cross-trigger combination + +**Separate elements:** + +- Scroll + Background: Content element with FadeScroll, background element with BgParallax + +**Invalid (same trigger type on same element):** + +- Two entrance animations +- Multiple scroll animations +- Multiple ongoing animations + +### Common Patterns + +**Card reveal on scroll:** + +```typescript +{ type: 'FadeScroll', range: 'in' } +``` + +**Interactive product card (requires nested containers):** + +```typescript +// Outer container - entrance +{ type: 'FadeIn' } +// Inner container - mouse interaction +{ type: 'Tilt3DMouse', power: 'soft' } +``` + +**Hero with depth (separate elements):** + +```typescript +// Background element +{ type: 'BgParallax', speed: 0.2 } +// Content element +{ type: 'ArcIn', direction: 'bottom', power: 'medium' } +``` + +**Notification badge (single element - entrance + ongoing supported):** + +```typescript +// Same element can have both +{ type: 'BounceIn', direction: 'top', power: 'soft' } // entrance +{ type: 'Pulse', power: 'soft' } // ongoing +``` + +**Loading indicator:** + +```typescript +{ type: 'Spin', direction: 'clockwise', duration: 1500 } +``` diff --git a/packages/motion-presets/rules/presets/scroll.md b/packages/motion-presets/rules/presets/scroll.md index 3a9263fc..96a4941b 100644 --- a/packages/motion-presets/rules/presets/scroll.md +++ b/packages/motion-presets/rules/presets/scroll.md @@ -1,225 +1,52 @@ --- name: Scroll Animations -category: scroll -tags: - [ - scroll, - parallax, - scroll-driven, - viewport, - scroll-reveal, - on-scroll, - scroll-triggered, - storytelling, - progressive, - ] +trigger: scroll --- # Scroll Animations -## Description +Animations tied to scroll position. Can animate in, out, or continuously. -Scroll animations tie element transformations to the user's scroll position. Unlike entrance animations that play once, scroll animations continuously respond to scroll progress—elements can animate in as they enter the viewport, animate out as they leave, or transform throughout the entire scroll range. +## When to Use -Scroll animations create immersive, storytelling experiences where the user's scrolling becomes an active part of the interaction. They're powerful for landing pages, portfolios, and narrative-driven designs. However, they require careful consideration for performance and accessibility. +- Progressive content reveals on scroll +- Parallax depth effects +- Storytelling tied to scroll progress +- De-emphasizing passed content -## Synonyms +## When NOT to Use -scroll-driven animation, scroll-triggered effect, parallax effect, scroll reveal, scroll fade, on-scroll animation, viewport animation, scroll-linked animation, scroll storytelling, progressive reveal, scroll-based transition - -## When to Use Scroll Animations - -- **Progressive content reveals**: Elements fading/sliding in as user scrolls to them -- **Parallax depth effects**: Layered elements moving at different rates -- **Storytelling experiences**: Narrative tied to scroll progress -- **Section transitions**: Effects as user scrolls between sections -- **Emphasis on scroll progress**: Progress indicators, timeline-like reveals -- **De-emphasizing passed content**: Fading out content as user scrolls past - -## When NOT to Use Scroll Animations - -- **One-time entrance effects** → use Entrance animations (more performant) -- **Continuous/looping animations** → use Ongoing animations -- **Mouse-reactive elements** → use Mouse animations -- **Background media** → use Background Scroll animations -- **Mobile-first designs** → scroll animations can be janky on mobile; test carefully -- **Content that must remain readable** → avoid on text-heavy sections - -## Accessibility Considerations - -- **Respect `prefers-reduced-motion`**: Disable scroll animations entirely or use subtle FadeScroll only -- **Vestibular safety**: ParallaxScroll, ArcScroll, FlipScroll, SpinScroll, and Spin3dScroll can trigger motion sickness. Provide alternatives or disable for sensitive users -- **Performance impact**: Scroll animations run continuously; optimize for 60fps. Janky animations are worse than no animations -- **Content accessibility**: Ensure all content is readable without animations. Don't hide critical information behind scroll-triggered reveals -- **Keyboard navigation**: Users navigating with keyboard may not trigger scroll animations in expected ways -- **Duration of scroll range**: Don't make users scroll excessively to reveal content +- One-time entrance → see [Entrance](presets-reference.md#entrance) (more performant) +- Continuous loops → see [Ongoing](presets-reference.md#ongoing) +- Background images → see [Background Scroll](presets-reference.md#background-scroll) ## Available Presets -### ParallaxScroll - -- **Description**: Element moves slower/faster than scroll, creating depth illusion. Like looking through a window where distant objects move slower. -- **Tags**: `parallax`, `depth`, `layered`, `continuous`, `movement`, `distance`, `speed` -- **Synonyms**: parallax effect, scroll parallax, depth scroll, layered scroll, differential scroll, scroll movement - -### FadeScroll - -- **Description**: Opacity transition tied to scroll position. Fade in on enter, fade out on exit. Smooth, cinematic content reveals. -- **Tags**: `fade`, `opacity`, `reveal`, `in`, `out`, `transition`, `subtle` -- **Synonyms**: scroll fade, fade on scroll, opacity scroll, scroll reveal, scroll disappear - -### ArcScroll - -- **Description**: 3D tilt/rotation as user scrolls. Like a card tilting towards or away. Dramatic, cinematic depth effect. -- **Tags**: `3d`, `arc`, `rotation`, `perspective`, `tilt`, `cinematic`, `dramatic` -- **Synonyms**: scroll arc, 3d scroll, tilt scroll, rotation scroll, perspective scroll - -### BlurScroll - -- **Description**: Blur/unblur effect controlled by scroll position. Creates focus/defocus transitions tied to scroll. -- **Tags**: `blur`, `focus`, `defocus`, `soft`, `transition`, `depth` -- **Synonyms**: scroll blur, blur on scroll, focus scroll, defocus scroll, blur transition - -### FlipScroll - -- **Description**: Full 3D card flip driven by scroll. Dramatic rotation revealing content as user scrolls. -- **Tags**: `flip`, `3d`, `rotation`, `card`, `dramatic`, `turn`, `reveal` -- **Synonyms**: scroll flip, 3d flip scroll, card flip scroll, flip on scroll - -### GrowScroll - -- **Description**: Scale up as element enters viewport. Element grows larger tied to scroll progress. -- **Tags**: `grow`, `scale`, `zoom`, `expand`, `size`, `enlarge`, `in` -- **Synonyms**: scroll grow, scale scroll, zoom scroll, grow on scroll, expand scroll - -### ShrinkScroll - -- **Description**: Scale down as element exits viewport. Element shrinks tied to scroll progress. -- **Tags**: `shrink`, `scale`, `reduce`, `minimize`, `size`, `out` -- **Synonyms**: scroll shrink, scale down scroll, shrink on scroll, minimize scroll - -### MoveScroll - -- **Description**: General translation movement on scroll. Move element in any direction tied to scroll position. -- **Tags**: `move`, `translate`, `position`, `movement`, `direction`, `shift` -- **Synonyms**: scroll move, translate scroll, movement scroll, position scroll - -### PanScroll - -- **Description**: Horizontal or vertical panning effect. Element slides across tied to scroll. -- **Tags**: `pan`, `horizontal`, `vertical`, `slide`, `traverse`, `sweep` -- **Synonyms**: scroll pan, pan on scroll, horizontal scroll, sliding scroll - -### RevealScroll - -- **Description**: Clip-based directional reveal on scroll. Content unveils progressively as user scrolls. -- **Tags**: `reveal`, `clip`, `mask`, `directional`, `unveil`, `progressive`, `wipe` -- **Synonyms**: scroll reveal, clip scroll, wipe scroll, unveil scroll, mask reveal scroll - -### ShapeScroll - -- **Description**: Shape mask reveal controlled by scroll. Geometric shapes expanding/contracting on scroll. -- **Tags**: `shape`, `mask`, `geometric`, `circle`, `expand`, `contract` -- **Synonyms**: shape scroll, mask scroll, geometric reveal scroll, shape reveal - -### ShuttersScroll - -- **Description**: Venetian blind strips revealing on scroll. Segmented progressive reveal tied to scroll. -- **Tags**: `shutters`, `blinds`, `strips`, `segmented`, `progressive`, `venetian` -- **Synonyms**: shutters scroll, blind scroll, strip reveal scroll, venetian scroll - -### SkewPanScroll - -- **Description**: Panning with skew distortion effect. Movement plus angular distortion on scroll. -- **Tags**: `skew`, `pan`, `distortion`, `angle`, `movement`, `warp` -- **Synonyms**: skew scroll, skew pan, distortion scroll, angled pan scroll - -### SlideScroll - -- **Description**: Slide movement tied to scroll position. Directional sliding as user scrolls. -- **Tags**: `slide`, `move`, `directional`, `translate`, `shift` -- **Synonyms**: scroll slide, slide on scroll, directional slide scroll - -### Spin3dScroll - -- **Description**: 3D rotation around axis on scroll. Element rotates in 3D space as user scrolls. -- **Tags**: `spin`, `3d`, `rotation`, `axis`, `revolve`, `orbit` -- **Synonyms**: 3d spin scroll, rotation scroll, spin on scroll, 3d rotate scroll - -### SpinScroll - -- **Description**: 2D rotation driven by scroll. Element spins flat as user scrolls. -- **Tags**: `spin`, `rotate`, `2d`, `turn`, `circular` -- **Synonyms**: scroll spin, rotate scroll, 2d spin scroll, turning scroll - -### StretchScroll - -- **Description**: Stretch/squeeze deformation on scroll. Element distorts proportionally tied to scroll. -- **Tags**: `stretch`, `squeeze`, `deform`, `distort`, `elastic`, `proportion` -- **Synonyms**: stretch scroll, squeeze scroll, deform scroll, elastic scroll - -### TiltScroll - -- **Description**: 3D tilt effect as user scrolls. Subtle perspective shift tied to scroll position. -- **Tags**: `tilt`, `3d`, `perspective`, `angle`, `subtle`, `depth` -- **Synonyms**: scroll tilt, 3d tilt scroll, perspective scroll, angle scroll - -### TurnScroll - -- **Description**: Corner-pivot 3D rotation on scroll. Complex rotation with pivot point on scroll. -- **Tags**: `turn`, `3d`, `corner`, `pivot`, `rotation`, `complex` -- **Synonyms**: turn scroll, corner turn scroll, pivot scroll, 3d turn scroll - -## Decision Guide - -### By Effect Type - -- **Opacity**: FadeScroll, BlurScroll -- **Movement/Position**: ParallaxScroll, MoveScroll, PanScroll, SlideScroll -- **Scale**: GrowScroll, ShrinkScroll, StretchScroll -- **3D Rotation**: ArcScroll, FlipScroll, TiltScroll, TurnScroll, Spin3dScroll -- **2D Rotation**: SpinScroll -- **Reveal/Mask**: RevealScroll, ShapeScroll, ShuttersScroll - -### By Use Case - -- **Depth/Layering effects**: ParallaxScroll, MoveScroll (with different speeds) -- **Content reveal**: FadeScroll (in), RevealScroll, GrowScroll -- **Dramatic/Cinematic sections**: ArcScroll, FlipScroll, TiltScroll -- **Storytelling/Timeline**: Multiple presets with coordinated ranges -- **De-emphasize passed content**: FadeScroll (out), ShrinkScroll, BlurScroll (out) -- **Hero sections**: ArcScroll, TiltScroll, GrowScroll - -### Range Modes +See [Scroll Presets](presets-reference.md#scroll-presets) for full details: -Most scroll presets support range modes that control when the animation occurs: +ParallaxScroll, FadeScroll, ArcScroll, BlurScroll, FlipScroll, GrowScroll, ShrinkScroll, MoveScroll, PanScroll, RevealScroll, ShapeScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll -- **`in`**: Animates as element enters viewport (0% → 50% visibility) -- **`out`**: Animates as element exits viewport (50% → 100% visibility) -- **`continuous`**: Animates throughout entire scroll range (0% → 100%) +## Range Modes -Custom `start` and `end` values allow fine-tuning the scroll range. +- `in`: Animates as element enters viewport (0% → 50%) +- `out`: Animates as element exits viewport (50% → 100%) +- `continuous`: Animates throughout entire scroll range -### Reduced Motion Alternatives +## Quick Decision -| Original | Reduced Motion Fallback | -| ----------------------------------- | ------------------------- | -| ParallaxScroll | Disable (static position) | -| ArcScroll, FlipScroll, Spin3dScroll | FadeScroll or disable | -| SpinScroll | Disable | -| TiltScroll, TurnScroll | FadeScroll | -| GrowScroll, ShrinkScroll | FadeScroll | +| Effect Type | Presets | +|-------------|---------| +| Opacity | FadeScroll, BlurScroll | +| Movement | ParallaxScroll, MoveScroll, PanScroll, SlideScroll | +| Scale | GrowScroll, ShrinkScroll | +| 3D Rotation | ArcScroll, FlipScroll, TiltScroll, TurnScroll | +| Reveal/Mask | RevealScroll, ShapeScroll, ShuttersScroll | -### Parallels in Other Categories +## Common Use Cases -| Scroll | Entrance | Ongoing | Background | -| -------------- | -------- | ------- | ---------- | -| FadeScroll | FadeIn | - | BgFade | -| ArcScroll | ArcIn | - | - | -| ParallaxScroll | - | - | BgParallax | -| TiltScroll | TiltIn | - | - | -| FlipScroll | FlipIn | Flip | - | -| GrowScroll | GrowIn | - | BgZoom | -| SpinScroll | SpinIn | Spin | BgRotate | -| RevealScroll | RevealIn | - | BgReveal | -| BlurScroll | BlurIn | - | - | +| Use Case | Recommended | +|----------|-------------| +| Depth/Layering | ParallaxScroll with different speeds | +| Content reveal | FadeScroll (in), RevealScroll | +| Dramatic sections | ArcScroll, FlipScroll, TiltScroll | +| De-emphasize passed | FadeScroll (out), ShrinkScroll | diff --git a/packages/motion-presets/rules/presets/scroll/arc-scroll.md b/packages/motion-presets/rules/presets/scroll/arc-scroll.md deleted file mode 100644 index 1e58638e..00000000 --- a/packages/motion-presets/rules/presets/scroll/arc-scroll.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: ArcScroll -category: scroll ---- - -# ArcScroll - -## Visual Description - -Element tilts and rotates in 3D space as the user scrolls, creating a dramatic cinematic effect similar to ArcIn but driven by scroll position instead of time. The element appears to exist in 3D space, rotating on an axis as scroll progresses. - -**How it looks**: Imagine a trading card slowly tilting as you scroll—it starts tilted away from you and gradually rotates flat, or vice versa. The effect creates depth and dimension, making the element feel like it's pivoting in real space. - -**`direction: 'vertical'`**: Element rotates on the X-axis, tilting forward/backward like a laptop screen opening or closing. - -**`direction: 'horizontal'`**: Element rotates on the Y-axis, tilting left/right like a door swinging open. - -The rotation is tied directly to scroll position, creating a satisfying connection between user input and visual transformation. - -## Parameters - -```typescript -interface ArcScroll { - direction: 'horizontal' | 'vertical'; // default: 'vertical' - range?: 'in' | 'out' | 'continuous'; // default varies - start?: number; // %, scroll position start - end?: number; // %, scroll position end -} -``` - -**Parameter Impact:** - -- `direction`: Determines the rotation axis - - `vertical`: Rotates on X-axis—element tilts forward/backward - - At start: tilted back (top edge away from viewer) - - At end: flat, facing viewer - - Feels like a screen or lid opening toward you - - `horizontal`: Rotates on Y-axis—element tilts left/right - - At start: tilted to one side - - At end: flat, facing viewer - - Feels like a door or panel swinging open -- `range`: When the rotation occurs - - `in`: Rotates from tilted → flat as element enters viewport - - `out`: Rotates from flat → tilted as element exits viewport - - `continuous`: Full rotation range throughout scroll visibility -- `start`/`end`: Fine-tune when rotation begins and completes (0-100) - -## Best Practices - -- **Use on single focal elements**: ArcScroll is dramatic; multiple simultaneous rotations are overwhelming -- **Test performance**: 3D transforms can be expensive; ensure smooth 60fps -- **Consider viewport position**: Element needs to be positioned where rotation is visible during scroll range -- **Pair with complementary content**: Works well with text that doesn't rotate alongside -- **Reduced motion**: Provide FadeScroll or static fallback—3D rotation is a vestibular trigger - -## Examples - -```typescript -// Basic - tilts forward/backward as you scroll -{ type: 'ArcScroll', direction: 'vertical' } - -// Tilts left/right as you scroll -{ type: 'ArcScroll', direction: 'horizontal' } - -// Only rotate while entering viewport -{ type: 'ArcScroll', direction: 'vertical', range: 'in' } - -// Only rotate while exiting viewport -{ type: 'ArcScroll', direction: 'horizontal', range: 'out' } - -// Custom scroll range (rotation completes earlier) -{ type: 'ArcScroll', direction: 'vertical', range: 'in', start: 0, end: 40 } -``` diff --git a/packages/motion-presets/rules/presets/scroll/fade-scroll.md b/packages/motion-presets/rules/presets/scroll/fade-scroll.md deleted file mode 100644 index 53cde26f..00000000 --- a/packages/motion-presets/rules/presets/scroll/fade-scroll.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: FadeScroll -category: scroll ---- - -# FadeScroll - -## Visual Description - -Element's opacity changes in response to scroll position, creating smooth fade-in or fade-out effects as the user scrolls. This is the scroll-driven equivalent of FadeIn—subtle, accessible, and universally applicable. - -**`range: 'in'` mode**: Element starts invisible and gradually becomes visible as it enters the viewport. By the time it reaches the middle of the viewport, it's fully visible. Perfect for revealing content as users scroll to it. - -**`range: 'out'` mode**: Element starts visible and gradually becomes invisible as it exits the viewport. Creates a graceful "dismissal" of content as users scroll past. Good for de-emphasizing passed content. - -The transition is smooth and linear, tied directly to scroll position—not time-based. Scroll faster, and the fade happens faster; scroll slower, and it's more gradual. - -## Parameters - -```typescript -interface FadeScroll { - range: 'in' | 'out'; // default: 'in' - opacity?: number; // 0-1, min: 0, max: 1, step: 0.01, default: 0 - start?: number; // %, min: 0, max: 100, default: 0 (in) or 50 (out) - end?: number; // %, min: 0, max: 100, default: 50 (in) or 100 (out) -} -``` - -**Parameter Impact:** - -- `range`: Direction of the fade effect - - `in`: Fades from invisible → visible as element enters viewport. Element reaches full opacity by the `end` scroll position - - `out`: Fades from visible → invisible as element exits viewport. Element becomes fully transparent by the `end` scroll position -- `opacity`: The "other" opacity value (what it fades from/to) - - `0` (default): Element fades from/to completely invisible - - `0.3-0.5`: Element fades from/to semi-transparent (never fully disappears) - - `1`: No fade effect (element stays visible) -- `start`/`end`: Scroll position range as percentage of element visibility - - For `in`: Default 0-50 means fade completes when element reaches viewport center - - For `out`: Default 50-100 means fade starts from viewport center until element leaves - - Adjust for slower/faster fades: wider range = slower fade - -## Best Practices - -- **`range: 'in'` is most common**: Revealing content as users scroll to it is the primary use case -- **Don't fade critical content**: Important information should be visible without needing to scroll to it -- **Combine in + out**: Apply both modes for content that fades in and out as user scrolls past -- **Adjust start/end for timing**: Want fade to complete earlier? Use `end: 30`. Later? Use `end: 70` -- **Safe for reduced motion**: FadeScroll is subtle enough to keep even with `prefers-reduced-motion`, though disabling is also fine - -## Examples - -```typescript -// Basic - fades in as enters viewport -{ type: 'FadeScroll', range: 'in' } - -// Fade out as exits viewport -{ type: 'FadeScroll', range: 'out' } - -// Slower fade in (completes later) -{ type: 'FadeScroll', range: 'in', start: 0, end: 70 } - -// Quick fade in (completes earlier) -{ type: 'FadeScroll', range: 'in', start: 0, end: 25 } - -// Fade to semi-transparent (not fully invisible) -{ type: 'FadeScroll', range: 'out', opacity: 0.3 } - -// Combined fade in and out (use two animations or trigger logic) -// As element enters: -{ type: 'FadeScroll', range: 'in' } -// As element exits: -{ type: 'FadeScroll', range: 'out' } -``` diff --git a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md b/packages/motion-presets/rules/presets/scroll/parallax-scroll.md deleted file mode 100644 index 1cd64d9b..00000000 --- a/packages/motion-presets/rules/presets/scroll/parallax-scroll.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: ParallaxScroll -category: scroll ---- - -# ParallaxScroll - -## Visual Description - -Element moves at a different rate than the page scroll, creating an illusion of depth and dimension. When you scroll the page, this element moves slower (or faster, or even opposite) compared to the rest of the content, making it feel like it exists on a different layer—closer or further away. - -**How it works**: As the user scrolls, the element's vertical position is modified based on the `speed` parameter. A speed of 0.5 means the element moves at half the scroll rate (appears further away). A negative speed means the element moves opposite to scroll direction. - -**The visual effect**: Imagine looking through a car window—distant mountains move slowly while nearby trees zip past. ParallaxScroll recreates this depth perception. Faster-moving elements feel closer; slower elements feel further away. - -This is a continuous effect that runs throughout the entire time the element is in the viewport, creating an immersive, layered experience. - -## Parameters - -```typescript -interface ParallaxScroll { - speed?: number; // ratio, min: -1, max: 1, step: 0.05, default: 0.5 - range?: 'continuous'; // only continuous supported - start?: number; // %, min: 0, max: 0, default: 0 - end?: number; // %, min: 100, max: 100, default: 100 -} -``` - -**Parameter Impact:** - -- `speed`: The core parameter—determines movement rate relative to scroll - - **Positive values (0.1 to 1)**: Element moves in same direction as scroll, but slower - - `0.1-0.3`: Subtle parallax, element feels slightly "behind" - - `0.4-0.6`: Noticeable depth effect (0.5 default is ideal) - - `0.7-0.9`: Strong parallax, element moves almost with scroll - - **Negative values (-1 to -0.1)**: Element moves opposite to scroll direction - - Creates unusual "floating against current" effect - - Use sparingly—can be disorienting - - **0**: No movement (element scrolls normally with page) -- `range`: Only `continuous` is supported—effect runs throughout viewport visibility -- `start`/`end`: Fixed at 0-100, covering full scroll range - -## Best Practices - -- **Layer multiple elements**: Create depth by applying different speeds to different elements (e.g., background: 0.2, midground: 0.5, foreground: 0.8) -- **Subtle is usually better**: Start with `speed: 0.3` and adjust—strong parallax can cause motion sickness -- **Test on mobile**: Parallax can be janky on mobile devices; consider disabling or reducing -- **Don't use on text**: Moving text while scrolling is hard to read -- **Combine with position**: Elements should be positioned appropriately to have room to move -- **Reduced motion**: Disable entirely for `prefers-reduced-motion` - -## Examples - -```typescript -// Basic - element moves at half scroll speed -{ type: 'ParallaxScroll' } - -// Subtle background element (feels very far away) -{ type: 'ParallaxScroll', speed: 0.2 } - -// Strong parallax (noticeable depth) -{ type: 'ParallaxScroll', speed: 0.7 } - -// Reverse parallax (floats against scroll direction) -{ type: 'ParallaxScroll', speed: -0.3 } - -// Layered depth effect (apply to different elements) -// Background layer -{ type: 'ParallaxScroll', speed: 0.2 } -// Midground layer -{ type: 'ParallaxScroll', speed: 0.5 } -// Foreground decorative elements -{ type: 'ParallaxScroll', speed: 0.8 } -``` From f03fc505ca42469fbc099e9e37445f30a338266d Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Wed, 28 Jan 2026 14:15:37 +0200 Subject: [PATCH 08/20] Document background scroll DOM structure requirements - Clarify that background scroll requires data-motion-part attributes - Note that these animate DOM elements via transforms, not CSS background-position - Add ImageParallax exception for regular img elements --- packages/motion-presets/rules/presets/PLAN.md | 10 +++++- .../rules/presets/background-scroll.md | 31 +++++++------------ .../rules/presets/presets-reference.md | 22 +++++++------ 3 files changed, 33 insertions(+), 30 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 7194664d..59519a4d 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -30,7 +30,7 @@ rules/presets/ | scroll | Scroll position binding | Tied to scroll progress (0-100%) | | ongoing | Continuous loop | Runs indefinitely until stopped | | mouse | Pointer position binding | Desktop only, real-time response | -| background-scroll | Scroll position for CSS backgrounds | Specifically for background media | +| background-scroll | Scroll + `data-motion-part` targeting | Requires structured DOM (see below) | **Important:** Entrance animations only support the `viewEnter` trigger natively. For click, toggle, or other event-based triggers, implement triggering logic separately. @@ -44,6 +44,14 @@ rules/presets/ | Scroll + Mouse | Requires nested containers | | Any other combination | Requires multiple containers | +### Background Scroll Requirements + +Requires `data-motion-part` attributes: `BG_LAYER`, `BG_MEDIA`, `BG_IMG` + +Animates DOM elements via CSS transforms (not `background-position`). + +**Exception:** `ImageParallax` works on regular `` elements without `data-motion-part`. + ### Common Parameters **All Entrance presets:** diff --git a/packages/motion-presets/rules/presets/background-scroll.md b/packages/motion-presets/rules/presets/background-scroll.md index 85ba7a3b..73ec2968 100644 --- a/packages/motion-presets/rules/presets/background-scroll.md +++ b/packages/motion-presets/rules/presets/background-scroll.md @@ -5,29 +5,29 @@ trigger: backgroundScroll # Background Scroll Animations -Scroll animations specifically for CSS background images/videos. +Scroll animations for structured background media components. Animates DOM elements via CSS transforms (not `background-position`). + +## DOM Structure Required + +Requires `data-motion-part` attributes: `BG_LAYER`, `BG_MEDIA`, `BG_IMG` ## When to Use - Hero sections with background depth -- Full-width section backgrounds +- Full-width section backgrounds with `data-motion-part` structure - Cinematic storytelling - Section transitions ## When NOT to Use -- Regular content elements → see [Scroll](presets-reference.md#scroll) -- Non-media backgrounds (solid colors) -- Multiple animated backgrounds +- Regular content elements → use [Scroll](presets-reference.md#scroll-presets) +- Elements without `data-motion-part` structure +- Simple CSS `background-image` (no DOM structure to animate) - Mobile with performance concerns ## Available Presets -See [Background Scroll Presets](presets-reference.md#background-scroll-presets) for full details: - -BgParallax, BgZoom, BgFade, BgFadeBack, BgPan, BgRotate, BgSkew, BgReveal, BgCloseUp, BgPullBack, BgFake3D, ImageParallax - -## Quick Decision +See [Background Scroll Presets](presets-reference.md#background-scroll-presets) for details. | Effect Type | Presets | | ------------- | --------- | @@ -37,15 +37,6 @@ BgParallax, BgZoom, BgFade, BgFadeBack, BgPan, BgRotate, BgSkew, BgReveal, BgClo | Rotation | BgRotate | | Reveal | BgReveal | -## Common Use Cases - -| Use Case | Recommended | -| ---------- | ------------- | -| Depth/Immersion | BgParallax (speed: 0.2-0.4) | -| Cinematic reveals | BgZoom, BgCloseUp, BgReveal | -| Section transitions | BgFade | -| Creative/Experimental | BgSkew, BgRotate | - ## Note -`ImageParallax` is for regular `` elements, not CSS backgrounds. +`ImageParallax` works on regular `` elements without `data-motion-part` structure. diff --git a/packages/motion-presets/rules/presets/presets-reference.md b/packages/motion-presets/rules/presets/presets-reference.md index 8d483eb0..6eedfcba 100644 --- a/packages/motion-presets/rules/presets/presets-reference.md +++ b/packages/motion-presets/rules/presets/presets-reference.md @@ -110,23 +110,25 @@ Animations that respond to cursor position. Desktop-only. ### Background Scroll -Scroll animations specifically for CSS background images/videos. +Scroll animations for structured background media components. Animates DOM elements via CSS transforms (not `background-position`). + +**Requires `data-motion-part` attributes:** `BG_LAYER`, `BG_MEDIA`, `BG_IMG` **When to use:** - Hero sections with background depth -- Full-width section backgrounds -- Cinematic storytelling -- Section transitions +- Full-width section backgrounds with `data-motion-part` structure **When NOT to use:** - Regular content elements → use scroll -- Non-media backgrounds (solid colors) -- Multiple animated backgrounds (performance) +- Elements without `data-motion-part` structure +- Simple CSS `background-image` (no DOM structure) **Available presets:** BgParallax, BgZoom, BgFade, BgFadeBack, BgPan, BgRotate, BgSkew, BgReveal, BgCloseUp, BgPullBack, BgFake3D, ImageParallax +**Note:** `ImageParallax` works on regular `` elements without `data-motion-part` structure. + --- ## Common Parameters @@ -171,7 +173,7 @@ Many presets support `power: 'soft' | 'medium' | 'hard'`. ### By Tone | Tone | Entrance | Scroll | Ongoing | Mouse | -|------|----------|--------|---------|-------| +| ------ | ---------- | -------- | --------- | ------- | | Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (soft), Breathe | Tilt3DMouse (soft), TrackMouse | | Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | | Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | @@ -180,7 +182,7 @@ Many presets support `power: 'soft' | 'medium' | 'hard'`. ### By Use Case | Use Case | Recommended Presets | -|----------|---------------------| +| ---------- | --------------------- | | Hero sections | ArcIn, ExpandIn, FloatIn, RevealIn + BgParallax, BgZoom | | Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | | List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | @@ -196,7 +198,7 @@ Many presets support `power: 'soft' | 'medium' | 'hard'`. Effects with similar visual results across triggers: | Entrance | Scroll | Ongoing | Mouse | Background | -|----------|--------|---------|-------|------------| +| ---------- | -------- | --------- | ------- | ------------ | | FadeIn | FadeScroll | Flash | - | BgFade | | ArcIn | ArcScroll | - | - | - | | SpinIn | SpinScroll | Spin | SpinMouse | BgRotate | @@ -1351,6 +1353,8 @@ Visual: Configurable custom behavior. For advanced custom implementations. ### Background Scroll Presets +**Requires DOM structure with `data-motion-part` attributes** (`BG_LAYER`, `BG_MEDIA`, `BG_IMG`). See [Background Scroll trigger](#background-scroll) for structure details. + #### BgParallax Visual: Background moves slower than scroll, creating depth. Most common bg effect. From 2e907a59613efcfe2aef3478c7d5f8e8018828bb Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Thu, 29 Jan 2026 09:38:40 +0200 Subject: [PATCH 09/20] fix md lint --- packages/motion-presets/rules/presets/presets-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/motion-presets/rules/presets/presets-reference.md b/packages/motion-presets/rules/presets/presets-reference.md index 6eedfcba..0094d7fa 100644 --- a/packages/motion-presets/rules/presets/presets-reference.md +++ b/packages/motion-presets/rules/presets/presets-reference.md @@ -18,7 +18,7 @@ This document is a comprehensive reference for Interact motion presets. Use it t ### Quick Trigger Lookup | User Intent | Trigger | Notes | -|-------------|---------|-------| +| ------------- | --------- | ------- | | "animate when element enters viewport", "reveal on scroll into view" | entrance | viewEnter trigger (intersection observer) | | "animate based on scroll position", "parallax", "scroll-driven" | scroll | Tied to scroll progress | | "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely | @@ -1538,7 +1538,7 @@ Parameters: ### Reduced Motion Fallback Table | Original | Fallback | -|----------|----------| +| ---------- | ---------- | | BounceIn, SpinIn, PunchIn | FadeIn | | ArcIn, FlipIn, TurnIn | FadeIn | | GlitchIn | FadeIn | From de32391dd5f9f4a50ac8ae2ec843b68147fc4b7b Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Thu, 29 Jan 2026 09:47:43 +0200 Subject: [PATCH 10/20] fixed lint issues - ran 'yarn format' on all md files --- packages/motion-presets/rules/presets/PLAN.md | 140 +++++++-------- .../rules/presets/background-scroll.md | 14 +- .../motion-presets/rules/presets/entrance.md | 24 +-- .../motion-presets/rules/presets/mouse.md | 20 +-- .../motion-presets/rules/presets/ongoing.md | 26 +-- .../rules/presets/presets-reference.md | 166 +++++++++++------- .../motion-presets/rules/presets/scroll.md | 26 +-- 7 files changed, 224 insertions(+), 192 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 59519a4d..8f2fc3a6 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -24,25 +24,25 @@ rules/presets/ ### Trigger Mechanisms -| Trigger | Mechanism | Notes | -| --------- | ----------- | ------- | -| entrance | `viewEnter` (intersection observer) | Plays once when element enters viewport | -| scroll | Scroll position binding | Tied to scroll progress (0-100%) | -| ongoing | Continuous loop | Runs indefinitely until stopped | -| mouse | Pointer position binding | Desktop only, real-time response | -| background-scroll | Scroll + `data-motion-part` targeting | Requires structured DOM (see below) | +| Trigger | Mechanism | Notes | +| ----------------- | ------------------------------------- | --------------------------------------- | +| entrance | `viewEnter` (intersection observer) | Plays once when element enters viewport | +| scroll | Scroll position binding | Tied to scroll progress (0-100%) | +| ongoing | Continuous loop | Runs indefinitely until stopped | +| mouse | Pointer position binding | Desktop only, real-time response | +| background-scroll | Scroll + `data-motion-part` targeting | Requires structured DOM (see below) | **Important:** Entrance animations only support the `viewEnter` trigger natively. For click, toggle, or other event-based triggers, implement triggering logic separately. ### Combining Animations -| Combination | Support | -| ------------- | --------- | -| Entrance + Ongoing | Single element (native support) | -| Entrance + Mouse | Requires nested containers | -| Entrance + Scroll | Requires nested containers | -| Scroll + Mouse | Requires nested containers | -| Any other combination | Requires multiple containers | +| Combination | Support | +| --------------------- | ------------------------------- | +| Entrance + Ongoing | Single element (native support) | +| Entrance + Mouse | Requires nested containers | +| Entrance + Scroll | Requires nested containers | +| Scroll + Mouse | Requires nested containers | +| Any other combination | Requires multiple containers | ### Background Scroll Requirements @@ -78,70 +78,70 @@ Animates DOM elements via CSS transforms (not `background-position`). ### Entrance Presets -| Preset | Power Controls | soft | medium | hard | -| -------- | --------------- | ------ | -------- | ------ | -| ArcIn | easing curve | subtle | balanced | dramatic | -| BlurIn | blur | 6px | 25px | 50px | -| BounceIn | distanceFactor | 1 | 2 | 3 | -| DropIn | scale, easing | 1.2/cubicInOut | 1.6/quintInOut | 2/backOut | -| ExpandIn | scale, easing | subtle | balanced | dramatic | -| FlipIn | initialRotate | 45deg | 90deg | 270deg | -| FoldIn | initialRotate | 35deg | 60deg | 90deg | -| GlideIn | easing curve | subtle | balanced | dramatic | -| GlitchIn | glitch intensity | subtle | balanced | dramatic | -| GrowIn | scale, easing | subtle | balanced | dramatic | -| PunchIn | easing | sineIn | quadIn | quintIn | -| ShuttersIn | easing curve | subtle | balanced | dramatic | -| SlideIn | easing curve | subtle | balanced | dramatic | -| SpinIn | easing curve | subtle | balanced | dramatic | +| Preset | Power Controls | soft | medium | hard | +| ---------- | ---------------- | -------------- | -------------- | --------- | +| ArcIn | easing curve | subtle | balanced | dramatic | +| BlurIn | blur | 6px | 25px | 50px | +| BounceIn | distanceFactor | 1 | 2 | 3 | +| DropIn | scale, easing | 1.2/cubicInOut | 1.6/quintInOut | 2/backOut | +| ExpandIn | scale, easing | subtle | balanced | dramatic | +| FlipIn | initialRotate | 45deg | 90deg | 270deg | +| FoldIn | initialRotate | 35deg | 60deg | 90deg | +| GlideIn | easing curve | subtle | balanced | dramatic | +| GlitchIn | glitch intensity | subtle | balanced | dramatic | +| GrowIn | scale, easing | subtle | balanced | dramatic | +| PunchIn | easing | sineIn | quadIn | quintIn | +| ShuttersIn | easing curve | subtle | balanced | dramatic | +| SlideIn | easing curve | subtle | balanced | dramatic | +| SpinIn | easing curve | subtle | balanced | dramatic | ### Scroll Presets -| Preset | Power Controls | soft | medium | hard | -| -------- | --------------- | ------ | -------- | ------ | -| BlurScroll | blur | 6px | 25px | 50px | -| FlipScroll | rotate | 60deg | 120deg | 420deg | -| GrowScroll | scaleFrom/scaleTo | 0.8-1.2 | 0.3-1.7 | 0-4 | -| MoveScroll | distance | 150px | 400px | 800px | -| ShapeScroll | clipPath intensity | varies by shape | | | -| ShrinkScroll | scaleFrom/scaleTo | 1.2-0.8 | 1.7-0.3 | 3.5-0 | -| SkewPanScroll | skew | 10deg | 17deg | 24deg | -| Spin3dScroll | rotationZ/travelY | 45/0 | 100/0.5 | 200/1 | -| SpinScroll | scale | 1 | 0.7 | 0.4 | -| StretchScroll | scaleX/scaleY | 0.8/1.2 | 0.6/1.5 | 0.4/2 | -| TiltScroll | distance | 0 | 0.5 | 1 | -| TurnScroll | scaleFrom/scaleTo | 1/1 | 0.7/1.3 | 0.4/1.6 | +| Preset | Power Controls | soft | medium | hard | +| ------------- | ------------------ | --------------- | ------- | ------- | +| BlurScroll | blur | 6px | 25px | 50px | +| FlipScroll | rotate | 60deg | 120deg | 420deg | +| GrowScroll | scaleFrom/scaleTo | 0.8-1.2 | 0.3-1.7 | 0-4 | +| MoveScroll | distance | 150px | 400px | 800px | +| ShapeScroll | clipPath intensity | varies by shape | | | +| ShrinkScroll | scaleFrom/scaleTo | 1.2-0.8 | 1.7-0.3 | 3.5-0 | +| SkewPanScroll | skew | 10deg | 17deg | 24deg | +| Spin3dScroll | rotationZ/travelY | 45/0 | 100/0.5 | 200/1 | +| SpinScroll | scale | 1 | 0.7 | 0.4 | +| StretchScroll | scaleX/scaleY | 0.8/1.2 | 0.6/1.5 | 0.4/2 | +| TiltScroll | distance | 0 | 0.5 | 1 | +| TurnScroll | scaleFrom/scaleTo | 1/1 | 0.7/1.3 | 0.4/1.6 | ### Ongoing Presets -| Preset | Power Controls | soft | medium | hard | -| -------- | --------------- | ------ | -------- | ------ | -| Bounce | bounceFactor | 1 | 2 | 3 | -| Flip | easing curve | subtle | balanced | dramatic | -| Fold | angle | 15deg | 30deg | 45deg | -| Jello | jelloFactor | 1 | 2 | 4 | -| Poke | pokeFactor | 1 | 2 | 4 | -| Pulse | pulseOffset | 0 | 0.06 | 0.12 | -| Rubber | rubberOffset | 0 | 0.05 | 0.1 | -| Spin | easing curve | linear | eased | bouncy | -| Swing | swing angle | 20deg | 40deg | 60deg | -| Wiggle | wiggleFactor | 1 | 2 | 4 | +| Preset | Power Controls | soft | medium | hard | +| ------ | -------------- | ------ | -------- | -------- | +| Bounce | bounceFactor | 1 | 2 | 3 | +| Flip | easing curve | subtle | balanced | dramatic | +| Fold | angle | 15deg | 30deg | 45deg | +| Jello | jelloFactor | 1 | 2 | 4 | +| Poke | pokeFactor | 1 | 2 | 4 | +| Pulse | pulseOffset | 0 | 0.06 | 0.12 | +| Rubber | rubberOffset | 0 | 0.05 | 0.1 | +| Spin | easing curve | linear | eased | bouncy | +| Swing | swing angle | 20deg | 40deg | 60deg | +| Wiggle | wiggleFactor | 1 | 2 | 4 | ### Mouse Presets -| Preset | Power Controls | soft | medium | hard | -| -------- | --------------- | ------ | -------- | ------ | -| AiryMouse | angle | 10deg | 50deg | 85deg | -| BlobMouse | scale | 1.2 | 1.6 | 2.4 | -| BlurMouse | angle/scale | 0/1 | 25/0.7 | 65/0.25 | -| BounceMouse | spring easing | subtle | balanced | dramatic | -| ScaleMouse | scale (varies by direction) | down: 0.85, up: 1.2 | down: 0.5, up: 1.6 | down: 0, up: 2.4 | -| SkewMouse | angle | 10deg | 20deg | 45deg | -| SpinMouse | rotation intensity | subtle | balanced | dramatic | -| SwivelMouse | angle/perspective | 25/1000 | 50/700 | 85/300 | -| Tilt3DMouse | angle/perspective | 25/1000 | 50/500 | 85/200 | -| Track3DMouse | angle/perspective | 25/1000 | 50/500 | 85/333 | -| TrackMouse | easing | linear | easeOut | hardBackOut | +| Preset | Power Controls | soft | medium | hard | +| ------------ | --------------------------- | ------------------- | ------------------ | ---------------- | +| AiryMouse | angle | 10deg | 50deg | 85deg | +| BlobMouse | scale | 1.2 | 1.6 | 2.4 | +| BlurMouse | angle/scale | 0/1 | 25/0.7 | 65/0.25 | +| BounceMouse | spring easing | subtle | balanced | dramatic | +| ScaleMouse | scale (varies by direction) | down: 0.85, up: 1.2 | down: 0.5, up: 1.6 | down: 0, up: 2.4 | +| SkewMouse | angle | 10deg | 20deg | 45deg | +| SpinMouse | rotation intensity | subtle | balanced | dramatic | +| SwivelMouse | angle/perspective | 25/1000 | 50/700 | 85/300 | +| Tilt3DMouse | angle/perspective | 25/1000 | 50/500 | 85/200 | +| Track3DMouse | angle/perspective | 25/1000 | 50/500 | 85/333 | +| TrackMouse | easing | linear | easeOut | hardBackOut | --- @@ -155,6 +155,7 @@ For each preset in presets-reference.md: Visual: [1-2 sentences describing what user SEES] Parameters: + - `param1`: type/range (default: value) - `param2`: type/range (default: value) - `power`: soft | medium | hard (if supported) @@ -184,3 +185,4 @@ To regenerate presets-reference.md: 3. Apply power mappings from this file 4. Generate using preset entry format above 5. Organize by trigger category +6. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks (tables, code blocks, etc.) diff --git a/packages/motion-presets/rules/presets/background-scroll.md b/packages/motion-presets/rules/presets/background-scroll.md index 73ec2968..ae3bbb96 100644 --- a/packages/motion-presets/rules/presets/background-scroll.md +++ b/packages/motion-presets/rules/presets/background-scroll.md @@ -29,13 +29,13 @@ Requires `data-motion-part` attributes: `BG_LAYER`, `BG_MEDIA`, `BG_IMG` See [Background Scroll Presets](presets-reference.md#background-scroll-presets) for details. -| Effect Type | Presets | -| ------------- | --------- | -| Depth/Movement | BgParallax, BgPan, BgFake3D | -| Scale/Zoom | BgZoom, BgCloseUp, BgPullBack | -| Opacity | BgFade, BgFadeBack | -| Rotation | BgRotate | -| Reveal | BgReveal | +| Effect Type | Presets | +| -------------- | ----------------------------- | +| Depth/Movement | BgParallax, BgPan, BgFake3D | +| Scale/Zoom | BgZoom, BgCloseUp, BgPullBack | +| Opacity | BgFade, BgFadeBack | +| Rotation | BgRotate | +| Reveal | BgReveal | ## Note diff --git a/packages/motion-presets/rules/presets/entrance.md b/packages/motion-presets/rules/presets/entrance.md index 5fdf12b0..2ac240fa 100644 --- a/packages/motion-presets/rules/presets/entrance.md +++ b/packages/motion-presets/rules/presets/entrance.md @@ -42,22 +42,22 @@ See [Common Parameters](presets-reference.md#common-parameters) for details on ` ## Quick Decision -| Tone | Presets | -| ------ | --------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | -| Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | -| Geometric/Modern | CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn | +| Tone | Presets | +| ------------------- | ----------------------------------------------- | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | +| Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | +| Geometric/Modern | CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn | ## Common Use Cases -| Use Case | Recommended | -| ---------- | ------------- | -| Hero sections | ArcIn, ExpandIn, FloatIn | -| Modals/Popups | FadeIn, DropIn, GrowIn | +| Use Case | Recommended | +| ---------------------- | -------------------------- | +| Hero sections | ArcIn, ExpandIn, FloatIn | +| Modals/Popups | FadeIn, DropIn, GrowIn | | List items (staggered) | FadeIn, SlideIn with delay | -| Notifications | BounceIn, PunchIn | -| Cards | FlipIn, ArcIn, TiltIn | +| Notifications | BounceIn, PunchIn | +| Cards | FlipIn, ArcIn, TiltIn | ## Combining with Ongoing diff --git a/packages/motion-presets/rules/presets/mouse.md b/packages/motion-presets/rules/presets/mouse.md index 88e41a79..1b7c3488 100644 --- a/packages/motion-presets/rules/presets/mouse.md +++ b/packages/motion-presets/rules/presets/mouse.md @@ -29,20 +29,20 @@ Tilt3DMouse, TrackMouse, BounceMouse, Track3DMouse, SpinMouse, ScaleMouse, Swive ## Quick Decision -| Tone | Presets | -|------|---------| +| Tone | Presets | +| -------------------- | ------------------------------------------ | | Professional/Premium | Tilt3DMouse (soft), TrackMouse, ScaleMouse | -| Playful/Fun | BounceMouse, BlobMouse, AiryMouse | -| Game-like/Dynamic | SpinMouse, Track3DMouse, SkewMouse | +| Playful/Fun | BounceMouse, BlobMouse, AiryMouse | +| Game-like/Dynamic | SpinMouse, Track3DMouse, SkewMouse | ## Common Use Cases -| Use Case | Recommended | -|----------|-------------| -| Product cards | Tilt3DMouse, ScaleMouse | -| Hero depth layers | TrackMouse with different distances | -| Interactive portfolios | Tilt3DMouse, Track3DMouse | -| Playful interfaces | BounceMouse, BlobMouse | +| Use Case | Recommended | +| ---------------------- | ----------------------------------- | +| Product cards | Tilt3DMouse, ScaleMouse | +| Hero depth layers | TrackMouse with different distances | +| Interactive portfolios | Tilt3DMouse, Track3DMouse | +| Playful interfaces | BounceMouse, BlobMouse | ## Mobile Fallback diff --git a/packages/motion-presets/rules/presets/ongoing.md b/packages/motion-presets/rules/presets/ongoing.md index 45abe060..591e1292 100644 --- a/packages/motion-presets/rules/presets/ongoing.md +++ b/packages/motion-presets/rules/presets/ongoing.md @@ -29,19 +29,19 @@ Pulse, Bounce, Spin, Breathe, Flash, Swing, Wiggle, Flip, Fold, Jello, Rubber, P ## Quick Decision -| Tone | Presets | -|------|---------| -| Subtle/Professional | Pulse (soft), Breathe, Flash (soft) | -| Playful/Energetic | Bounce, Wiggle, Jello, DVD | -| Mechanical/Technical | Spin, Flip, Fold | -| Attention-grabbing | Flash, Bounce, Pulse (hard), Poke | +| Tone | Presets | +| -------------------- | ----------------------------------- | +| Subtle/Professional | Pulse (soft), Breathe, Flash (soft) | +| Playful/Energetic | Bounce, Wiggle, Jello, DVD | +| Mechanical/Technical | Spin, Flip, Fold | +| Attention-grabbing | Flash, Bounce, Pulse (hard), Poke | ## Common Use Cases -| Use Case | Recommended | -|----------|-------------| -| Loading spinner | Spin (duration: 1500ms) | -| Status indicator | Pulse, Breathe | -| Notification badge | Bounce, Pulse, Poke | -| CTA emphasis | Pulse, Bounce | -| Character/Mascot | Bounce, Wiggle, Jello | +| Use Case | Recommended | +| ------------------ | ----------------------- | +| Loading spinner | Spin (duration: 1500ms) | +| Status indicator | Pulse, Breathe | +| Notification badge | Bounce, Pulse, Poke | +| CTA emphasis | Pulse, Bounce | +| Character/Mascot | Bounce, Wiggle, Jello | diff --git a/packages/motion-presets/rules/presets/presets-reference.md b/packages/motion-presets/rules/presets/presets-reference.md index 0094d7fa..4278d3d2 100644 --- a/packages/motion-presets/rules/presets/presets-reference.md +++ b/packages/motion-presets/rules/presets/presets-reference.md @@ -17,13 +17,13 @@ This document is a comprehensive reference for Interact motion presets. Use it t ### Quick Trigger Lookup -| User Intent | Trigger | Notes | -| ------------- | --------- | ------- | -| "animate when element enters viewport", "reveal on scroll into view" | entrance | viewEnter trigger (intersection observer) | -| "animate based on scroll position", "parallax", "scroll-driven" | scroll | Tied to scroll progress | -| "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely | -| "react to mouse", "follow cursor", "tilt on hover" | mouse | Desktop only | -| "background image effect", "hero background", "parallax bg" | background-scroll | CSS backgrounds only | +| User Intent | Trigger | Notes | +| -------------------------------------------------------------------- | ----------------- | ----------------------------------------- | +| "animate when element enters viewport", "reveal on scroll into view" | entrance | viewEnter trigger (intersection observer) | +| "animate based on scroll position", "parallax", "scroll-driven" | scroll | Tied to scroll progress | +| "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely | +| "react to mouse", "follow cursor", "tilt on hover" | mouse | Desktop only | +| "background image effect", "hero background", "parallax bg" | background-scroll | CSS backgrounds only | --- @@ -172,44 +172,44 @@ Many presets support `power: 'soft' | 'medium' | 'hard'`. ### By Tone -| Tone | Entrance | Scroll | Ongoing | Mouse | -| ------ | ---------- | -------- | --------- | ------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (soft), Breathe | Tilt3DMouse (soft), TrackMouse | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | -| Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | -| Geometric/Modern | CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | +| Tone | Entrance | Scroll | Ongoing | Mouse | +| ------------------- | ----------------------------------------------- | ----------------------------------------- | -------------------------- | ------------------------------ | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (soft), Breathe | Tilt3DMouse (soft), TrackMouse | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | +| Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | +| Geometric/Modern | CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | ### By Use Case -| Use Case | Recommended Presets | -| ---------- | --------------------- | -| Hero sections | ArcIn, ExpandIn, FloatIn, RevealIn + BgParallax, BgZoom | -| Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | -| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | -| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | -| Notifications/Badges | BounceIn, PunchIn, DropIn + Pulse | -| CTAs/Buttons | BounceIn, PunchIn, GrowIn + Pulse | -| Loading indicators | Spin, Pulse | -| Product images | Tilt3DMouse, ScaleMouse | -| Background depth | BgParallax, ParallaxScroll, TrackMouse (layered) | +| Use Case | Recommended Presets | +| ---------------------- | ------------------------------------------------------- | +| Hero sections | ArcIn, ExpandIn, FloatIn, RevealIn + BgParallax, BgZoom | +| Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | +| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | +| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | +| Notifications/Badges | BounceIn, PunchIn, DropIn + Pulse | +| CTAs/Buttons | BounceIn, PunchIn, GrowIn + Pulse | +| Loading indicators | Spin, Pulse | +| Product images | Tilt3DMouse, ScaleMouse | +| Background depth | BgParallax, ParallaxScroll, TrackMouse (layered) | ### Cross-Category Parallels Effects with similar visual results across triggers: -| Entrance | Scroll | Ongoing | Mouse | Background | -| ---------- | -------- | --------- | ------- | ------------ | -| FadeIn | FadeScroll | Flash | - | BgFade | -| ArcIn | ArcScroll | - | - | - | -| SpinIn | SpinScroll | Spin | SpinMouse | BgRotate | -| BounceIn | - | Bounce | BounceMouse | - | -| TiltIn | TiltScroll | - | Tilt3DMouse | - | -| FlipIn | FlipScroll | Flip | - | - | -| GrowIn | GrowScroll | Pulse | ScaleMouse | BgZoom | -| SlideIn | SlideScroll | - | TrackMouse | BgPan | -| BlurIn | BlurScroll | - | BlurMouse | - | -| RevealIn | RevealScroll | - | - | BgReveal | -| - | ParallaxScroll | - | TrackMouse | BgParallax | +| Entrance | Scroll | Ongoing | Mouse | Background | +| -------- | -------------- | ------- | ----------- | ---------- | +| FadeIn | FadeScroll | Flash | - | BgFade | +| ArcIn | ArcScroll | - | - | - | +| SpinIn | SpinScroll | Spin | SpinMouse | BgRotate | +| BounceIn | - | Bounce | BounceMouse | - | +| TiltIn | TiltScroll | - | Tilt3DMouse | - | +| FlipIn | FlipScroll | Flip | - | - | +| GrowIn | GrowScroll | Pulse | ScaleMouse | BgZoom | +| SlideIn | SlideScroll | - | TrackMouse | BgPan | +| BlurIn | BlurScroll | - | BlurMouse | - | +| RevealIn | RevealScroll | - | - | BgReveal | +| - | ParallaxScroll | - | TrackMouse | BgParallax | ### Combining Triggers @@ -221,7 +221,7 @@ Effects with similar visual results across triggers: **Requires multiple containers (nested elements):** - Entrance + Mouse -- Entrance + Scroll +- Entrance + Scroll - Scroll + Mouse - Any other combination @@ -997,7 +997,9 @@ Parameters: - `delay`: 0-8000ms (default: 0) ```typescript -{ type: 'Flash' } +{ + type: 'Flash'; +} ``` #### Swing @@ -1092,7 +1094,9 @@ Parameters: **When `power` is set:** overrides `intensity`/rubber offset (soft=0, medium=0.05, hard=0.1) ```typescript -{ type: 'Rubber' } +{ + type: 'Rubber'; +} ``` #### Poke @@ -1134,7 +1138,9 @@ Parameters: - `delay`: 0-8000ms (default: 0) ```typescript -{ type: 'DVD' } +{ + type: 'DVD'; +} ``` --- @@ -1265,7 +1271,9 @@ Parameters: **When `power` is set:** overrides `angle` and `perspective` (soft: 25/1000, medium: 50/700, hard: 85/300) ```typescript -{ type: 'SwivelMouse' } +{ + type: 'SwivelMouse'; +} ``` #### SkewMouse @@ -1283,7 +1291,9 @@ Parameters: **When `power` is set:** overrides `angle` (soft=10, medium=20, hard=45) ```typescript -{ type: 'SkewMouse' } +{ + type: 'SkewMouse'; +} ``` #### BlurMouse @@ -1303,7 +1313,9 @@ Parameters: **When `power` is set:** overrides `angle` and `scale` (soft: 0/1, medium: 25/0.7, hard: 65/0.25) ```typescript -{ type: 'BlurMouse' } +{ + type: 'BlurMouse'; +} ``` #### AiryMouse @@ -1321,7 +1333,9 @@ Parameters: **When `power` is set:** overrides `angle` (soft=10, medium=50, hard=85) ```typescript -{ type: 'AiryMouse' } +{ + type: 'AiryMouse'; +} ``` #### BlobMouse @@ -1338,7 +1352,9 @@ Parameters: **When `power` is set:** overrides `scale` (soft=1.2, medium=1.6, hard=2.4) ```typescript -{ type: 'BlobMouse' } +{ + type: 'BlobMouse'; +} ``` #### CustomMouse @@ -1346,7 +1362,9 @@ Parameters: Visual: Configurable custom behavior. For advanced custom implementations. ```typescript -{ type: 'CustomMouse' } +{ + type: 'CustomMouse'; +} ``` --- @@ -1406,7 +1424,9 @@ Parameters: - `scale`: scale factor ```typescript -{ type: 'BgFadeBack' } +{ + type: 'BgFadeBack'; +} ``` #### BgPan @@ -1446,7 +1466,9 @@ Parameters: - `angle`: skew angle ```typescript -{ type: 'BgSkew' } +{ + type: 'BgSkew'; +} ``` #### BgReveal @@ -1454,7 +1476,9 @@ Parameters: Visual: Clip-based background reveal. Theatrical unveiling. ```typescript -{ type: 'BgReveal' } +{ + type: 'BgReveal'; +} ``` #### BgCloseUp @@ -1466,7 +1490,9 @@ Parameters: - `scale`: zoom scale ```typescript -{ type: 'BgCloseUp' } +{ + type: 'BgCloseUp'; +} ``` #### BgPullBack @@ -1478,7 +1504,9 @@ Parameters: - `scale`: zoom scale ```typescript -{ type: 'BgPullBack' } +{ + type: 'BgPullBack'; +} ``` #### BgFake3D @@ -1491,7 +1519,9 @@ Parameters: - `zoom`: zoom factor ```typescript -{ type: 'BgFake3D' } +{ + type: 'BgFake3D'; +} ``` #### ImageParallax @@ -1537,17 +1567,17 @@ Parameters: ### Reduced Motion Fallback Table -| Original | Fallback | -| ---------- | ---------- | -| BounceIn, SpinIn, PunchIn | FadeIn | -| ArcIn, FlipIn, TurnIn | FadeIn | -| GlitchIn | FadeIn | -| Spin, Bounce, Wiggle | Stop or subtle Pulse | -| Flash | Reduce frequency (<3/sec) | -| ParallaxScroll | Static position | -| ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | -| BgParallax, BgZoom | Static background | -| All mouse animations | Static state | +| Original | Fallback | +| --------------------------------- | ------------------------- | +| BounceIn, SpinIn, PunchIn | FadeIn | +| ArcIn, FlipIn, TurnIn | FadeIn | +| GlitchIn | FadeIn | +| Spin, Bounce, Wiggle | Stop or subtle Pulse | +| Flash | Reduce frequency (<3/sec) | +| ParallaxScroll | Static position | +| ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | +| BgParallax, BgZoom | Static background | +| All mouse animations | Static state | ### Stagger Patterns @@ -1557,15 +1587,15 @@ For lists/grids, apply increasing `delay` values: // List items with 100ms stagger items.forEach((item, i) => ({ type: 'FadeIn', - delay: i * 100 -})) + delay: i * 100, +})); // Faster stagger (50ms) items.forEach((item, i) => ({ type: 'SlideIn', direction: 'bottom', - delay: i * 50 -})) + delay: i * 50, +})); ``` ### Performance Notes diff --git a/packages/motion-presets/rules/presets/scroll.md b/packages/motion-presets/rules/presets/scroll.md index 96a4941b..a7457e45 100644 --- a/packages/motion-presets/rules/presets/scroll.md +++ b/packages/motion-presets/rules/presets/scroll.md @@ -34,19 +34,19 @@ ParallaxScroll, FadeScroll, ArcScroll, BlurScroll, FlipScroll, GrowScroll, Shrin ## Quick Decision -| Effect Type | Presets | -|-------------|---------| -| Opacity | FadeScroll, BlurScroll | -| Movement | ParallaxScroll, MoveScroll, PanScroll, SlideScroll | -| Scale | GrowScroll, ShrinkScroll | -| 3D Rotation | ArcScroll, FlipScroll, TiltScroll, TurnScroll | -| Reveal/Mask | RevealScroll, ShapeScroll, ShuttersScroll | +| Effect Type | Presets | +| ----------- | -------------------------------------------------- | +| Opacity | FadeScroll, BlurScroll | +| Movement | ParallaxScroll, MoveScroll, PanScroll, SlideScroll | +| Scale | GrowScroll, ShrinkScroll | +| 3D Rotation | ArcScroll, FlipScroll, TiltScroll, TurnScroll | +| Reveal/Mask | RevealScroll, ShapeScroll, ShuttersScroll | ## Common Use Cases -| Use Case | Recommended | -|----------|-------------| -| Depth/Layering | ParallaxScroll with different speeds | -| Content reveal | FadeScroll (in), RevealScroll | -| Dramatic sections | ArcScroll, FlipScroll, TiltScroll | -| De-emphasize passed | FadeScroll (out), ShrinkScroll | +| Use Case | Recommended | +| ------------------- | ------------------------------------ | +| Depth/Layering | ParallaxScroll with different speeds | +| Content reveal | FadeScroll (in), RevealScroll | +| Dramatic sections | ArcScroll, FlipScroll, TiltScroll | +| De-emphasize passed | FadeScroll (out), ShrinkScroll | From f05d7b6100c2d548d903a914bc7e2cfa1dc9a92c Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Thu, 29 Jan 2026 10:14:50 +0200 Subject: [PATCH 11/20] made better a11y rules --- packages/motion-presets/rules/presets/PLAN.md | 60 +++++++++++++- .../rules/presets/presets-reference.md | 81 ++++++++++++------- 2 files changed, 109 insertions(+), 32 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 8f2fc3a6..f161bdd6 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -145,6 +145,58 @@ Animates DOM elements via CSS transforms (not `background-position`). --- +## Accessibility + +This section documents preset selection guidance for accessibility. It is not about library-level features (like `allowA11yTriggers`). + +### Host vs Preset Responsibility + +The presets provide animations; the host platform decides when/whether to apply them. When the host handles accessibility globally (e.g., disabling all animations under `prefers-reduced-motion`), presets don't need to address it separately. + +### Preset Risk Levels + +**High risk** (vestibular triggers, seizure risk): + +- Spinning: SpinIn, Spin, SpinScroll, SpinMouse, Spin3dScroll +- Bouncing: BounceIn, Bounce, BounceMouse +- 3D rotations: ArcIn, FlipIn, ArcScroll, FlipScroll, Tilt3DMouse +- Continuous motion: Flash, DVD, Jello, Wiggle + +**Medium risk** (strong motion, may affect some users): + +- GlitchIn, PunchIn, TurnIn +- ParallaxScroll, BgParallax at high speed values + +**Low risk / safe** (opacity/blur changes, minimal spatial movement): + +- FadeIn, FadeScroll, BlurIn, BlurScroll +- SlideIn (soft), GlideIn (soft) +- Pulse (soft), Breathe + +### Reduced Motion Fallbacks + +| Original | Fallback | +| --------------------------------- | ------------------------- | +| BounceIn, SpinIn, PunchIn | FadeIn | +| ArcIn, FlipIn, TurnIn | FadeIn | +| GlitchIn | FadeIn | +| Spin, Bounce, Wiggle | Stop or subtle Pulse | +| Flash | Reduce frequency (<3/sec) | +| ParallaxScroll | Static position | +| ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | +| BgParallax, BgZoom | Static background | +| All mouse animations | Static state | + +### LLM Guidance Principles + +1. **Do not limit creativity by default** - generate what the user asks for +2. **Apply constraints only when explicitly requested** - keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" +3. **High-risk presets are informational, not blockers** - optionally note vestibular concerns in response +4. **Mouse presets are desktop-only** - note this as context, not a restriction +5. **Duration guidelines are suggestions** - functional UI <500ms, decorative up to 1200ms, hero up to 2000ms + +--- + ## Preset Entry Format For each preset in presets-reference.md: @@ -175,8 +227,9 @@ To regenerate presets-reference.md: 1. **Preset list**: `motion-presets/src/types.ts` - EntranceAnimation, ScrollAnimation, OngoingAnimation, MouseAnimation, BackgroundScrollAnimation unions 2. **Parameter constraints**: `effects-kit/src/effects/{category}/{preset}.ts` - min/max/step/defaults -3. **Power mappings**: This file (PLAN.md) - see tables above -4. **Base params**: `effects-kit/src/effects/baseParams.ts` +3. **Power mappings**: This file (PLAN.md) - see Power Parameter Mappings section +4. **Accessibility**: This file (PLAN.md) - see Accessibility section +5. **Base params**: `effects-kit/src/effects/baseParams.ts` ## Regeneration Steps @@ -185,4 +238,5 @@ To regenerate presets-reference.md: 3. Apply power mappings from this file 4. Generate using preset entry format above 5. Organize by trigger category -6. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks (tables, code blocks, etc.) +6. Include accessibility section from this file +7. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks (tables, code blocks, etc.) diff --git a/packages/motion-presets/rules/presets/presets-reference.md b/packages/motion-presets/rules/presets/presets-reference.md index 4278d3d2..b4b5d548 100644 --- a/packages/motion-presets/rules/presets/presets-reference.md +++ b/packages/motion-presets/rules/presets/presets-reference.md @@ -1541,29 +1541,35 @@ Parameters: --- -## 5. Extras +## 5. Accessibility -### Accessibility +### Host vs Preset Responsibility -**Always respect `prefers-reduced-motion`:** +The presets provide animations; the host platform decides when and whether to apply them. -- Check `window.matchMedia('(prefers-reduced-motion: reduce)')` -- Provide FadeIn as fallback for entrance animations -- Disable ongoing/scroll/mouse animations entirely for sensitive users +- When the host handles accessibility globally (e.g., disabling all animations under `prefers-reduced-motion`), presets don't need to address it separately +- Keyboard triggers (`activate`/`interest`) and config options like `allowA11yTriggers` are library-level features, not part of preset configuration +- This section provides guidance for preset selection, not library configuration -**Vestibular triggers to avoid or provide alternatives:** +### Preset Risk Levels -- Spinning: SpinIn, Spin, SpinScroll, SpinMouse +**High risk** (vestibular triggers, seizure risk): + +- Spinning: SpinIn, Spin, SpinScroll, SpinMouse, Spin3dScroll - Bouncing: BounceIn, Bounce, BounceMouse - 3D rotations: ArcIn, FlipIn, ArcScroll, FlipScroll, Tilt3DMouse -- Large-scale parallax: ParallaxScroll, BgParallax at high speeds -- Flashing: Flash (never exceed 3 flashes/second) +- Continuous motion: Flash, DVD, Jello, Wiggle -**Duration guidelines:** +**Medium risk** (strong motion, may affect some users): -- Functional UI (modals, dropdowns): under 500ms -- Decorative content: up to 1200ms -- Hero moments: up to 2000ms +- GlitchIn, PunchIn, TurnIn +- ParallaxScroll, BgParallax at high speed values + +**Low risk / safe** (opacity/blur changes, minimal spatial movement): + +- FadeIn, FadeScroll, BlurIn, BlurScroll +- SlideIn (soft), GlideIn (soft) +- Pulse (soft), Breathe ### Reduced Motion Fallback Table @@ -1579,24 +1585,41 @@ Parameters: | BgParallax, BgZoom | Static background | | All mouse animations | Static state | -### Stagger Patterns +### Trigger Considerations -For lists/grids, apply increasing `delay` values: +All preset triggers play automatically without explicit user action: -```typescript -// List items with 100ms stagger -items.forEach((item, i) => ({ - type: 'FadeIn', - delay: i * 100, -})); +| Trigger | Behavior | Note | +| ----------------- | ------------------------------------- | ------------------------------------------ | +| Entrance | Plays on viewport entry (`viewEnter`) | Not user-initiated | +| Scroll | Tied to scroll position | Continuous while scrolling | +| Background Scroll | Tied to scroll position | Continuous while scrolling | +| Ongoing | Loops indefinitely | Flash must stay under 3 flashes/sec | +| Mouse | Responds to cursor position | Desktop only, no touch/keyboard equivalent | -// Faster stagger (50ms) -items.forEach((item, i) => ({ - type: 'SlideIn', - direction: 'bottom', - delay: i * 50, -})); -``` +### LLM Guidance for Preset Selection + +**Do not limit creativity by default.** If the user asks for "grand", "energetic", "stunning", or similar, generate accordingly using any appropriate presets. + +**Apply accessibility constraints only when explicitly requested** via phrases like: + +- "accessible", "a11y", "reduced motion safe" +- "subtle", "tone down", "gentle" +- "professional", "minimal" + +**When generating high-risk presets:** Optionally note in your response that some presets may affect users with vestibular sensitivity. This is informational, not a blocker. + +**Mouse presets:** Note that these are desktop-only (no touch/keyboard equivalent). This is informational context, not a restriction. + +**Duration guidelines** (suggestions, not limits): + +- Functional UI (modals, dropdowns): under 500ms +- Decorative content: up to 1200ms +- Hero moments: up to 2000ms + +### Stagger Patterns + +For lists/grids, apply increasing subtle `delay` values ### Performance Notes From 276971ee69294ece3e2a55ae5521f6d98077029f Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Sun, 1 Feb 2026 13:48:05 +0200 Subject: [PATCH 12/20] Update motion presets documentation based on the real presets implemen tation plan - Refactor section headings for better readability across all preset files. - Standardize usage notes for when to use and not use each animation type. - Consolidate available presets information and enhance quick decision tables. - Update PLAN.md to reflect the current status and versioning of presets. --- packages/motion-presets/rules/presets/PLAN.md | 407 ++++++++++--- .../rules/presets/background-scroll.md | 6 +- .../motion-presets/rules/presets/entrance.md | 36 +- .../motion-presets/rules/presets/mouse.md | 10 +- .../motion-presets/rules/presets/ongoing.md | 10 +- .../rules/presets/presets-reference.md | 539 +++++++----------- .../motion-presets/rules/presets/scroll.md | 12 +- 7 files changed, 572 insertions(+), 448 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index f161bdd6..96da2932 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -1,7 +1,9 @@ --- name: LLM Preset Rules overview: Consolidated single-file reference with lightweight trigger entry points. -status: completed +status: in-progress +version: 2.0 +last-updated: 2026-02-01 --- # LLM Rules for Motion Presets @@ -20,6 +22,117 @@ rules/presets/ └── background-scroll.md # Lightweight trigger entry point ``` +--- + +## Preset Registry + +### Entrance Presets + +| Preset | Status | Notes | +| ---------- | ----------- | -------------------------------------------------------- | +| FadeIn | Active | Simple opacity transition | +| ArcIn | Active | 3D arc rotation entry | +| BlurIn | Active | Blur-to-clear transition | +| BounceIn | Active | Bouncy entrance with overshoot | +| CurveIn | Active | Curved path entry | +| DropIn | Active | Drop from above with scale | +| FlipIn | Active | 3D flip rotation | +| FloatIn | Active | Gentle floating entry | +| FoldIn | Active | 3D fold unfold | +| GlideIn | Active | Smooth directional slide (default: from left, angle 270) | +| GrowIn | Active | Scale + translate entry | +| RevealIn | Active | Directional clip-path reveal | +| ShapeIn | Active | Geometric shape clip-path reveal | +| ShuttersIn | Active | Multi-segment reveal | +| SlideIn | Active | Directional slide with clip | +| SpinIn | Active | Rotation entry | +| TiltIn | Active | 3D tilt entry | +| TurnIn | Active | Corner-pivot rotation | +| WinkIn | Active | Axis-based scale reveal | +| CircleIn | **REMOVED** | Legacy preset | +| ExpandIn | **REMOVED** | Consolidated into GrowIn | +| GlitchIn | **REMOVED** | Was wrapper for GlideIn | +| PunchIn | **REMOVED** | Legacy preset | + +### Scroll Presets + +| Preset | Status | Notes | +| -------------- | ------ | ----------------------------- | +| ArcScroll | Active | 3D arc on scroll | +| BlurScroll | Active | Blur based on scroll | +| FadeScroll | Active | Opacity on scroll | +| FlipScroll | Active | 3D flip on scroll | +| GrowScroll | Active | Scale up on scroll | +| MoveScroll | Active | Translate on scroll | +| PanScroll | Active | Horizontal pan on scroll | +| ParallaxScroll | Active | Depth-based parallax | +| RevealScroll | Active | Clip-path reveal on scroll | +| ShapeScroll | Active | Shape clip-path on scroll | +| ShrinkScroll | Active | Scale down on scroll | +| ShuttersScroll | Active | Multi-segment on scroll | +| SkewPanScroll | Active | Skew + pan on scroll | +| SlideScroll | Active | Slide on scroll | +| Spin3dScroll | Active | 3D spin on scroll | +| SpinScroll | Active | 2D spin on scroll | +| StretchScroll | Active | Stretch deformation on scroll | +| TiltScroll | Active | 3D tilt on scroll | +| TurnScroll | Active | Turn rotation on scroll | + +### Ongoing Presets + +| Preset | Status | Notes | +| ------- | ------ | ---------------------- | +| Bounce | Active | Continuous bounce | +| Breathe | Active | Gentle scale pulse | +| Cross | Active | Cross-pattern movement | +| DVD | Active | DVD screensaver bounce | +| Flash | Active | Opacity flash | +| Flip | Active | Continuous flip | +| Fold | Active | Continuous fold | +| Jello | Active | Jello wobble | +| Poke | Active | Directional poke | +| Pulse | Active | Scale pulse | +| Rubber | Active | Rubber stretch | +| Spin | Active | Continuous rotation | +| Swing | Active | Pendulum swing | +| Wiggle | Active | Shake wiggle | + +### Mouse Presets + +| Preset | Status | Notes | +| ------------ | ------ | ------------------------ | +| AiryMouse | Active | Light floating follow | +| BlobMouse | Active | Blob-like scale response | +| BlurMouse | Active | Blur on distance | +| BounceMouse | Active | Bouncy follow | +| CustomMouse | Active | Custom mouse effect | +| ScaleMouse | Active | Scale on mouse | +| SkewMouse | Active | Skew on mouse | +| SpinMouse | Active | Spin on mouse | +| SwivelMouse | Active | 3D swivel on mouse | +| Tilt3DMouse | Active | 3D tilt on mouse | +| Track3DMouse | Active | 3D tracking on mouse | +| TrackMouse | Active | Direct mouse tracking | + +### Background Scroll Presets + +| Preset | Status | Notes | +| ------------- | ------ | ------------------------------------------- | +| BgCloseUp | Active | Zoom close-up effect | +| BgFade | Active | Background fade | +| BgFadeBack | Active | Fade with pullback | +| BgFake3D | Active | Fake 3D depth | +| BgPan | Active | Horizontal pan | +| BgParallax | Active | Parallax depth | +| BgPullBack | Active | Pull back zoom | +| BgReveal | Active | Background reveal | +| BgRotate | Active | Background rotation | +| BgSkew | Active | Background skew | +| BgZoom | Active | Background zoom | +| ImageParallax | Active | Image parallax (no data-motion-part needed) | + +--- + ## Key Constraints ### Trigger Mechanisms @@ -52,6 +165,10 @@ Animates DOM elements via CSS transforms (not `background-position`). **Exception:** `ImageParallax` works on regular `` elements without `data-motion-part`. +--- + +## Parameter Standards + ### Common Parameters **All Entrance presets:** @@ -70,78 +187,80 @@ Animates DOM elements via CSS transforms (not `background-position`). - `duration`: 100-4000ms - `delay`: 0-8000ms ---- +### Parameter Naming Conventions -## Power Parameter Mappings +| Meaning | Parameter Name | Values | Example Presets | +| ----------------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------- | +| Numeric angle (degrees) | `angle` | 0-360 | GrowIn, GlideIn, MoveScroll | +| Cardinal direction | `direction` | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | +| Extended cardinal | `direction` | + 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center' | BounceIn, ShapeIn | +| Rotation direction | `direction` | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | +| Axis | `axis` | 'horizontal', 'vertical' | WinkIn, FlipScroll, ArcScroll, Flip, Breathe | -`power: 'soft' | 'medium' | 'hard'` **overrides** fine-grained parameters when set. +### Coordinate System -### Entrance Presets +**Standard:** 0° = right (east), angles increase counter-clockwise -| Preset | Power Controls | soft | medium | hard | -| ---------- | ---------------- | -------------- | -------------- | --------- | -| ArcIn | easing curve | subtle | balanced | dramatic | -| BlurIn | blur | 6px | 25px | 50px | -| BounceIn | distanceFactor | 1 | 2 | 3 | -| DropIn | scale, easing | 1.2/cubicInOut | 1.6/quintInOut | 2/backOut | -| ExpandIn | scale, easing | subtle | balanced | dramatic | -| FlipIn | initialRotate | 45deg | 90deg | 270deg | -| FoldIn | initialRotate | 35deg | 60deg | 90deg | -| GlideIn | easing curve | subtle | balanced | dramatic | -| GlitchIn | glitch intensity | subtle | balanced | dramatic | -| GrowIn | scale, easing | subtle | balanced | dramatic | -| PunchIn | easing | sineIn | quadIn | quintIn | -| ShuttersIn | easing curve | subtle | balanced | dramatic | -| SlideIn | easing curve | subtle | balanced | dramatic | -| SpinIn | easing curve | subtle | balanced | dramatic | +- 0° = right (east) +- 90° = top (north) +- 180° = left (west) +- 270° = bottom (south) -### Scroll Presets +### Distance Units -| Preset | Power Controls | soft | medium | hard | -| ------------- | ------------------ | --------------- | ------- | ------- | -| BlurScroll | blur | 6px | 25px | 50px | -| FlipScroll | rotate | 60deg | 120deg | 420deg | -| GrowScroll | scaleFrom/scaleTo | 0.8-1.2 | 0.3-1.7 | 0-4 | -| MoveScroll | distance | 150px | 400px | 800px | -| ShapeScroll | clipPath intensity | varies by shape | | | -| ShrinkScroll | scaleFrom/scaleTo | 1.2-0.8 | 1.7-0.3 | 3.5-0 | -| SkewPanScroll | skew | 10deg | 17deg | 24deg | -| Spin3dScroll | rotationZ/travelY | 45/0 | 100/0.5 | 200/1 | -| SpinScroll | scale | 1 | 0.7 | 0.4 | -| StretchScroll | scaleX/scaleY | 0.8/1.2 | 0.6/1.5 | 0.4/2 | -| TiltScroll | distance | 0 | 0.5 | 1 | -| TurnScroll | scaleFrom/scaleTo | 1/1 | 0.7/1.3 | 0.4/1.6 | +All distance parameters accept any CSS unit with a default: -### Ongoing Presets +```typescript +distance: { value: 120, type: 'px' } // pixels +distance: { value: 50, type: 'percentage' } // percentage +distance: { value: 10, type: 'vh' } // viewport height +``` -| Preset | Power Controls | soft | medium | hard | -| ------ | -------------- | ------ | -------- | -------- | -| Bounce | bounceFactor | 1 | 2 | 3 | -| Flip | easing curve | subtle | balanced | dramatic | -| Fold | angle | 15deg | 30deg | 45deg | -| Jello | jelloFactor | 1 | 2 | 4 | -| Poke | pokeFactor | 1 | 2 | 4 | -| Pulse | pulseOffset | 0 | 0.06 | 0.12 | -| Rubber | rubberOffset | 0 | 0.05 | 0.1 | -| Spin | easing curve | linear | eased | bouncy | -| Swing | swing angle | 20deg | 40deg | 60deg | -| Wiggle | wiggleFactor | 1 | 2 | 4 | +### CSS Custom Properties -### Mouse Presets +The library uses these CSS custom properties for runtime control: + +- `--motion-opacity`: Target opacity (default: 1) +- `--motion-rotate-z`: Element rotation for scroll effects + +--- + +## Optional Parameters (Previously Hardcoded) + +Many presets now expose parameters that were previously hardcoded: + +### 3D Perspective + +| Preset | Parameter | Default | Range | +| ----------------- | ------------- | ------- | -------- | +| ArcIn | `perspective` | 800 | 200-2000 | +| TiltIn | `perspective` | 800 | 200-2000 | +| FoldIn | `perspective` | 800 | 200-2000 | +| FlipIn | `perspective` | 800 | 200-2000 | +| CurveIn | `perspective` | 200 | 100-1000 | +| BounceIn (center) | `perspective` | 800 | 200-2000 | +| FlipScroll | `perspective` | 800 | 200-2000 | +| TiltScroll | `perspective` | 400 | 200-2000 | +| Spin3dScroll | `perspective` | 1000 | 200-2000 | + +### Depth (Z Translation) + +| Preset | Parameter | Default | Notes | +| --------- | --------- | ------- | ---------------------- | +| ArcIn | `depth` | 300px | Z translation distance | +| CurveIn | `depth` | 900px | Z translation distance | +| TiltIn | `depth` | 200px | Z translation distance | +| ArcScroll | `depth` | 300 | Z translation distance | -| Preset | Power Controls | soft | medium | hard | -| ------------ | --------------------------- | ------------------- | ------------------ | ---------------- | -| AiryMouse | angle | 10deg | 50deg | 85deg | -| BlobMouse | scale | 1.2 | 1.6 | 2.4 | -| BlurMouse | angle/scale | 0/1 | 25/0.7 | 65/0.25 | -| BounceMouse | spring easing | subtle | balanced | dramatic | -| ScaleMouse | scale (varies by direction) | down: 0.85, up: 1.2 | down: 0.5, up: 1.6 | down: 0, up: 2.4 | -| SkewMouse | angle | 10deg | 20deg | 45deg | -| SpinMouse | rotation intensity | subtle | balanced | dramatic | -| SwivelMouse | angle/perspective | 25/1000 | 50/700 | 85/300 | -| Tilt3DMouse | angle/perspective | 25/1000 | 50/500 | 85/200 | -| Track3DMouse | angle/perspective | 25/1000 | 50/500 | 85/333 | -| TrackMouse | easing | linear | easeOut | hardBackOut | +### Rotation Angles + +| Preset | Parameter | Default | Notes | +| --------- | ----------- | ------- | ------------------ | +| ArcIn | `angle` | 80 | Arc rotation angle | +| ArcScroll | `angle` | 68 | Arc rotation angle | +| TiltIn | `tiltAngle` | 90 | Initial tilt angle | +| FloatIn | `distance` | 120 | Float distance | +| TurnIn | `angle` | 50 | Rotation angle | --- @@ -164,22 +283,21 @@ The presets provide animations; the host platform decides when/whether to apply **Medium risk** (strong motion, may affect some users): -- GlitchIn, PunchIn, TurnIn +- TurnIn - ParallaxScroll, BgParallax at high speed values **Low risk / safe** (opacity/blur changes, minimal spatial movement): - FadeIn, FadeScroll, BlurIn, BlurScroll -- SlideIn (soft), GlideIn (soft) -- Pulse (soft), Breathe +- SlideIn (subtle), GlideIn (subtle) +- Pulse (subtle), Breathe ### Reduced Motion Fallbacks | Original | Fallback | | --------------------------------- | ------------------------- | -| BounceIn, SpinIn, PunchIn | FadeIn | +| BounceIn, SpinIn | FadeIn | | ArcIn, FlipIn, TurnIn | FadeIn | -| GlitchIn | FadeIn | | Spin, Bounce, Wiggle | Stop or subtle Pulse | | Flash | Reduce frequency (<3/sec) | | ParallaxScroll | Static position | @@ -210,33 +328,156 @@ Parameters: - `param1`: type/range (default: value) - `param2`: type/range (default: value) -- `power`: soft | medium | hard (if supported) - -**When `power` is set:** overrides `paramX` (soft=value, medium=value, hard=value) \`\`\`typescript { type: 'PresetName', param1: 'value' } \`\`\` ``` +**Notes:** + +- Include all required parameters +- Include optional parameters with their defaults +- For angle-based presets, note that 0° = right (east) +- For 3D presets, include perspective parameter if customizable + +--- + +## Selection Tables + +### Preset Selection By Tone + +| Tone | Entrance | Scroll | Ongoing | Mouse | +| ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | +| Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | +| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | + +### Preset Selection By Use Case + +| Use Case | Recommended Presets | +| ---------------------- | ------------------------------------------------ | +| Hero sections | ArcIn, FloatIn, RevealIn + BgParallax, BgZoom | +| Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | +| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | +| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | +| Notifications/Badges | BounceIn, DropIn + Pulse | +| CTAs/Buttons | BounceIn, GrowIn + Pulse | +| Loading indicators | Spin, Pulse | +| Product images | Tilt3DMouse, ScaleMouse | +| Background depth | BgParallax, ParallaxScroll, TrackMouse (layered) | + --- ## Data Sources To regenerate presets-reference.md: -1. **Preset list**: `motion-presets/src/types.ts` - EntranceAnimation, ScrollAnimation, OngoingAnimation, MouseAnimation, BackgroundScrollAnimation unions -2. **Parameter constraints**: `effects-kit/src/effects/{category}/{preset}.ts` - min/max/step/defaults -3. **Power mappings**: This file (PLAN.md) - see Power Parameter Mappings section -4. **Accessibility**: This file (PLAN.md) - see Accessibility section -5. **Base params**: `effects-kit/src/effects/baseParams.ts` +1. **Preset registry**: This file (PLAN.md) - see Preset Registry section for active/removed status +2. **Preset list**: `motion-presets/src/types.ts` - EntranceAnimation, ScrollAnimation, OngoingAnimation, MouseAnimation, BackgroundScrollAnimation unions +3. **Parameter constraints**: `motion-presets/src/library/{category}/{Preset}.ts` - parameter types and defaults +4. **Parameter standards**: This file (PLAN.md) - see Parameter Standards section +5. **Optional parameters**: This file (PLAN.md) - see Optional Parameters section +6. **Accessibility**: This file (PLAN.md) - see Accessibility section +7. **Selection tables**: This file (PLAN.md) - see Selection Tables section ## Regeneration Steps -1. Read preset list from types.ts -2. For each preset, get params from effects-kit -3. Apply power mappings from this file -4. Generate using preset entry format above -5. Organize by trigger category -6. Include accessibility section from this file -7. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks (tables, code blocks, etc.) +1. Check Preset Registry in this file for active presets (skip REMOVED presets) +2. Read preset type definitions from types.ts +3. For each active preset, get params from library implementation +4. Apply parameter naming conventions from this file +5. Generate using preset entry format above +6. Organize by trigger category +7. Include selection tables from this file +8. Include accessibility section from this file +9. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks + +--- + +## Intensity Value Guide (Legacy Power Reference) + +The `power` parameter was removed from presets. When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use these value mappings as guidance for suggesting appropriate parameter values. + +### Entrance Presets Intensity Values + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| -------- | ---------------- | ----------- | ------- | ------------- | +| ArcIn | easing | quintInOut | backOut | backInOut | +| BlurIn | blur | 6px | 25px | 50px | +| BounceIn | distanceFactor | 1 | 2 | 3 | +| DropIn | initialScale | 1.2 | 1.6 | 2 | +| FlipIn | initialRotate | 45° | 90° | 270° | +| FoldIn | initialRotate | 35° | 60° | 90° | +| GrowIn | initialScale | 0.8 | 0.6 | 0 | +| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | +| SpinIn | initialScale | 0.8 | 0.5 | 0 | + +### Scroll Presets Intensity Values + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| ------------- | --------- | ----------- | ------ | ------------- | +| BlurScroll | blur | 6px | 25px | 50px | +| FlipScroll | rotate | 60° | 120° | 420° | +| GrowScroll | scale | 1.2 | 1.7 | 4 | +| MoveScroll | distance | 150px | 400px | 800px | +| ShrinkScroll | scale | 0.8 | 0.3 | 0 | +| SkewPanScroll | skew | 10° | 17° | 24° | +| Spin3dScroll | rotate | 45° | 100° | 200° | +| SpinScroll | scale | 1 | 0.7 | 0.4 | +| StretchScroll | stretch | 1.2 | 1.5 | 2 | +| TiltScroll | distance | 0.25 | 0.5 | 1 | +| TurnScroll | scale | 1 | 1.3 | 1.6 | + +### Ongoing Presets Intensity Values + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| ------ | --------- | ----------- | ------ | ------------- | +| Bounce | intensity | 0.3 | 0.5 | 1 | +| Fold | angle | 15° | 30° | 45° | +| Jello | intensity | 0.25 | 0.5 | 1 | +| Poke | intensity | 0.25 | 0.5 | 1 | +| Pulse | intensity | 0 | 0.06 | 0.12 | +| Rubber | intensity | 0 | 0.05 | 0.1 | +| Swing | swing | 20° | 40° | 60° | +| Wiggle | intensity | 0.25 | 0.5 | 1 | + +### Mouse Presets Intensity Values + +| Preset | Parameter(s) | Subtle/Soft | Medium | Dramatic/Hard | +| ----------------- | ------------------ | ----------- | -------- | ------------- | +| AiryMouse | angle | 10° | 50° | 85° | +| BlobMouse | scale | 1.2 | 1.6 | 2.4 | +| BlurMouse | angle, scale | 0°, 1 | 25°, 0.7 | 65°, 0.25 | +| ScaleMouse (down) | scale | 0.85 | 0.5 | 0 | +| ScaleMouse (up) | scale | 1.2 | 1.6 | 2.4 | +| SkewMouse | angle | 10° | 20° | 45° | +| SwivelMouse | angle, perspective | 25°, 1000 | 50°, 700 | 85°, 300 | +| Tilt3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 200 | +| Track3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 333 | + +### Intensity Usage Example + +When a user asks: "I want a subtle flip entrance" + +Instead of: `{ type: 'FlipIn', power: 'soft' }` + +Suggest: `{ type: 'FlipIn', initialRotate: 45 }` + +--- + +## Migration Reference + +For users migrating from removed presets: + +| Removed Preset | Migration | +| -------------- | --------------------------------------------------------------------------- | +| GlitchIn | Use `GlideIn` with desired `angle` (default 270 = from left) | +| ExpandIn | Use `GrowIn` with `angle` and `distance` to achieve expand-from-edge effect | +| CircleIn | No direct replacement (legacy preset) | +| PunchIn | No direct replacement (legacy preset) | + +### GlideIn Default Change + +GlideIn default `angle` changed from `0` (from top) to `270` (from left) to match the more common slide-in-from-left behavior. diff --git a/packages/motion-presets/rules/presets/background-scroll.md b/packages/motion-presets/rules/presets/background-scroll.md index ae3bbb96..cf45f198 100644 --- a/packages/motion-presets/rules/presets/background-scroll.md +++ b/packages/motion-presets/rules/presets/background-scroll.md @@ -11,21 +11,21 @@ Scroll animations for structured background media components. Animates DOM eleme Requires `data-motion-part` attributes: `BG_LAYER`, `BG_MEDIA`, `BG_IMG` -## When to Use +## When to Use Background Scroll Animations - Hero sections with background depth - Full-width section backgrounds with `data-motion-part` structure - Cinematic storytelling - Section transitions -## When NOT to Use +## When NOT to Use Background Scroll Animations - Regular content elements → use [Scroll](presets-reference.md#scroll-presets) - Elements without `data-motion-part` structure - Simple CSS `background-image` (no DOM structure to animate) - Mobile with performance concerns -## Available Presets +## Available Background Scroll Presets See [Background Scroll Presets](presets-reference.md#background-scroll-presets) for details. diff --git a/packages/motion-presets/rules/presets/entrance.md b/packages/motion-presets/rules/presets/entrance.md index 2ac240fa..d5cabf80 100644 --- a/packages/motion-presets/rules/presets/entrance.md +++ b/packages/motion-presets/rules/presets/entrance.md @@ -13,50 +13,48 @@ Uses the `viewEnter` trigger (intersection observer). Plays automatically when e **Note:** For click, toggle, or other event-based triggers, implement the triggering logic separately and call the animation programmatically. -## When to Use +## When to Use Entrance Animations - Element reveals on viewport entry - First-time visibility animations - Content appearing as user scrolls down -## When NOT to Use +## When NOT to Use Entrance Animations - Scroll-driven reveals → see [Scroll](presets-reference.md#scroll) - Continuous/looping → see [Ongoing](presets-reference.md#ongoing) - Mouse-reactive → see [Mouse](presets-reference.md#mouse) -## Available Presets +## Available Entrance Presets See [Entrance Presets](presets-reference.md#entrance-presets) for full details: -FadeIn, ArcIn, BlurIn, BounceIn, CircleIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, GlitchIn, GrowIn, PunchIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn +FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, FlipIn, FloatIn, FoldIn, GlideIn, GrowIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn -## Common Parameters +## Entrance Common Parameters All entrance presets share: -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +- `duration`: 0-4000 in ms (default: 1200) +- `delay`: 0-8000 in ms (default: 0) -See [Common Parameters](presets-reference.md#common-parameters) for details on `power` behavior. +## Entrance Quick Decision -## Quick Decision +| Tone | Presets | +| ------------------- | ---------------------------------------- | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | +| Playful/Energetic | BounceIn, SpinIn | +| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | -| Tone | Presets | -| ------------------- | ----------------------------------------------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | -| Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | -| Geometric/Modern | CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn | - -## Common Use Cases +## Entrance Common Use Cases | Use Case | Recommended | | ---------------------- | -------------------------- | -| Hero sections | ArcIn, ExpandIn, FloatIn | +| Hero sections | ArcIn, FloatIn, RevealIn | | Modals/Popups | FadeIn, DropIn, GrowIn | | List items (staggered) | FadeIn, SlideIn with delay | -| Notifications | BounceIn, PunchIn | +| Notifications | BounceIn, DropIn | | Cards | FlipIn, ArcIn, TiltIn | ## Combining with Ongoing diff --git a/packages/motion-presets/rules/presets/mouse.md b/packages/motion-presets/rules/presets/mouse.md index 1b7c3488..726ddb75 100644 --- a/packages/motion-presets/rules/presets/mouse.md +++ b/packages/motion-presets/rules/presets/mouse.md @@ -7,27 +7,27 @@ trigger: mouse Animations that respond to cursor position. Desktop-only. -## When to Use +## When to Use Mouse Animations - Interactive cards/products (tilt effect) - Parallax depth with cursor - Hero section interactivity - Playful/game-like interfaces -## When NOT to Use +## When NOT to Use Mouse Animations - Mobile-first designs (won't work on touch) - Accessibility-critical interfaces - Essential functionality - Multiple simultaneous effects -## Available Presets +## Available Mouse Presets See [Mouse Presets](presets-reference.md#mouse-presets) for full details: Tilt3DMouse, TrackMouse, BounceMouse, Track3DMouse, SpinMouse, ScaleMouse, SwivelMouse, SkewMouse, BlurMouse, AiryMouse, BlobMouse, CustomMouse -## Quick Decision +## Mouse Quick Decision | Tone | Presets | | -------------------- | ------------------------------------------ | @@ -35,7 +35,7 @@ Tilt3DMouse, TrackMouse, BounceMouse, Track3DMouse, SpinMouse, ScaleMouse, Swive | Playful/Fun | BounceMouse, BlobMouse, AiryMouse | | Game-like/Dynamic | SpinMouse, Track3DMouse, SkewMouse | -## Common Use Cases +## Mouse Common Use Cases | Use Case | Recommended | | ---------------------- | ----------------------------------- | diff --git a/packages/motion-presets/rules/presets/ongoing.md b/packages/motion-presets/rules/presets/ongoing.md index 591e1292..706b3377 100644 --- a/packages/motion-presets/rules/presets/ongoing.md +++ b/packages/motion-presets/rules/presets/ongoing.md @@ -7,27 +7,27 @@ trigger: ongoing Continuous looping animations that run indefinitely. -## When to Use +## When to Use Ongoing Animations - Loading/processing indicators - Status indicators (live, active, recording) - Attention-drawing elements (notifications, CTAs) - Decorative ambient motion -## When NOT to Use +## When NOT to Use Ongoing Animations - Multiple simultaneous animations (visual chaos) - Content that needs to be read - Professional/minimal interfaces - One-time reveals → see [Entrance](presets-reference.md#entrance) -## Available Presets +## Available Ongoing Presets See [Ongoing Presets](presets-reference.md#ongoing-presets) for full details: Pulse, Bounce, Spin, Breathe, Flash, Swing, Wiggle, Flip, Fold, Jello, Rubber, Poke, Cross, DVD -## Quick Decision +## Ongoing Quick Decision | Tone | Presets | | -------------------- | ----------------------------------- | @@ -36,7 +36,7 @@ Pulse, Bounce, Spin, Breathe, Flash, Swing, Wiggle, Flip, Fold, Jello, Rubber, P | Mechanical/Technical | Spin, Flip, Fold | | Attention-grabbing | Flash, Bounce, Pulse (hard), Poke | -## Common Use Cases +## Ongoing Common Use Cases | Use Case | Recommended | | ------------------ | ----------------------- | diff --git a/packages/motion-presets/rules/presets/presets-reference.md b/packages/motion-presets/rules/presets/presets-reference.md index b4b5d548..4be3cee1 100644 --- a/packages/motion-presets/rules/presets/presets-reference.md +++ b/packages/motion-presets/rules/presets/presets-reference.md @@ -48,7 +48,7 @@ One-shot animations that play once when an element first enters the viewport. **Note:** For click, toggle, or other event-based triggers, implement the triggering logic separately and call the animation programmatically. The library only provides viewEnter as a built-in trigger for entrance animations. -**Available presets:** FadeIn, ArcIn, BlurIn, BounceIn, CircleIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, GlitchIn, GrowIn, PunchIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn +**Available presets:** FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, FlipIn, FloatIn, FoldIn, GlideIn, GrowIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn ### Scroll @@ -149,22 +149,21 @@ Scroll animations for structured background media components. Animates DOM eleme - `duration`: 100-4000ms - single cycle length - `delay`: 0-8000ms - initial wait before looping starts -### The `power` Parameter +### Coordinate System -Many presets support `power: 'soft' | 'medium' | 'hard'`. +For angle-based parameters, the library uses standard mathematical coordinates: -**Important:** `power` is a preset modifier that **overrides** fine-grained parameters when set. +- **0°** = right (east) +- **90°** = top (north) +- **180°** = left (west) +- **270°** = bottom (south) -- When `power` is provided, it sets predefined values for rotation angles, distances, scale factors, and easing curves -- For fine control, **omit `power`** and use specific parameters like `intensity`, `distanceFactor`, `initialRotate`, etc. -- Pattern: if `power` is set, specific params are ignored +### CSS Custom Properties -```typescript -// power overrides other params -{ type: 'BounceIn', power: 'hard' } // Uses hard preset (distanceFactor: 3) -{ type: 'BounceIn', distanceFactor: 2.5 } // Fine control (no power) -{ type: 'BounceIn', power: 'hard', distanceFactor: 2.5 } // power wins, distanceFactor ignored -``` +The library exposes these CSS custom properties for runtime control: + +- `--motion-opacity`: Target opacity (default: 1) +- `--motion-rotate-z`: Element rotation for scroll effects --- @@ -172,26 +171,26 @@ Many presets support `power: 'soft' | 'medium' | 'hard'`. ### By Tone -| Tone | Entrance | Scroll | Ongoing | Mouse | -| ------------------- | ----------------------------------------------- | ----------------------------------------- | -------------------------- | ------------------------------ | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (soft), Breathe | Tilt3DMouse (soft), TrackMouse | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn, ExpandIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | -| Playful/Energetic | BounceIn, SpinIn, PunchIn, GlitchIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | -| Geometric/Modern | CircleIn, ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | +| Tone | Entrance | Scroll | Ongoing | Mouse | +| ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | +| Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | +| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | ### By Use Case -| Use Case | Recommended Presets | -| ---------------------- | ------------------------------------------------------- | -| Hero sections | ArcIn, ExpandIn, FloatIn, RevealIn + BgParallax, BgZoom | -| Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | -| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | -| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | -| Notifications/Badges | BounceIn, PunchIn, DropIn + Pulse | -| CTAs/Buttons | BounceIn, PunchIn, GrowIn + Pulse | -| Loading indicators | Spin, Pulse | -| Product images | Tilt3DMouse, ScaleMouse | -| Background depth | BgParallax, ParallaxScroll, TrackMouse (layered) | +| Use Case | Recommended Presets | +| ---------------------- | ------------------------------------------------ | +| Hero sections | ArcIn, FloatIn, RevealIn + BgParallax, BgZoom | +| Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | +| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | +| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | +| Notifications/Badges | BounceIn, DropIn + Pulse | +| CTAs/Buttons | BounceIn, GrowIn + Pulse | +| Loading indicators | Spin, Pulse | +| Product images | Tilt3DMouse, ScaleMouse | +| Background depth | BgParallax, ParallaxScroll, TrackMouse (layered) | ### Cross-Category Parallels @@ -259,13 +258,13 @@ Visual: Element swings in along a curved 3D path, like a door opening. Dramatic, Parameters: - `direction`: top | right | bottom | left (default: left) -- `power`: soft | medium | hard (default: medium) - -**When `power` is set:** controls rotation intensity and easing curve +- `perspective`: 3D perspective depth (default: 800) +- `angle`: arc rotation angle (default: 80) +- `depth`: Z translation distance (default: 300) ```typescript { type: 'ArcIn', direction: 'bottom' } -{ type: 'ArcIn', direction: 'left', power: 'hard' } // Dramatic hero entrance +{ type: 'ArcIn', direction: 'left', angle: 120 } // Dramatic hero entrance ``` #### BlurIn @@ -274,15 +273,12 @@ Visual: Element transitions from blurry to sharp focus while fading in. Soft, dr Parameters: -- `blur`: blur amount in px (default varies) -- `power`: soft | medium | hard - -**When `power` is set:** overrides `blur` (soft=6, medium=25, hard=50) +- `blur`: blur amount in px (default: 25) ```typescript { type: 'BlurIn' } -{ type: 'BlurIn', power: 'soft' } -{ type: 'BlurIn', blur: 15 } // Custom blur, no power +{ type: 'BlurIn', blur: 6 } // Subtle blur +{ type: 'BlurIn', blur: 50 } // Dramatic blur ``` #### BounceIn @@ -292,29 +288,13 @@ Visual: Element bounces into view with spring physics. Playful, attention-grabbi Parameters: - `direction`: top | right | bottom | left | center (default: top) -- `power`: soft | medium | hard (default: soft) - `distanceFactor`: 1-4 (default: 1) - -**When `power` is set:** overrides `distanceFactor` (soft=1, medium=2, hard=3) +- `perspective`: 3D perspective for center direction (default: 800) ```typescript { type: 'BounceIn' } -{ type: 'BounceIn', direction: 'center', power: 'medium' } // Reward popup -{ type: 'BounceIn', distanceFactor: 2.5 } // Custom distance, no power -``` - -#### CircleIn - -Visual: Circular mask expanding from center to reveal element. Geometric, spotlight-like. - -Parameters: - -- `direction`: in | out (default: in) -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) - -```typescript -{ type: 'CircleIn', direction: 'in' } +{ type: 'BounceIn', direction: 'center', distanceFactor: 2 } // Reward popup +{ type: 'BounceIn', distanceFactor: 2.5 } // Custom distance ``` #### CurveIn @@ -337,31 +317,11 @@ Visual: Falls from above with subtle scale/bounce on landing. Gravity-like, natu Parameters: -- `power`: soft | medium | hard -- `initialScale`: starting scale (default varies) - -**When `power` is set:** overrides `initialScale` and easing (soft: 1.2/cubicInOut, medium: 1.6/quintInOut, hard: 2/backOut) +- `initialScale`: starting scale (default: 1.6) ```typescript { type: 'DropIn' } -{ type: 'DropIn', power: 'medium' } -``` - -#### ExpandIn - -Visual: Expands outward from a point. Growing, revealing emergence. - -Parameters: - -- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center -- `power`: soft | medium | hard -- `initialScale`: starting scale - -**When `power` is set:** controls scale and easing intensity - -```typescript -{ type: 'ExpandIn', direction: 'center' } -{ type: 'ExpandIn', direction: 'bottom-left', power: 'hard' } +{ type: 'DropIn', initialScale: 2 } // More dramatic ``` #### FlipIn @@ -371,14 +331,12 @@ Visual: 3D card flip rotation to reveal element. Dramatic, card-like metaphor. Parameters: - `direction`: top | right | bottom | left -- `power`: soft | medium | hard -- `initialRotate`: starting rotation degrees - -**When `power` is set:** overrides `initialRotate` (soft=45, medium=90, hard=270) +- `initialRotate`: starting rotation degrees (default: 90) +- `perspective`: 3D perspective depth (default: 800) ```typescript { type: 'FlipIn', direction: 'left' } -{ type: 'FlipIn', direction: 'top', power: 'hard' } +{ type: 'FlipIn', direction: 'top', initialRotate: 270 } // Dramatic flip ``` #### FloatIn @@ -402,13 +360,12 @@ Visual: Paper-folding 3D effect. Origami-like, creative. Parameters: - `direction`: top | right | bottom | left -- `power`: soft | medium | hard -- `initialRotate`: starting rotation degrees - -**When `power` is set:** overrides `initialRotate` (soft=35, medium=60, hard=90) +- `initialRotate`: starting rotation degrees (default: 60) +- `perspective`: 3D perspective depth (default: 800) ```typescript { type: 'FoldIn', direction: 'left' } +{ type: 'FoldIn', direction: 'top', initialRotate: 90 } // More dramatic fold ``` #### GlideIn @@ -417,65 +374,27 @@ Visual: Smooth 2D glide from direction with angle control. Clean, directional. Parameters: -- `direction`: angle in degrees (0-360) +- `angle`: angle in degrees (default: 270, from left). 0° = right, 90° = top, 180° = left, 270° = bottom - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `power`: soft | medium | hard -- `startFromOffScreen`: boolean - -**When `power` is set:** controls easing curve intensity ```typescript -{ type: 'GlideIn', direction: 180, distance: { value: 100, type: 'px' } } -``` - -#### GlitchIn - -Visual: Digital glitch/distortion effect. Edgy, tech-inspired. - -Parameters: - -- `direction`: angle in degrees -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `power`: soft | medium | hard -- `startFromOffScreen`: boolean - -**When `power` is set:** controls glitch intensity - -```typescript -{ type: 'GlitchIn', direction: 0, distance: { value: 50, type: 'px' } } +{ type: 'GlideIn', angle: 270, distance: { value: 100, type: 'px' } } // From left (default) +{ type: 'GlideIn', angle: 90, distance: { value: 50, type: 'percentage' } } // From top ``` #### GrowIn -Visual: Scale from small to full size. Expanding, emerging. - -Parameters: - -- `direction`: angle in degrees -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `power`: soft | medium | hard -- `initialScale`: starting scale (0-1) - -**When `power` is set:** controls scale and easing intensity - -```typescript -{ type: 'GrowIn', direction: 0, distance: { value: 0, type: 'px' } } -``` - -#### PunchIn - -Visual: Corner-based scale with energy and impact. Punchy, attention-grabbing. +Visual: Scale from small to full size with optional directional movement. Expanding, emerging. Parameters: -- `direction`: top-left | top-right | bottom-left | bottom-right | center -- `power`: soft | medium | hard - -**When `power` is set:** controls easing curve (soft=sineIn, medium=quadIn, hard=quintIn) +- `angle`: angle in degrees (default: 0). 0° = right, 90° = top, 180° = left, 270° = bottom +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: 120px) +- `initialScale`: starting scale 0-1 (default: 0.6) ```typescript -{ type: 'PunchIn', direction: 'center' } -{ type: 'PunchIn', direction: 'bottom-right', power: 'hard' } +{ type: 'GrowIn', angle: 0, distance: { value: 0, type: 'px' } } // Pure scale, no movement +{ type: 'GrowIn', angle: 270, distance: { value: 100, type: 'px' }, initialScale: 0.3 } // From bottom with dramatic scale ``` #### RevealIn @@ -517,9 +436,6 @@ Parameters: - `direction`: top | right | bottom | left - `shutters`: number of strips - `staggered`: boolean (animate strips sequentially) -- `power`: soft | medium | hard - -**When `power` is set:** controls easing curve intensity ```typescript { type: 'ShuttersIn', direction: 'left', shutters: 5, staggered: true } @@ -532,14 +448,11 @@ Visual: Straight movement from direction. Clean, simple, versatile. Parameters: - `direction`: top | right | bottom | left -- `power`: soft | medium | hard -- `initialTranslate`: starting offset - -**When `power` is set:** controls easing curve intensity +- `initialTranslate`: starting offset (0-1, default: 1) ```typescript { type: 'SlideIn', direction: 'bottom' } -{ type: 'SlideIn', direction: 'left', power: 'soft' } +{ type: 'SlideIn', direction: 'left', initialTranslate: 0.2 } // Subtle slide ``` #### SpinIn @@ -550,13 +463,11 @@ Parameters: - `direction`: clockwise | counter-clockwise - `spins`: number of rotations -- `power`: soft | medium | hard -- `initialScale`: starting scale - -**When `power` is set:** controls easing curve intensity +- `initialScale`: starting scale (default: 0) ```typescript { type: 'SpinIn', direction: 'clockwise', spins: 1 } +{ type: 'SpinIn', direction: 'counter-clockwise', spins: 2, initialScale: 0.5 } ``` #### TiltIn @@ -580,12 +491,11 @@ Visual: Corner-pivot 3D rotation. Complex, dramatic, premium. Parameters: - `direction`: top-left | top-right | bottom-left | bottom-right -- `power`: soft | medium | hard -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +- `angle`: rotation angle (default: 50) ```typescript { type: 'TurnIn', direction: 'bottom-left' } +{ type: 'TurnIn', direction: 'top-right', angle: 80 } // More dramatic ``` #### WinkIn @@ -658,15 +568,12 @@ Visual: Blur/unblur effect controlled by scroll. Focus transitions. Parameters: -- `power`: soft | medium | hard - `range`: in | out | continuous -- `blur`: blur amount in px - -**When `power` is set:** overrides `blur` (soft=6, medium=25, hard=50) +- `blur`: blur amount in px (default: 25) ```typescript { type: 'BlurScroll', range: 'in' } -{ type: 'BlurScroll', range: 'out', power: 'medium' } +{ type: 'BlurScroll', range: 'out', blur: 50 } // More dramatic ``` #### FlipScroll @@ -675,16 +582,14 @@ Visual: Full 3D card flip driven by scroll. Dramatic rotation. Parameters: -- `direction`: vertical | horizontal -- `power`: soft | medium | hard +- `axis`: vertical | horizontal - `range`: in | out | continuous -- `rotate`: rotation degrees - -**When `power` is set:** overrides `rotate` (soft=60, medium=120, hard=420) +- `rotate`: rotation degrees (default: 120) +- `perspective`: 3D perspective depth (default: 800) ```typescript -{ type: 'FlipScroll', direction: 'horizontal' } -{ type: 'FlipScroll', direction: 'vertical', range: 'in' } +{ type: 'FlipScroll', axis: 'horizontal' } +{ type: 'FlipScroll', axis: 'vertical', range: 'in', rotate: 420 } // Multiple rotations ``` #### GrowScroll @@ -694,16 +599,13 @@ Visual: Scale up as element enters viewport. Parameters: - `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center -- `power`: soft | medium | hard - `range`: in | out | continuous -- `scale`: target scale +- `scale`: target scale (default: 1.7) - `speed`: animation speed -**When `power` is set:** overrides scale range (soft: 0.8-1.2, medium: 0.3-1.7, hard: 0-4) - ```typescript { type: 'GrowScroll', direction: 'center' } -{ type: 'GrowScroll', direction: 'center', range: 'in' } +{ type: 'GrowScroll', direction: 'center', range: 'in', scale: 4 } // Dramatic scale ``` #### ShrinkScroll @@ -713,15 +615,13 @@ Visual: Scale down as element exits viewport. Parameters: - `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center -- `power`: soft | medium | hard - `range`: in | out | continuous -- `scale`: target scale +- `scale`: target scale (default: 0.3) - `speed`: animation speed -**When `power` is set:** overrides scale range (soft: 1.2-0.8, medium: 1.7-0.3, hard: 3.5-0) - ```typescript { type: 'ShrinkScroll', direction: 'center', range: 'out' } +{ type: 'ShrinkScroll', direction: 'center', scale: 0 } // Shrink to nothing ``` #### MoveScroll @@ -730,15 +630,13 @@ Visual: Translation movement on scroll in any direction. Parameters: -- `angle`: 0-360 degrees -- `power`: soft | medium | hard +- `angle`: 0-360 degrees. 0° = right, 90° = top, 180° = left, 270° = bottom - `range`: in | out | continuous -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } - -**When `power` is set:** overrides `distance` (soft=150px, medium=400px, hard=800px) +- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: 400px) ```typescript { type: 'MoveScroll', angle: 90, distance: { value: 100, type: 'px' } } +{ type: 'MoveScroll', angle: 0, distance: { value: 800, type: 'px' } } // Long horizontal move ``` #### PanScroll @@ -778,13 +676,11 @@ Parameters: - `shape`: circle | ellipse | rectangle | diamond | window - `range`: in | out | continuous -- `power`: soft | medium | hard -- `intensity`: 0-1 - -**When `power` is set:** overrides clipPath intensity (varies by shape) +- `intensity`: 0-1 (default: varies by shape) ```typescript { type: 'ShapeScroll', shape: 'circle' } +{ type: 'ShapeScroll', shape: 'diamond', intensity: 0.8 } ``` #### ShuttersScroll @@ -810,13 +706,11 @@ Parameters: - `direction`: left | right - `range`: in | out | continuous -- `power`: soft | medium | hard -- `skew`: skew angle - -**When `power` is set:** overrides `skew` (soft=10, medium=17, hard=24) +- `skew`: skew angle (default: 17) ```typescript { type: 'SkewPanScroll', direction: 'left' } +{ type: 'SkewPanScroll', direction: 'right', skew: 24 } // More dramatic ``` #### SlideScroll @@ -840,15 +734,13 @@ Visual: 3D rotation around axis on scroll. Parameters: - `range`: in | out | continuous -- `power`: soft | medium | hard -- `rotate`: rotation degrees +- `rotate`: rotation degrees (default: 100) - `speed`: animation speed - -**When `power` is set:** overrides rotation and travel (soft: 45deg/0, medium: 100deg/0.5, hard: 200deg/1) +- `perspective`: 3D perspective depth (default: 1000) ```typescript { type: 'Spin3dScroll' } -{ type: 'Spin3dScroll', range: 'continuous' } +{ type: 'Spin3dScroll', range: 'continuous', rotate: 200 } // More dramatic ``` #### SpinScroll @@ -860,13 +752,11 @@ Parameters: - `direction`: clockwise | counter-clockwise - `spins`: number of rotations - `range`: in | out | continuous -- `power`: soft | medium | hard -- `scale`: scale factor - -**When `power` is set:** overrides `scale` (soft=1, medium=0.7, hard=0.4) +- `scale`: scale factor (default: 0.7) ```typescript { type: 'SpinScroll', direction: 'clockwise', spins: 1 } +{ type: 'SpinScroll', direction: 'counter-clockwise', spins: 2, scale: 0.4 } ``` #### StretchScroll @@ -875,15 +765,12 @@ Visual: Stretch/squeeze deformation on scroll. Parameters: -- `power`: soft | medium | hard - `range`: in | out | continuous -- `stretch`: stretch amount - -**When `power` is set:** overrides scaleX/scaleY (soft: 0.8/1.2, medium: 0.6/1.5, hard: 0.4/2) +- `stretch`: stretch amount (default: 1.5) ```typescript { type: 'StretchScroll' } -{ type: 'StretchScroll', power: 'medium' } +{ type: 'StretchScroll', stretch: 2 } // More dramatic ``` #### TiltScroll @@ -894,13 +781,12 @@ Parameters: - `direction`: left | right - `range`: in | out | continuous -- `power`: soft | medium | hard -- `distance`: tilt distance - -**When `power` is set:** overrides `distance` (soft=0, medium=0.5, hard=1) +- `distance`: tilt distance (default: 0.5) +- `perspective`: 3D perspective depth (default: 400) ```typescript { type: 'TiltScroll', direction: 'left' } +{ type: 'TiltScroll', direction: 'right', distance: 1 } // More dramatic ``` #### TurnScroll @@ -912,13 +798,11 @@ Parameters: - `direction`: left | right - `spin`: clockwise | counter-clockwise - `range`: in | out | continuous -- `power`: soft | medium | hard -- `scale`: scale factor - -**When `power` is set:** overrides scale range (soft: 1/1, medium: 0.7/1.3, hard: 0.4/1.6) +- `scale`: scale factor (default: 1.3) ```typescript { type: 'TurnScroll', direction: 'left', spin: 'clockwise' } +{ type: 'TurnScroll', direction: 'right', spin: 'counter-clockwise', scale: 1.6 } ``` --- @@ -931,15 +815,11 @@ Visual: Gentle scale oscillation, heartbeat-like rhythm. Subtle, universal. Parameters: -- `power`: soft | medium | hard (default: soft) -- `intensity`: 0-1 (default: 0) - -**When `power` is set:** overrides `intensity`/pulse magnitude (soft=0, medium=0.06, hard=0.12) +- `intensity`: 0-1 (default: 0.06) ```typescript { type: 'Pulse' } -{ type: 'Pulse', power: 'medium' } // Status indicator -{ type: 'Pulse', intensity: 0.04 } // Custom intensity, no power +{ type: 'Pulse', intensity: 0.12 } // More dramatic ``` #### Bounce @@ -948,14 +828,11 @@ Visual: Vertical bouncing motion like a ball on trampoline. Playful, energetic. Parameters: -- `power`: soft | medium | hard (default: soft) - `intensity`: 0-1 (default: 0.3) -**When `power` is set:** overrides `intensity`/bounce factor (soft=1, medium=2, hard=3) - ```typescript { type: 'Bounce' } -{ type: 'Bounce', power: 'medium' } // Playful mascot +{ type: 'Bounce', intensity: 0.6 } // More energetic ``` #### Spin @@ -965,9 +842,6 @@ Visual: Continuous rotation around center. Mechanical, precise. Parameters: - `direction`: clockwise | counter-clockwise (default: clockwise) -- `power`: soft | medium | hard (default: soft) - -**When `power` is set:** controls easing curve (linear → eased → bouncy) ```typescript { type: 'Spin', direction: 'clockwise' } @@ -1008,15 +882,12 @@ Visual: Rotation oscillation like a pendulum. Back and forth rhythmic. Parameters: -- `power`: soft | medium | hard -- `swing`: swing angle +- `swing`: swing angle (default: 40) - `direction`: top | right | bottom | left -**When `power` is set:** overrides `swing` angle (soft: 20deg, medium: 40deg, hard: 60deg) - ```typescript { type: 'Swing' } -{ type: 'Swing', power: 'medium' } +{ type: 'Swing', swing: 60 } // More dramatic ``` #### Wiggle @@ -1025,14 +896,11 @@ Visual: Horizontal shake/wiggle. Side-to-side for attention. Parameters: -- `power`: soft | medium | hard -- `intensity`: 0-1 - -**When `power` is set:** overrides `intensity`/wiggle factor (soft=1, medium=2, hard=4) +- `intensity`: 0-1 (default: 0.5) ```typescript { type: 'Wiggle' } -{ type: 'Wiggle', power: 'soft' } +{ type: 'Wiggle', intensity: 1 } // More vigorous ``` #### Flip @@ -1041,13 +909,10 @@ Visual: Periodic 180° flips. Card-like rotation showing front/back. Parameters: -- `direction`: vertical | horizontal -- `power`: soft | medium | hard - -**When `power` is set:** controls easing curve intensity +- `axis`: vertical | horizontal ```typescript -{ type: 'Flip', direction: 'horizontal' } +{ type: 'Flip', axis: 'horizontal' } ``` #### Fold @@ -1057,13 +922,11 @@ Visual: 3D folding motion. Paper-like folding and unfolding. Parameters: - `direction`: top | right | bottom | left -- `power`: soft | medium | hard -- `angle`: fold angle - -**When `power` is set:** overrides `angle` (soft: 15deg, medium: 30deg, hard: 45deg) +- `angle`: fold angle (default: 30) ```typescript { type: 'Fold', direction: 'left' } +{ type: 'Fold', direction: 'top', angle: 45 } // More dramatic ``` #### Jello @@ -1072,14 +935,11 @@ Visual: Wobbly elastic deformation. Jiggly, bouncy distortion. Parameters: -- `power`: soft | medium | hard -- `intensity`: 0-1 - -**When `power` is set:** overrides `intensity`/jello factor (soft=1, medium=2, hard=4) +- `intensity`: 0-1 (default: 0.5) ```typescript { type: 'Jello' } -{ type: 'Jello', power: 'medium' } +{ type: 'Jello', intensity: 1 } // More wobbly ``` #### Rubber @@ -1088,15 +948,11 @@ Visual: Elastic stretch effect. Springy stretching and snapping. Parameters: -- `power`: soft | medium | hard -- `intensity`: 0-1 - -**When `power` is set:** overrides `intensity`/rubber offset (soft=0, medium=0.05, hard=0.1) +- `intensity`: 0-1 (default: 0.05) ```typescript -{ - type: 'Rubber'; -} +{ type: 'Rubber' } +{ type: 'Rubber', intensity: 0.1 } // More stretchy ``` #### Poke @@ -1106,13 +962,11 @@ Visual: Quick scale bump like being tapped. Brief attention "boop". Parameters: - `direction`: top | right | bottom | left -- `power`: soft | medium | hard -- `intensity`: 0-1 - -**When `power` is set:** overrides `intensity`/poke factor (soft=1, medium=2, hard=4) +- `intensity`: 0-1 (default: 0.5) ```typescript { type: 'Poke', direction: 'top' } +{ type: 'Poke', direction: 'right', intensity: 1 } // More dramatic ``` #### Cross @@ -1133,7 +987,6 @@ Visual: Corner-to-corner bounce (DVD screensaver). Nostalgic, retro. Parameters: -- `power`: soft | medium | hard - `duration`: 100-4000ms (default: 1200) - `delay`: 0-8000ms (default: 0) @@ -1153,17 +1006,14 @@ Visual: Element tilts toward cursor in 3D, like angling a card. Premium, interac Parameters: -- `power`: soft | medium | hard (default: medium) - `angle`: 5-85 degrees (default: 50) -- `perspective`: 200-1000px (default: 800) +- `perspective`: 200-1000px (default: 500) - `inverted`: boolean (default: false) -**When `power` is set:** overrides `angle` and `perspective` (soft: 25/1000, medium: 50/500, hard: 85/200) - ```typescript { type: 'Tilt3DMouse' } -{ type: 'Tilt3DMouse', power: 'soft' } // Subtle professional -{ type: 'Tilt3DMouse', angle: 15, perspective: 1000 } // Custom, no power +{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } // Subtle professional +{ type: 'Tilt3DMouse', angle: 85, perspective: 200 } // Dramatic ``` #### TrackMouse @@ -1174,11 +1024,8 @@ Parameters: - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: { value: 250, type: 'px' }) - `axis`: horizontal | vertical | both (default: both) -- `power`: soft | medium | hard (default: medium) - `inverted`: boolean (default: false) -**When `power` is set:** overrides easing (soft=linear, medium=easeOut, hard=hardBackOut) - ```typescript { type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } { type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'horizontal' } // Background layer @@ -1192,11 +1039,8 @@ Parameters: - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: { value: 80, type: 'px' }) - `axis`: horizontal | vertical | both (default: both) -- `power`: soft | medium | hard - `inverted`: boolean (default: false) -**When `power` is set:** controls spring easing behavior - ```typescript { type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } ``` @@ -1208,16 +1052,14 @@ Visual: Combined translation + 3D rotation following mouse. Complex, immersive. Parameters: - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `angle`: rotation angle +- `angle`: rotation angle (default: 50) - `axis`: horizontal | vertical | both -- `perspective`: perspective distance -- `power`: soft | medium | hard +- `perspective`: perspective distance (default: 500) - `inverted`: boolean -**When `power` is set:** overrides `angle` and `perspective` (soft: 25/1000, medium: 50/500, hard: 85/333) - ```typescript { type: 'Track3DMouse', distance: { value: 100, type: 'px' }, axis: 'both' } +{ type: 'Track3DMouse', distance: { value: 50, type: 'px' }, angle: 25, perspective: 1000 } // Subtle ``` #### SpinMouse @@ -1227,11 +1069,8 @@ Visual: Rotation following mouse angle. Element spins based on cursor position. Parameters: - `axis`: horizontal | vertical | both -- `power`: soft | medium | hard - `inverted`: boolean -**When `power` is set:** controls rotation intensity and easing - ```typescript { type: 'SpinMouse' } { type: 'SpinMouse', axis: 'both' } @@ -1245,15 +1084,13 @@ Parameters: - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } - `axis`: horizontal | vertical | both -- `scale`: scale factor -- `power`: soft | medium | hard +- `scale`: scale factor (default: depends on scaleDirection) - `scaleDirection`: in | out - `inverted`: boolean -**When `power` is set:** overrides `scale` (varies by scaleDirection - down: 0.85/0.5/0, up: 1.2/1.6/2.4) - ```typescript { type: 'ScaleMouse', distance: { value: 100, type: 'px' }, scaleDirection: 'in' } +{ type: 'ScaleMouse', distance: { value: 100, type: 'px' }, scaleDirection: 'out', scale: 2.4 } // Dramatic grow ``` #### SwivelMouse @@ -1262,18 +1099,14 @@ Visual: Z-axis rotation following cursor. Gyroscope-like vertical rotation. Parameters: -- `angle`: rotation angle -- `perspective`: perspective distance +- `angle`: rotation angle (default: 50) +- `perspective`: perspective distance (default: 700) - `pivotAxis`: top | bottom | right | left | center-horizontal | center-vertical -- `power`: soft | medium | hard - `inverted`: boolean -**When `power` is set:** overrides `angle` and `perspective` (soft: 25/1000, medium: 50/700, hard: 85/300) - ```typescript -{ - type: 'SwivelMouse'; -} +{ type: 'SwivelMouse' } +{ type: 'SwivelMouse', angle: 25, perspective: 1000 } // Subtle ``` #### SkewMouse @@ -1283,17 +1116,13 @@ Visual: Skew distortion following cursor. Angular distortion. Parameters: - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `angle`: skew angle +- `angle`: skew angle (default: 20) - `axis`: horizontal | vertical | both -- `power`: soft | medium | hard - `inverted`: boolean -**When `power` is set:** overrides `angle` (soft=10, medium=20, hard=45) - ```typescript -{ - type: 'SkewMouse'; -} +{ type: 'SkewMouse' } +{ type: 'SkewMouse', angle: 45 } // More dramatic ``` #### BlurMouse @@ -1303,19 +1132,15 @@ Visual: Blur based on cursor distance. Focus/defocus by proximity. Parameters: - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `angle`: angle -- `scale`: scale factor +- `angle`: angle (default: 25) +- `scale`: scale factor (default: 0.7) - `blur`: blur amount - `perspective`: perspective distance -- `power`: soft | medium | hard - `inverted`: boolean -**When `power` is set:** overrides `angle` and `scale` (soft: 0/1, medium: 25/0.7, hard: 65/0.25) - ```typescript -{ - type: 'BlurMouse'; -} +{ type: 'BlurMouse' } +{ type: 'BlurMouse', angle: 65, scale: 0.25 } // More dramatic ``` #### AiryMouse @@ -1326,16 +1151,12 @@ Parameters: - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } - `axis`: horizontal | vertical | both -- `angle`: angle -- `power`: soft | medium | hard +- `angle`: angle (default: 50) - `inverted`: boolean -**When `power` is set:** overrides `angle` (soft=10, medium=50, hard=85) - ```typescript -{ - type: 'AiryMouse'; -} +{ type: 'AiryMouse' } +{ type: 'AiryMouse', angle: 10 } // Subtle ``` #### BlobMouse @@ -1345,16 +1166,12 @@ Visual: Organic blob-like deformation. Fluid shape distortion. Parameters: - `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `scale`: scale factor -- `power`: soft | medium | hard +- `scale`: scale factor (default: 1.6) - `inverted`: boolean -**When `power` is set:** overrides `scale` (soft=1.2, medium=1.6, hard=2.4) - ```typescript -{ - type: 'BlobMouse'; -} +{ type: 'BlobMouse' } +{ type: 'BlobMouse', scale: 2.4 } // More dramatic ``` #### CustomMouse @@ -1562,22 +1379,21 @@ The presets provide animations; the host platform decides when and whether to ap **Medium risk** (strong motion, may affect some users): -- GlitchIn, PunchIn, TurnIn +- TurnIn - ParallaxScroll, BgParallax at high speed values **Low risk / safe** (opacity/blur changes, minimal spatial movement): - FadeIn, FadeScroll, BlurIn, BlurScroll -- SlideIn (soft), GlideIn (soft) -- Pulse (soft), Breathe +- SlideIn (subtle settings), GlideIn (subtle settings) +- Pulse (low intensity), Breathe ### Reduced Motion Fallback Table | Original | Fallback | | --------------------------------- | ------------------------- | -| BounceIn, SpinIn, PunchIn | FadeIn | +| BounceIn, SpinIn | FadeIn | | ArcIn, FlipIn, TurnIn | FadeIn | -| GlitchIn | FadeIn | | Spin, Bounce, Wiggle | Stop or subtle Pulse | | Flash | Reduce frequency (<3/sec) | | ParallaxScroll | Static position | @@ -1665,7 +1481,7 @@ For lists/grids, apply increasing subtle `delay` values // Outer container - entrance { type: 'FadeIn' } // Inner container - mouse interaction -{ type: 'Tilt3DMouse', power: 'soft' } +{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } // subtle ``` **Hero with depth (separate elements):** @@ -1674,15 +1490,15 @@ For lists/grids, apply increasing subtle `delay` values // Background element { type: 'BgParallax', speed: 0.2 } // Content element -{ type: 'ArcIn', direction: 'bottom', power: 'medium' } +{ type: 'ArcIn', direction: 'bottom' } ``` **Notification badge (single element - entrance + ongoing supported):** ```typescript // Same element can have both -{ type: 'BounceIn', direction: 'top', power: 'soft' } // entrance -{ type: 'Pulse', power: 'soft' } // ongoing +{ type: 'BounceIn', direction: 'top', distanceFactor: 1 } // entrance, subtle +{ type: 'Pulse', intensity: 0.06 } // ongoing ``` **Loading indicator:** @@ -1690,3 +1506,72 @@ For lists/grids, apply increasing subtle `delay` values ```typescript { type: 'Spin', direction: 'clockwise', duration: 1500 } ``` + +--- + +## 7. Intensity Value Guide + +When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use these value mappings as guidance for suggesting appropriate parameter values. + +### Entrance Presets Intensity Values + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| -------- | ---------------- | ----------- | ------- | ------------- | +| ArcIn | easing | quintInOut | backOut | backInOut | +| BlurIn | blur | 6px | 25px | 50px | +| BounceIn | distanceFactor | 1 | 2 | 3 | +| DropIn | initialScale | 1.2 | 1.6 | 2 | +| FlipIn | initialRotate | 45° | 90° | 270° | +| FoldIn | initialRotate | 35° | 60° | 90° | +| GrowIn | initialScale | 0.8 | 0.6 | 0 | +| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | +| SpinIn | initialScale | 0.8 | 0.5 | 0 | + +### Scroll Presets Intensity Values + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| ------------- | --------- | ----------- | ------ | ------------- | +| BlurScroll | blur | 6px | 25px | 50px | +| FlipScroll | rotate | 60° | 120° | 420° | +| GrowScroll | scale | 1.2 | 1.7 | 4 | +| MoveScroll | distance | 150px | 400px | 800px | +| ShrinkScroll | scale | 0.8 | 0.3 | 0 | +| SkewPanScroll | skew | 10° | 17° | 24° | +| Spin3dScroll | rotate | 45° | 100° | 200° | +| SpinScroll | scale | 1 | 0.7 | 0.4 | +| StretchScroll | stretch | 1.2 | 1.5 | 2 | +| TiltScroll | distance | 0.25 | 0.5 | 1 | +| TurnScroll | scale | 1 | 1.3 | 1.6 | + +### Ongoing Presets Intensity Values + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| ------ | --------- | ----------- | ------ | ------------- | +| Bounce | intensity | 0.3 | 0.5 | 1 | +| Fold | angle | 15° | 30° | 45° | +| Jello | intensity | 0.25 | 0.5 | 1 | +| Poke | intensity | 0.25 | 0.5 | 1 | +| Pulse | intensity | 0 | 0.06 | 0.12 | +| Rubber | intensity | 0 | 0.05 | 0.1 | +| Swing | swing | 20° | 40° | 60° | +| Wiggle | intensity | 0.25 | 0.5 | 1 | + +### Mouse Presets Intensity Values + +| Preset | Parameter(s) | Subtle/Soft | Medium | Dramatic/Hard | +| ----------------- | ------------------ | ----------- | -------- | ------------- | +| AiryMouse | angle | 10° | 50° | 85° | +| BlobMouse | scale | 1.2 | 1.6 | 2.4 | +| BlurMouse | angle, scale | 0°, 1 | 25°, 0.7 | 65°, 0.25 | +| ScaleMouse (down) | scale | 0.85 | 0.5 | 0 | +| ScaleMouse (up) | scale | 1.2 | 1.6 | 2.4 | +| SkewMouse | angle | 10° | 20° | 45° | +| SwivelMouse | angle, perspective | 25°, 1000 | 50°, 700 | 85°, 300 | +| Tilt3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 200 | +| Track3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 333 | + +### Usage Example + +When a user asks: "I want a subtle flip entrance" + +Suggest: `{ type: 'FlipIn', initialRotate: 45 }` diff --git a/packages/motion-presets/rules/presets/scroll.md b/packages/motion-presets/rules/presets/scroll.md index a7457e45..0389c26e 100644 --- a/packages/motion-presets/rules/presets/scroll.md +++ b/packages/motion-presets/rules/presets/scroll.md @@ -7,32 +7,32 @@ trigger: scroll Animations tied to scroll position. Can animate in, out, or continuously. -## When to Use +## When to Use Scroll Animations - Progressive content reveals on scroll - Parallax depth effects - Storytelling tied to scroll progress - De-emphasizing passed content -## When NOT to Use +## When NOT to Use Scroll Animations - One-time entrance → see [Entrance](presets-reference.md#entrance) (more performant) - Continuous loops → see [Ongoing](presets-reference.md#ongoing) - Background images → see [Background Scroll](presets-reference.md#background-scroll) -## Available Presets +## Available Scroll Presets See [Scroll Presets](presets-reference.md#scroll-presets) for full details: ParallaxScroll, FadeScroll, ArcScroll, BlurScroll, FlipScroll, GrowScroll, ShrinkScroll, MoveScroll, PanScroll, RevealScroll, ShapeScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll -## Range Modes +## Scroll Range Modes - `in`: Animates as element enters viewport (0% → 50%) - `out`: Animates as element exits viewport (50% → 100%) - `continuous`: Animates throughout entire scroll range -## Quick Decision +## Scroll Quick Decision | Effect Type | Presets | | ----------- | -------------------------------------------------- | @@ -42,7 +42,7 @@ ParallaxScroll, FadeScroll, ArcScroll, BlurScroll, FlipScroll, GrowScroll, Shrin | 3D Rotation | ArcScroll, FlipScroll, TiltScroll, TurnScroll | | Reveal/Mask | RevealScroll, ShapeScroll, ShuttersScroll | -## Common Use Cases +## Scroll Common Use Cases | Use Case | Recommended | | ------------------- | ------------------------------------ | From f44bac564be6dae1d5ab13558fe897b1825e1789 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Thu, 12 Feb 2026 11:22:40 +0200 Subject: [PATCH 13/20] Apply suggestion from @ydaniv Co-authored-by: Yehonatan Daniv --- packages/motion-presets/rules/presets/PLAN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 96da2932..9526cc2d 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -221,7 +221,7 @@ distance: { value: 10, type: 'vh' } // viewport height The library uses these CSS custom properties for runtime control: - `--motion-opacity`: Target opacity (default: 1) -- `--motion-rotate-z`: Element rotation for scroll effects +- `--motion-rotate`: Element rotation for scroll effects --- From ad792677e316199cf0a320ceb4de69e8de4e3c62 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Thu, 12 Feb 2026 13:53:05 +0200 Subject: [PATCH 14/20] Address PR review feedback on PLAN.md - Rewrite trigger mechanisms as preset categories (not triggers) - Remove background scroll section (not functional yet) - Remove Status column and deleted presets from registry tables - Clarify animation options vs preset parameters (duration/delay are config-level) - Fix intensity values to match actual code powermaps (ArcIn, SpinIn, TiltScroll, ongoing presets) - Remove power reference from intensity guide heading - Add conditions note for reduced motion in accessibility section - Rewrite combining animations as general rules about CSS property conflicts - Remove migration reference and merge data sources into regeneration steps - Clean up Bg* preset references, fix desktop-only claim for mouse presets - Trim parameter naming conventions to overloaded names only (direction) - Remove --motion-opacity (unused), update distance units documentation Co-authored-by: Cursor --- packages/motion-presets/rules/presets/PLAN.md | 359 ++++++++---------- 1 file changed, 153 insertions(+), 206 deletions(-) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 9526cc2d..25332ca5 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -1,6 +1,6 @@ --- name: LLM Preset Rules -overview: Consolidated single-file reference with lightweight trigger entry points. +overview: Consolidated single-file reference with category-specific preset guides. status: in-progress version: 2.0 last-updated: 2026-02-01 @@ -15,11 +15,10 @@ This file serves as the **source of truth** for regenerating `presets-reference. ```text rules/presets/ ├── presets-reference.md # Comprehensive reference (all presets, all info) -├── entrance.md # Lightweight trigger entry point -├── scroll.md # Lightweight trigger entry point -├── ongoing.md # Lightweight trigger entry point -├── mouse.md # Lightweight trigger entry point -└── background-scroll.md # Lightweight trigger entry point +├── entrance.md # Entrance preset category guide +├── scroll.md # Scroll preset category guide +├── ongoing.md # Ongoing preset category guide +└── mouse.md # Mouse preset category guide ``` --- @@ -28,174 +27,146 @@ rules/presets/ ### Entrance Presets -| Preset | Status | Notes | -| ---------- | ----------- | -------------------------------------------------------- | -| FadeIn | Active | Simple opacity transition | -| ArcIn | Active | 3D arc rotation entry | -| BlurIn | Active | Blur-to-clear transition | -| BounceIn | Active | Bouncy entrance with overshoot | -| CurveIn | Active | Curved path entry | -| DropIn | Active | Drop from above with scale | -| FlipIn | Active | 3D flip rotation | -| FloatIn | Active | Gentle floating entry | -| FoldIn | Active | 3D fold unfold | -| GlideIn | Active | Smooth directional slide (default: from left, angle 270) | -| GrowIn | Active | Scale + translate entry | -| RevealIn | Active | Directional clip-path reveal | -| ShapeIn | Active | Geometric shape clip-path reveal | -| ShuttersIn | Active | Multi-segment reveal | -| SlideIn | Active | Directional slide with clip | -| SpinIn | Active | Rotation entry | -| TiltIn | Active | 3D tilt entry | -| TurnIn | Active | Corner-pivot rotation | -| WinkIn | Active | Axis-based scale reveal | -| CircleIn | **REMOVED** | Legacy preset | -| ExpandIn | **REMOVED** | Consolidated into GrowIn | -| GlitchIn | **REMOVED** | Was wrapper for GlideIn | -| PunchIn | **REMOVED** | Legacy preset | +| Preset | Notes | +| ---------- | -------------------------------------------------------- | +| FadeIn | Simple opacity transition | +| ArcIn | 3D arc rotation entry | +| BlurIn | Blur-to-clear transition | +| BounceIn | Bouncy entrance with overshoot | +| CurveIn | Curved path entry | +| DropIn | Drop from above with scale | +| FlipIn | 3D flip rotation | +| FloatIn | Gentle floating entry | +| FoldIn | 3D fold unfold | +| GlideIn | Smooth directional slide (default: from left, angle 270) | +| GrowIn | Scale + translate entry | +| RevealIn | Directional clip-path reveal | +| ShapeIn | Geometric shape clip-path reveal | +| ShuttersIn | Multi-segment reveal | +| SlideIn | Directional slide with clip | +| SpinIn | Rotation entry | +| TiltIn | 3D tilt entry | +| TurnIn | Corner-pivot rotation | +| WinkIn | Axis-based scale reveal | ### Scroll Presets -| Preset | Status | Notes | -| -------------- | ------ | ----------------------------- | -| ArcScroll | Active | 3D arc on scroll | -| BlurScroll | Active | Blur based on scroll | -| FadeScroll | Active | Opacity on scroll | -| FlipScroll | Active | 3D flip on scroll | -| GrowScroll | Active | Scale up on scroll | -| MoveScroll | Active | Translate on scroll | -| PanScroll | Active | Horizontal pan on scroll | -| ParallaxScroll | Active | Depth-based parallax | -| RevealScroll | Active | Clip-path reveal on scroll | -| ShapeScroll | Active | Shape clip-path on scroll | -| ShrinkScroll | Active | Scale down on scroll | -| ShuttersScroll | Active | Multi-segment on scroll | -| SkewPanScroll | Active | Skew + pan on scroll | -| SlideScroll | Active | Slide on scroll | -| Spin3dScroll | Active | 3D spin on scroll | -| SpinScroll | Active | 2D spin on scroll | -| StretchScroll | Active | Stretch deformation on scroll | -| TiltScroll | Active | 3D tilt on scroll | -| TurnScroll | Active | Turn rotation on scroll | +| Preset | Notes | +| -------------- | ----------------------------- | +| ArcScroll | 3D arc on scroll | +| BlurScroll | Blur based on scroll | +| FadeScroll | Opacity on scroll | +| FlipScroll | 3D flip on scroll | +| GrowScroll | Scale up on scroll | +| MoveScroll | Translate on scroll | +| PanScroll | Horizontal pan on scroll | +| ParallaxScroll | Depth-based parallax | +| RevealScroll | Clip-path reveal on scroll | +| ShapeScroll | Shape clip-path on scroll | +| ShrinkScroll | Scale down on scroll | +| ShuttersScroll | Multi-segment on scroll | +| SkewPanScroll | Skew + pan on scroll | +| SlideScroll | Slide on scroll | +| Spin3dScroll | 3D spin on scroll | +| SpinScroll | 2D spin on scroll | +| StretchScroll | Stretch deformation on scroll | +| TiltScroll | 3D tilt on scroll | +| TurnScroll | Turn rotation on scroll | ### Ongoing Presets -| Preset | Status | Notes | -| ------- | ------ | ---------------------- | -| Bounce | Active | Continuous bounce | -| Breathe | Active | Gentle scale pulse | -| Cross | Active | Cross-pattern movement | -| DVD | Active | DVD screensaver bounce | -| Flash | Active | Opacity flash | -| Flip | Active | Continuous flip | -| Fold | Active | Continuous fold | -| Jello | Active | Jello wobble | -| Poke | Active | Directional poke | -| Pulse | Active | Scale pulse | -| Rubber | Active | Rubber stretch | -| Spin | Active | Continuous rotation | -| Swing | Active | Pendulum swing | -| Wiggle | Active | Shake wiggle | +| Preset | Notes | +| ------- | ---------------------- | +| Bounce | Continuous bounce | +| Breathe | Gentle scale pulse | +| Cross | Cross-pattern movement | +| DVD | DVD screensaver bounce | +| Flash | Opacity flash | +| Flip | Continuous flip | +| Fold | Continuous fold | +| Jello | Jello wobble | +| Poke | Directional poke | +| Pulse | Scale pulse | +| Rubber | Rubber stretch | +| Spin | Continuous rotation | +| Swing | Pendulum swing | +| Wiggle | Shake wiggle | ### Mouse Presets -| Preset | Status | Notes | -| ------------ | ------ | ------------------------ | -| AiryMouse | Active | Light floating follow | -| BlobMouse | Active | Blob-like scale response | -| BlurMouse | Active | Blur on distance | -| BounceMouse | Active | Bouncy follow | -| CustomMouse | Active | Custom mouse effect | -| ScaleMouse | Active | Scale on mouse | -| SkewMouse | Active | Skew on mouse | -| SpinMouse | Active | Spin on mouse | -| SwivelMouse | Active | 3D swivel on mouse | -| Tilt3DMouse | Active | 3D tilt on mouse | -| Track3DMouse | Active | 3D tracking on mouse | -| TrackMouse | Active | Direct mouse tracking | - -### Background Scroll Presets - -| Preset | Status | Notes | -| ------------- | ------ | ------------------------------------------- | -| BgCloseUp | Active | Zoom close-up effect | -| BgFade | Active | Background fade | -| BgFadeBack | Active | Fade with pullback | -| BgFake3D | Active | Fake 3D depth | -| BgPan | Active | Horizontal pan | -| BgParallax | Active | Parallax depth | -| BgPullBack | Active | Pull back zoom | -| BgReveal | Active | Background reveal | -| BgRotate | Active | Background rotation | -| BgSkew | Active | Background skew | -| BgZoom | Active | Background zoom | -| ImageParallax | Active | Image parallax (no data-motion-part needed) | +| Preset | Notes | +| ------------ | ------------------------ | +| AiryMouse | Light floating follow | +| BlobMouse | Blob-like scale response | +| BlurMouse | Blur on distance | +| BounceMouse | Bouncy follow | +| CustomMouse | Custom mouse effect | +| ScaleMouse | Scale on mouse | +| SkewMouse | Skew on mouse | +| SpinMouse | Spin on mouse | +| SwivelMouse | 3D swivel on mouse | +| Tilt3DMouse | 3D tilt on mouse | +| Track3DMouse | 3D tracking on mouse | +| TrackMouse | Direct mouse tracking | --- ## Key Constraints -### Trigger Mechanisms +### Preset Categories -| Trigger | Mechanism | Notes | -| ----------------- | ------------------------------------- | --------------------------------------- | -| entrance | `viewEnter` (intersection observer) | Plays once when element enters viewport | -| scroll | Scroll position binding | Tied to scroll progress (0-100%) | -| ongoing | Continuous loop | Runs indefinitely until stopped | -| mouse | Pointer position binding | Desktop only, real-time response | -| background-scroll | Scroll + `data-motion-part` targeting | Requires structured DOM (see below) | +These are categories of presets, each optimized for certain use cases but not limited to a single trigger mechanism. -**Important:** Entrance animations only support the `viewEnter` trigger natively. For click, toggle, or other event-based triggers, implement triggering logic separately. +| Category | Optimized For | Notes | +| -------- | ----------------------------------- | ------------------------------------------------------------------------ | +| entrance | `viewEnter` (intersection observer) | Can also be triggered by hover, click, animationend, and other triggers | +| scroll | ViewTimeline (scroll progress) | Animation progress tied to element's position in the viewport | +| ongoing | Continuous loop | Runs indefinitely until stopped | +| mouse | Pointer position binding | Real-time response to cursor position; may behave differently on mobile | ### Combining Animations -| Combination | Support | -| --------------------- | ------------------------------- | -| Entrance + Ongoing | Single element (native support) | -| Entrance + Mouse | Requires nested containers | -| Entrance + Scroll | Requires nested containers | -| Scroll + Mouse | Requires nested containers | -| Any other combination | Requires multiple containers | +1. Avoid mixing multiple animations on the same element when possible +2. Never combine animations that affect the same CSS properties (e.g., two animations both using `transform`) +3. When combining is necessary, animation order matters - later animations may override earlier ones +4. If possible, use nested containers to separate animations that would conflict - place each animation on a separate wrapper element -### Background Scroll Requirements +--- -Requires `data-motion-part` attributes: `BG_LAYER`, `BG_MEDIA`, `BG_IMG` +## Parameter Standards -Animates DOM elements via CSS transforms (not `background-position`). +### Animation Options (Not Preset Parameters) -**Exception:** `ImageParallax` works on regular `` elements without `data-motion-part`. +These are set on the animation/effect configuration level, not on the preset itself: ---- - -## Parameter Standards +- `duration`: Animation duration in ms (entrance, ongoing) +- `delay`: Animation delay in ms (entrance, ongoing) +- `easing`: Easing function +- `iterations`: Number of iterations +- `alternate`: Alternate direction on each iteration +- `fill`: Animation fill mode +- `reversed`: Reverse the animation -### Common Parameters +**Scroll-specific animation options:** -**All Entrance presets:** +- `rangeStart` / `rangeEnd`: `RangeOffset` controlling when the scroll animation starts/ends +- `transitionDuration` / `transitionDelay` / `transitionEasing`: Transition smoothing -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +### Preset-Specific Parameters **Most Scroll presets:** -- `range`: 'in' | 'out' | 'continuous' -- `start`: 0-100% -- `end`: 0-100% +- `range`: 'in' | 'out' | 'continuous' (controls animation direction relative to scroll) -**Most Ongoing presets:** +### Overloaded Parameter Names -- `duration`: 100-4000ms -- `delay`: 0-8000ms +The `direction` parameter accepts different values depending on the preset: -### Parameter Naming Conventions - -| Meaning | Parameter Name | Values | Example Presets | -| ----------------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------- | -| Numeric angle (degrees) | `angle` | 0-360 | GrowIn, GlideIn, MoveScroll | -| Cardinal direction | `direction` | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | -| Extended cardinal | `direction` | + 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center' | BounceIn, ShapeIn | -| Rotation direction | `direction` | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | -| Axis | `axis` | 'horizontal', 'vertical' | WinkIn, FlipScroll, ArcScroll, Flip, Breathe | +| Meaning | Accepted Values | Presets | +| ------------------ | ------------------------------------------------------------------ | ------------------------------------ | +| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | +| Extended cardinal | + 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center' | BounceIn, ShapeIn | +| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | ### Coordinate System @@ -208,20 +179,21 @@ Animates DOM elements via CSS transforms (not `background-position`). ### Distance Units -All distance parameters accept any CSS unit with a default: +Distance parameters use the `UnitLengthPercentage` type: ```typescript -distance: { value: 120, type: 'px' } // pixels +distance: { value: 120, type: 'px' } // pixels distance: { value: 50, type: 'percentage' } // percentage -distance: { value: 10, type: 'vh' } // viewport height +distance: { value: 10, type: 'vh' } // viewport height ``` +Supported unit types: `px`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax`, `percentage` + ### CSS Custom Properties The library uses these CSS custom properties for runtime control: -- `--motion-opacity`: Target opacity (default: 1) -- `--motion-rotate`: Element rotation for scroll effects +- `--motion-rotate`: Element rotation (used by SpinIn and other rotation presets) --- @@ -270,7 +242,11 @@ This section documents preset selection guidance for accessibility. It is not ab ### Host vs Preset Responsibility -The presets provide animations; the host platform decides when/whether to apply them. When the host handles accessibility globally (e.g., disabling all animations under `prefers-reduced-motion`), presets don't need to address it separately. +The presets provide animations; the host platform decides when/whether to apply them. + +Interact supports `conditions` in the config for handling reduced motion. Define a media condition for `(prefers-reduced-motion: reduce)` and use it to swap high-risk presets for safer alternatives (e.g., SpinIn → FadeIn, BounceIn → FadeIn). Conditions can be applied per-interaction or per-effect, and automatically re-evaluate when the user's preference changes. + +When the host handles accessibility globally (e.g., disabling all animations), presets don't need to address it separately. ### Preset Risk Levels @@ -284,7 +260,7 @@ The presets provide animations; the host platform decides when/whether to apply **Medium risk** (strong motion, may affect some users): - TurnIn -- ParallaxScroll, BgParallax at high speed values +- ParallaxScroll at high speed values **Low risk / safe** (opacity/blur changes, minimal spatial movement): @@ -302,7 +278,6 @@ The presets provide animations; the host platform decides when/whether to apply | Flash | Reduce frequency (<3/sec) | | ParallaxScroll | Static position | | ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | -| BgParallax, BgZoom | Static background | | All mouse animations | Static state | ### LLM Guidance Principles @@ -310,7 +285,7 @@ The presets provide animations; the host platform decides when/whether to apply 1. **Do not limit creativity by default** - generate what the user asks for 2. **Apply constraints only when explicitly requested** - keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" 3. **High-risk presets are informational, not blockers** - optionally note vestibular concerns in response -4. **Mouse presets are desktop-only** - note this as context, not a restriction +4. **Mouse presets may behave differently on mobile** - note this as context, not a restriction 5. **Duration guidelines are suggestions** - functional UI <500ms, decorative up to 1200ms, hero up to 2000ms --- @@ -358,7 +333,7 @@ Parameters: | Use Case | Recommended Presets | | ---------------------- | ------------------------------------------------ | -| Hero sections | ArcIn, FloatIn, RevealIn + BgParallax, BgZoom | +| Hero sections | ArcIn, FloatIn, RevealIn | | Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | | List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | | Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | @@ -366,53 +341,43 @@ Parameters: | CTAs/Buttons | BounceIn, GrowIn + Pulse | | Loading indicators | Spin, Pulse | | Product images | Tilt3DMouse, ScaleMouse | -| Background depth | BgParallax, ParallaxScroll, TrackMouse (layered) | +| Background depth | ParallaxScroll, TrackMouse (layered) | --- -## Data Sources - -To regenerate presets-reference.md: - -1. **Preset registry**: This file (PLAN.md) - see Preset Registry section for active/removed status -2. **Preset list**: `motion-presets/src/types.ts` - EntranceAnimation, ScrollAnimation, OngoingAnimation, MouseAnimation, BackgroundScrollAnimation unions -3. **Parameter constraints**: `motion-presets/src/library/{category}/{Preset}.ts` - parameter types and defaults -4. **Parameter standards**: This file (PLAN.md) - see Parameter Standards section -5. **Optional parameters**: This file (PLAN.md) - see Optional Parameters section -6. **Accessibility**: This file (PLAN.md) - see Accessibility section -7. **Selection tables**: This file (PLAN.md) - see Selection Tables section - ## Regeneration Steps -1. Check Preset Registry in this file for active presets (skip REMOVED presets) -2. Read preset type definitions from types.ts -3. For each active preset, get params from library implementation +To regenerate `presets-reference.md`: + +1. Check Preset Registry in this file for active presets +2. Read preset type definitions from `motion-presets/src/types.ts` +3. For each active preset, get params from `motion-presets/src/library/{category}/{Preset}.ts` 4. Apply parameter naming conventions from this file 5. Generate using preset entry format above -6. Organize by trigger category +6. Organize by preset category 7. Include selection tables from this file 8. Include accessibility section from this file 9. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks --- -## Intensity Value Guide (Legacy Power Reference) +## Intensity Value Guide -The `power` parameter was removed from presets. When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use these value mappings as guidance for suggesting appropriate parameter values. +When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use these value mappings as guidance for suggesting appropriate parameter values. ### Entrance Presets Intensity Values -| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | -| -------- | ---------------- | ----------- | ------- | ------------- | -| ArcIn | easing | quintInOut | backOut | backInOut | -| BlurIn | blur | 6px | 25px | 50px | -| BounceIn | distanceFactor | 1 | 2 | 3 | -| DropIn | initialScale | 1.2 | 1.6 | 2 | -| FlipIn | initialRotate | 45° | 90° | 270° | -| FoldIn | initialRotate | 35° | 60° | 90° | -| GrowIn | initialScale | 0.8 | 0.6 | 0 | -| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | -| SpinIn | initialScale | 0.8 | 0.5 | 0 | +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| -------- | ---------------- | ----------- | ---------- | ------------- | +| ArcIn | easing | cubicInOut | quintInOut | backOut | +| BlurIn | blur | 6px | 25px | 50px | +| BounceIn | distanceFactor | 1 | 2 | 3 | +| DropIn | initialScale | 1.2 | 1.6 | 2 | +| FlipIn | initialRotate | 45° | 90° | 270° | +| FoldIn | initialRotate | 35° | 60° | 90° | +| GrowIn | initialScale | 0.8 | 0.6 | 0 | +| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | +| SpinIn | initialScale | 1 | 0.6 | 0 | ### Scroll Presets Intensity Values @@ -427,21 +392,21 @@ The `power` parameter was removed from presets. When users ask for "soft", "subt | Spin3dScroll | rotate | 45° | 100° | 200° | | SpinScroll | scale | 1 | 0.7 | 0.4 | | StretchScroll | stretch | 1.2 | 1.5 | 2 | -| TiltScroll | distance | 0.25 | 0.5 | 1 | +| TiltScroll | distance | 0 | 0.5 | 1 | | TurnScroll | scale | 1 | 1.3 | 1.6 | ### Ongoing Presets Intensity Values | Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | | ------ | --------- | ----------- | ------ | ------------- | -| Bounce | intensity | 0.3 | 0.5 | 1 | +| Bounce | intensity | 0 | 0.5 | 1 | | Fold | angle | 15° | 30° | 45° | -| Jello | intensity | 0.25 | 0.5 | 1 | -| Poke | intensity | 0.25 | 0.5 | 1 | -| Pulse | intensity | 0 | 0.06 | 0.12 | -| Rubber | intensity | 0 | 0.05 | 0.1 | +| Jello | intensity | 0 | 0.33 | 1 | +| Poke | intensity | 0 | 0.33 | 1 | +| Pulse | intensity | 0 | 0.5 | 1 | +| Rubber | intensity | 0 | 0.5 | 1 | | Swing | swing | 20° | 40° | 60° | -| Wiggle | intensity | 0.25 | 0.5 | 1 | +| Wiggle | intensity | 0 | 0.33 | 1 | ### Mouse Presets Intensity Values @@ -461,23 +426,5 @@ The `power` parameter was removed from presets. When users ask for "soft", "subt When a user asks: "I want a subtle flip entrance" -Instead of: `{ type: 'FlipIn', power: 'soft' }` - Suggest: `{ type: 'FlipIn', initialRotate: 45 }` ---- - -## Migration Reference - -For users migrating from removed presets: - -| Removed Preset | Migration | -| -------------- | --------------------------------------------------------------------------- | -| GlitchIn | Use `GlideIn` with desired `angle` (default 270 = from left) | -| ExpandIn | Use `GrowIn` with `angle` and `distance` to achieve expand-from-edge effect | -| CircleIn | No direct replacement (legacy preset) | -| PunchIn | No direct replacement (legacy preset) | - -### GlideIn Default Change - -GlideIn default `angle` changed from `0` (from top) to `270` (from left) to match the more common slide-in-from-left behavior. From bee343a71de4df82babafe8c7af4d7ecf4d02f08 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Thu, 12 Feb 2026 14:30:13 +0200 Subject: [PATCH 15/20] =?UTF-8?q?Regenerate=20preset=20docs:=20GrowIn?= =?UTF-8?q?=E2=86=92ExpandIn,=20add=20registry=20alignment=20step?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename GrowIn to ExpandIn across all preset docs (aligned with src/library) - Remove duplicate ExpandIn section in presets-reference.md - Remove deleted background-scroll.md - Add registry verification as first regeneration step in PLAN.md - Regenerate all category docs from updated PLAN.md Co-authored-by: Cursor --- packages/motion-presets/rules/presets/PLAN.md | 51 +- .../rules/presets/background-scroll.md | 42 - .../motion-presets/rules/presets/entrance.md | 35 +- .../motion-presets/rules/presets/mouse.md | 15 +- .../motion-presets/rules/presets/ongoing.md | 21 +- .../rules/presets/presets-reference.md | 1084 ++++++----------- .../motion-presets/rules/presets/scroll.md | 15 +- 7 files changed, 458 insertions(+), 805 deletions(-) delete mode 100644 packages/motion-presets/rules/presets/background-scroll.md diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index 25332ca5..b4d6e245 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -35,11 +35,11 @@ rules/presets/ | BounceIn | Bouncy entrance with overshoot | | CurveIn | Curved path entry | | DropIn | Drop from above with scale | +| ExpandIn | Scale + translate entry from edge | | FlipIn | 3D flip rotation | | FloatIn | Gentle floating entry | | FoldIn | 3D fold unfold | | GlideIn | Smooth directional slide (default: from left, angle 270) | -| GrowIn | Scale + translate entry | | RevealIn | Directional clip-path reveal | | ShapeIn | Geometric shape clip-path reveal | | ShuttersIn | Multi-segment reveal | @@ -117,12 +117,12 @@ rules/presets/ These are categories of presets, each optimized for certain use cases but not limited to a single trigger mechanism. -| Category | Optimized For | Notes | -| -------- | ----------------------------------- | ------------------------------------------------------------------------ | -| entrance | `viewEnter` (intersection observer) | Can also be triggered by hover, click, animationend, and other triggers | -| scroll | ViewTimeline (scroll progress) | Animation progress tied to element's position in the viewport | -| ongoing | Continuous loop | Runs indefinitely until stopped | -| mouse | Pointer position binding | Real-time response to cursor position; may behave differently on mobile | +| Category | Optimized For | Notes | +| -------- | ----------------------------------- | ----------------------------------------------------------------------- | +| entrance | `viewEnter` (intersection observer) | Can also be triggered by hover, click, animationend, and other triggers | +| scroll | ViewTimeline (scroll progress) | Animation progress tied to element's position in the viewport | +| ongoing | Continuous loop | Runs indefinitely until stopped | +| mouse | Pointer position binding | Real-time response to cursor position; may behave differently on mobile | ### Combining Animations @@ -162,11 +162,11 @@ These are set on the animation/effect configuration level, not on the preset its The `direction` parameter accepts different values depending on the preset: -| Meaning | Accepted Values | Presets | -| ------------------ | ------------------------------------------------------------------ | ------------------------------------ | -| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | -| Extended cardinal | + 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center' | BounceIn, ShapeIn | -| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | +| Meaning | Accepted Values | Presets | +| ------------------ | ------------------------------------------------------------------ | -------------------------------- | +| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | +| Extended cardinal | + 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center' | BounceIn, ShapeIn | +| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | ### Coordinate System @@ -331,17 +331,17 @@ Parameters: ### Preset Selection By Use Case -| Use Case | Recommended Presets | -| ---------------------- | ------------------------------------------------ | -| Hero sections | ArcIn, FloatIn, RevealIn | -| Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | -| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | -| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | -| Notifications/Badges | BounceIn, DropIn + Pulse | -| CTAs/Buttons | BounceIn, GrowIn + Pulse | -| Loading indicators | Spin, Pulse | -| Product images | Tilt3DMouse, ScaleMouse | -| Background depth | ParallaxScroll, TrackMouse (layered) | +| Use Case | Recommended Presets | +| ---------------------- | ---------------------------------------------- | +| Hero sections | ArcIn, FloatIn, RevealIn | +| Modals/Popups | FadeIn, DropIn, ExpandIn, SlideIn | +| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | +| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | +| Notifications/Badges | BounceIn, DropIn + Pulse | +| CTAs/Buttons | BounceIn, ExpandIn + Pulse | +| Loading indicators | Spin, Pulse | +| Product images | Tilt3DMouse, ScaleMouse | +| Background depth | ParallaxScroll, TrackMouse (layered) | --- @@ -349,7 +349,7 @@ Parameters: To regenerate `presets-reference.md`: -1. Check Preset Registry in this file for active presets +1. Verify Preset Registry in this file is aligned with actual preset files in `motion-presets/src/library/{category}/` (exclude index.ts and test files) 2. Read preset type definitions from `motion-presets/src/types.ts` 3. For each active preset, get params from `motion-presets/src/library/{category}/{Preset}.ts` 4. Apply parameter naming conventions from this file @@ -375,7 +375,7 @@ When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use | DropIn | initialScale | 1.2 | 1.6 | 2 | | FlipIn | initialRotate | 45° | 90° | 270° | | FoldIn | initialRotate | 35° | 60° | 90° | -| GrowIn | initialScale | 0.8 | 0.6 | 0 | +| ExpandIn | initialScale | 0.8 | 0.6 | 0 | | SlideIn | initialTranslate | 0.2 | 0.8 | 1 | | SpinIn | initialScale | 1 | 0.6 | 0 | @@ -427,4 +427,3 @@ When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use When a user asks: "I want a subtle flip entrance" Suggest: `{ type: 'FlipIn', initialRotate: 45 }` - diff --git a/packages/motion-presets/rules/presets/background-scroll.md b/packages/motion-presets/rules/presets/background-scroll.md deleted file mode 100644 index cf45f198..00000000 --- a/packages/motion-presets/rules/presets/background-scroll.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: Background Scroll Animations -trigger: backgroundScroll ---- - -# Background Scroll Animations - -Scroll animations for structured background media components. Animates DOM elements via CSS transforms (not `background-position`). - -## DOM Structure Required - -Requires `data-motion-part` attributes: `BG_LAYER`, `BG_MEDIA`, `BG_IMG` - -## When to Use Background Scroll Animations - -- Hero sections with background depth -- Full-width section backgrounds with `data-motion-part` structure -- Cinematic storytelling -- Section transitions - -## When NOT to Use Background Scroll Animations - -- Regular content elements → use [Scroll](presets-reference.md#scroll-presets) -- Elements without `data-motion-part` structure -- Simple CSS `background-image` (no DOM structure to animate) -- Mobile with performance concerns - -## Available Background Scroll Presets - -See [Background Scroll Presets](presets-reference.md#background-scroll-presets) for details. - -| Effect Type | Presets | -| -------------- | ----------------------------- | -| Depth/Movement | BgParallax, BgPan, BgFake3D | -| Scale/Zoom | BgZoom, BgCloseUp, BgPullBack | -| Opacity | BgFade, BgFadeBack | -| Rotation | BgRotate | -| Reveal | BgReveal | - -## Note - -`ImageParallax` works on regular `` elements without `data-motion-part` structure. diff --git a/packages/motion-presets/rules/presets/entrance.md b/packages/motion-presets/rules/presets/entrance.md index d5cabf80..2c36f87b 100644 --- a/packages/motion-presets/rules/presets/entrance.md +++ b/packages/motion-presets/rules/presets/entrance.md @@ -1,42 +1,30 @@ --- name: Entrance Animations -trigger: entrance +category: entrance --- # Entrance Animations -One-shot animations that play once when an element first enters the viewport. - -## Trigger Mechanism - -Uses the `viewEnter` trigger (intersection observer). Plays automatically when element scrolls into view for the first time. - -**Note:** For click, toggle, or other event-based triggers, implement the triggering logic separately and call the animation programmatically. +One-shot animations optimized for viewport entry, but can also be triggered by hover, click, animationEnd, and other triggers. ## When to Use Entrance Animations - Element reveals on viewport entry - First-time visibility animations +- Click/hover-triggered transitions - Content appearing as user scrolls down ## When NOT to Use Entrance Animations -- Scroll-driven reveals → see [Scroll](presets-reference.md#scroll) -- Continuous/looping → see [Ongoing](presets-reference.md#ongoing) -- Mouse-reactive → see [Mouse](presets-reference.md#mouse) +- Scroll-driven reveals → see [Scroll](presets-reference.md#scroll-presets) +- Continuous/looping → see [Ongoing](presets-reference.md#ongoing-presets) +- Mouse-reactive → see [Mouse](presets-reference.md#mouse-presets) ## Available Entrance Presets See [Entrance Presets](presets-reference.md#entrance-presets) for full details: -FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, FlipIn, FloatIn, FoldIn, GlideIn, GrowIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn - -## Entrance Common Parameters - -All entrance presets share: - -- `duration`: 0-4000 in ms (default: 1200) -- `delay`: 0-8000 in ms (default: 0) +FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn ## Entrance Quick Decision @@ -52,14 +40,7 @@ All entrance presets share: | Use Case | Recommended | | ---------------------- | -------------------------- | | Hero sections | ArcIn, FloatIn, RevealIn | -| Modals/Popups | FadeIn, DropIn, GrowIn | +| Modals/Popups | FadeIn, DropIn, ExpandIn | | List items (staggered) | FadeIn, SlideIn with delay | | Notifications | BounceIn, DropIn | | Cards | FlipIn, ArcIn, TiltIn | - -## Combining with Ongoing - -Entrance + Ongoing is the only combination supported on a single element. Example: - -- BounceIn plays on viewport entry -- Pulse continues indefinitely after diff --git a/packages/motion-presets/rules/presets/mouse.md b/packages/motion-presets/rules/presets/mouse.md index 726ddb75..febddf03 100644 --- a/packages/motion-presets/rules/presets/mouse.md +++ b/packages/motion-presets/rules/presets/mouse.md @@ -1,11 +1,11 @@ --- name: Mouse Animations -trigger: mouse +category: mouse --- # Mouse Animations -Animations that respond to cursor position. Desktop-only. +Animations that respond to cursor position. May behave differently on mobile. ## When to Use Mouse Animations @@ -16,16 +16,15 @@ Animations that respond to cursor position. Desktop-only. ## When NOT to Use Mouse Animations -- Mobile-first designs (won't work on touch) - Accessibility-critical interfaces -- Essential functionality -- Multiple simultaneous effects +- Essential functionality (never rely on mouse for core features) +- Multiple simultaneous effects on many elements ## Available Mouse Presets See [Mouse Presets](presets-reference.md#mouse-presets) for full details: -Tilt3DMouse, TrackMouse, BounceMouse, Track3DMouse, SpinMouse, ScaleMouse, SwivelMouse, SkewMouse, BlurMouse, AiryMouse, BlobMouse, CustomMouse +AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse ## Mouse Quick Decision @@ -44,9 +43,9 @@ Tilt3DMouse, TrackMouse, BounceMouse, Track3DMouse, SpinMouse, ScaleMouse, Swive | Interactive portfolios | Tilt3DMouse, Track3DMouse | | Playful interfaces | BounceMouse, BlobMouse | -## Mobile Fallback +## Mobile Considerations -Mouse animations don't work on touch devices. Options: +Mouse animations may behave differently on touch devices. Options: 1. Do nothing (static on mobile) 2. Use entrance animation instead diff --git a/packages/motion-presets/rules/presets/ongoing.md b/packages/motion-presets/rules/presets/ongoing.md index 706b3377..269fb863 100644 --- a/packages/motion-presets/rules/presets/ongoing.md +++ b/packages/motion-presets/rules/presets/ongoing.md @@ -1,6 +1,6 @@ --- name: Ongoing Animations -trigger: ongoing +category: ongoing --- # Ongoing Animations @@ -18,14 +18,13 @@ Continuous looping animations that run indefinitely. - Multiple simultaneous animations (visual chaos) - Content that needs to be read -- Professional/minimal interfaces -- One-time reveals → see [Entrance](presets-reference.md#entrance) +- One-time reveals → see [Entrance](presets-reference.md#entrance-presets) ## Available Ongoing Presets See [Ongoing Presets](presets-reference.md#ongoing-presets) for full details: -Pulse, Bounce, Spin, Breathe, Flash, Swing, Wiggle, Flip, Fold, Jello, Rubber, Poke, Cross, DVD +Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle ## Ongoing Quick Decision @@ -38,10 +37,10 @@ Pulse, Bounce, Spin, Breathe, Flash, Swing, Wiggle, Flip, Fold, Jello, Rubber, P ## Ongoing Common Use Cases -| Use Case | Recommended | -| ------------------ | ----------------------- | -| Loading spinner | Spin (duration: 1500ms) | -| Status indicator | Pulse, Breathe | -| Notification badge | Bounce, Pulse, Poke | -| CTA emphasis | Pulse, Bounce | -| Character/Mascot | Bounce, Wiggle, Jello | +| Use Case | Recommended | +| ------------------ | --------------------- | +| Loading spinner | Spin | +| Status indicator | Pulse, Breathe | +| Notification badge | Bounce, Pulse, Poke | +| CTA emphasis | Pulse, Bounce | +| Character/Mascot | Bounce, Wiggle, Jello | diff --git a/packages/motion-presets/rules/presets/presets-reference.md b/packages/motion-presets/rules/presets/presets-reference.md index 4be3cee1..c750c0d6 100644 --- a/packages/motion-presets/rules/presets/presets-reference.md +++ b/packages/motion-presets/rules/presets/presets-reference.md @@ -11,34 +11,32 @@ This document is a comprehensive reference for Interact motion presets. Use it t ### Decision Flow -1. **Select Trigger** - What causes the animation? (viewport entry, scroll position, mouse, continuous loop) +1. **Select Category** - What kind of animation? (entrance, scroll, ongoing, mouse) 2. **Select Preset** - Which visual effect matches the intent? -3. **Configure Parameters** - Customize direction, power, timing, etc. +3. **Configure Parameters** - Customize direction, intensity, timing, etc. -### Quick Trigger Lookup +### Quick Category Lookup -| User Intent | Trigger | Notes | -| -------------------------------------------------------------------- | ----------------- | ----------------------------------------- | -| "animate when element enters viewport", "reveal on scroll into view" | entrance | viewEnter trigger (intersection observer) | -| "animate based on scroll position", "parallax", "scroll-driven" | scroll | Tied to scroll progress | -| "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely | -| "react to mouse", "follow cursor", "tilt on hover" | mouse | Desktop only | -| "background image effect", "hero background", "parallax bg" | background-scroll | CSS backgrounds only | +| User Intent | Category | Notes | +| -------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- | +| "animate when element enters viewport", "reveal on scroll into view" | entrance | Optimized for `viewEnter`; also works with hover, click, animationEnd | +| "animate based on scroll position", "parallax", "scroll-driven" | scroll | Animation progress tied to element's position in the viewport | +| "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely until stopped | +| "react to mouse", "follow cursor", "tilt on hover" | mouse | Real-time response to cursor position; may behave differently on mobile | --- -## 2. Triggers +## 2. Preset Categories ### Entrance -One-shot animations that play once when an element first enters the viewport. - -**Trigger mechanism:** Uses the `viewEnter` trigger (intersection observer). Plays once when element first scrolls into view. +One-shot animations optimized for viewport entry, but can also be triggered by hover, click, animationEnd, and other triggers. **When to use:** - Element reveals on viewport entry - First-time visibility animations +- Click/hover-triggered transitions **When NOT to use:** @@ -46,13 +44,11 @@ One-shot animations that play once when an element first enters the viewport. - Continuous/looping → use ongoing - Mouse-reactive → use mouse -**Note:** For click, toggle, or other event-based triggers, implement the triggering logic separately and call the animation programmatically. The library only provides viewEnter as a built-in trigger for entrance animations. - -**Available presets:** FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, FlipIn, FloatIn, FoldIn, GlideIn, GrowIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn +**Available presets:** FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn ### Scroll -Animations tied to scroll position. Can animate in, out, or continuously throughout scroll range. +Animations whose progress is tied to a ViewTimeline - the element's position in the viewport. **When to use:** @@ -65,7 +61,6 @@ Animations tied to scroll position. Can animate in, out, or continuously through - One-time entrance → use entrance (more performant) - Continuous loops → use ongoing -- Background images → use background-scroll **Available presets:** ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll @@ -84,14 +79,13 @@ Continuous looping animations that run indefinitely. - Multiple simultaneous animations (visual chaos) - Content that needs to be read -- Professional/minimal interfaces - One-time reveals → use entrance -**Available presets:** Pulse, Bounce, Spin, Breathe, Flash, Swing, Wiggle, Flip, Fold, Jello, Rubber, Poke, Cross, DVD +**Available presets:** Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle ### Mouse -Animations that respond to cursor position. Desktop-only. +Animations that respond to cursor position. May behave differently on mobile. **When to use:** @@ -102,134 +96,62 @@ Animations that respond to cursor position. Desktop-only. **When NOT to use:** -- Mobile-first designs (won't work on touch) - Accessibility-critical interfaces - Essential functionality (never rely on mouse for core features) -**Available presets:** Tilt3DMouse, TrackMouse, BounceMouse, Track3DMouse, SpinMouse, ScaleMouse, SwivelMouse, SkewMouse, BlurMouse, AiryMouse, BlobMouse, CustomMouse - -### Background Scroll - -Scroll animations for structured background media components. Animates DOM elements via CSS transforms (not `background-position`). - -**Requires `data-motion-part` attributes:** `BG_LAYER`, `BG_MEDIA`, `BG_IMG` - -**When to use:** +**Available presets:** AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse -- Hero sections with background depth -- Full-width section backgrounds with `data-motion-part` structure - -**When NOT to use:** - -- Regular content elements → use scroll -- Elements without `data-motion-part` structure -- Simple CSS `background-image` (no DOM structure) - -**Available presets:** BgParallax, BgZoom, BgFade, BgFadeBack, BgPan, BgRotate, BgSkew, BgReveal, BgCloseUp, BgPullBack, BgFake3D, ImageParallax +--- -**Note:** `ImageParallax` works on regular `` elements without `data-motion-part` structure. +## 3. Parameter Standards ---- +### Animation Options (Not Preset Parameters) -## Common Parameters +These are set on the animation/effect configuration level, not on the preset itself: -### Shared by All Entrance Presets +- `duration`: Animation duration in ms (entrance, ongoing) +- `delay`: Animation delay in ms (entrance, ongoing) +- `easing`: Easing function +- `iterations`: Number of iterations +- `alternate`: Alternate direction on each iteration +- `fill`: Animation fill mode +- `reversed`: Reverse the animation -- `duration`: 0-4000ms (default: 1200) - animation length -- `delay`: 0-8000ms (default: 0) - wait before starting +**Scroll-specific animation options:** -### Shared by Most Scroll Presets +- `rangeStart` / `rangeEnd`: `RangeOffset` controlling when the scroll animation starts/ends +- `transitionDuration` / `transitionDelay` / `transitionEasing`: Transition smoothing -- `range`: 'in' | 'out' | 'continuous' - when animation occurs relative to viewport -- `start`: 0-100% - scroll position to start animation -- `end`: 0-100% - scroll position to end animation +### Overloaded Parameter Names -### Shared by Most Ongoing Presets +The `direction` parameter accepts different values depending on the preset: -- `duration`: 100-4000ms - single cycle length -- `delay`: 0-8000ms - initial wait before looping starts +| Meaning | Accepted Values | Presets | +| ------------------ | ------------------------------------------------------------------ | -------------------------------- | +| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | +| Extended cardinal | + 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center' | BounceIn, ShapeIn | +| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | ### Coordinate System -For angle-based parameters, the library uses standard mathematical coordinates: +For angle-based parameters: - **0°** = right (east) - **90°** = top (north) - **180°** = left (west) - **270°** = bottom (south) -### CSS Custom Properties - -The library exposes these CSS custom properties for runtime control: - -- `--motion-opacity`: Target opacity (default: 1) -- `--motion-rotate-z`: Element rotation for scroll effects - ---- - -## 3. Trigger-Preset Relations - -### By Tone - -| Tone | Entrance | Scroll | Ongoing | Mouse | -| ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | -| Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | -| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | - -### By Use Case - -| Use Case | Recommended Presets | -| ---------------------- | ------------------------------------------------ | -| Hero sections | ArcIn, FloatIn, RevealIn + BgParallax, BgZoom | -| Modals/Popups | FadeIn, DropIn, GrowIn, SlideIn | -| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | -| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | -| Notifications/Badges | BounceIn, DropIn + Pulse | -| CTAs/Buttons | BounceIn, GrowIn + Pulse | -| Loading indicators | Spin, Pulse | -| Product images | Tilt3DMouse, ScaleMouse | -| Background depth | BgParallax, ParallaxScroll, TrackMouse (layered) | - -### Cross-Category Parallels - -Effects with similar visual results across triggers: - -| Entrance | Scroll | Ongoing | Mouse | Background | -| -------- | -------------- | ------- | ----------- | ---------- | -| FadeIn | FadeScroll | Flash | - | BgFade | -| ArcIn | ArcScroll | - | - | - | -| SpinIn | SpinScroll | Spin | SpinMouse | BgRotate | -| BounceIn | - | Bounce | BounceMouse | - | -| TiltIn | TiltScroll | - | Tilt3DMouse | - | -| FlipIn | FlipScroll | Flip | - | - | -| GrowIn | GrowScroll | Pulse | ScaleMouse | BgZoom | -| SlideIn | SlideScroll | - | TrackMouse | BgPan | -| BlurIn | BlurScroll | - | BlurMouse | - | -| RevealIn | RevealScroll | - | - | BgReveal | -| - | ParallaxScroll | - | TrackMouse | BgParallax | - -### Combining Triggers - -**On a single element (natively supported):** - -- **Entrance + Ongoing only**: Element can have both entrance and ongoing animations - - Example: BounceIn on viewport entry, then Pulse continuously - -**Requires multiple containers (nested elements):** +### Distance Units -- Entrance + Mouse -- Entrance + Scroll -- Scroll + Mouse -- Any other combination +Distance parameters use the `UnitLengthPercentage` type: -These require nested elements with each animation on a separate container. Layout must ensure inner container can animate independently of outer. - -**Multi-element patterns:** +```typescript +distance: { value: 120, type: 'px' } // pixels +distance: { value: 50, type: 'percentage' } // percentage +distance: { value: 10, type: 'vh' } // viewport height +``` -- **Scroll + Background**: Content element uses FadeScroll, separate background element uses BgParallax -- **Layered parallax**: Multiple sibling elements with TrackMouse at different distances +Supported unit types: `px`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax`, `percentage` --- @@ -243,12 +165,12 @@ Visual: Element transitions from invisible to visible. Simple opacity change, no Parameters: -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +- No preset-specific parameters ```typescript -{ type: 'FadeIn' } -{ type: 'FadeIn', duration: 300 } // Quick functional fade +{ + type: 'FadeIn'; +} ``` #### ArcIn @@ -258,13 +180,12 @@ Visual: Element swings in along a curved 3D path, like a door opening. Dramatic, Parameters: - `direction`: top | right | bottom | left (default: left) -- `perspective`: 3D perspective depth (default: 800) -- `angle`: arc rotation angle (default: 80) -- `depth`: Z translation distance (default: 300) +- `depth`: UnitLengthPercentage (default: 300px) - Z translation distance +- `perspective`: number (default: 800) ```typescript { type: 'ArcIn', direction: 'bottom' } -{ type: 'ArcIn', direction: 'left', angle: 120 } // Dramatic hero entrance +{ type: 'ArcIn', direction: 'left', depth: { value: 500, type: 'px' } } ``` #### BlurIn @@ -273,12 +194,12 @@ Visual: Element transitions from blurry to sharp focus while fading in. Soft, dr Parameters: -- `blur`: blur amount in px (default: 25) +- `blur`: number in px (default: 25) ```typescript { type: 'BlurIn' } -{ type: 'BlurIn', blur: 6 } // Subtle blur -{ type: 'BlurIn', blur: 50 } // Dramatic blur +{ type: 'BlurIn', blur: 6 } // Subtle +{ type: 'BlurIn', blur: 50 } // Dramatic ``` #### BounceIn @@ -288,24 +209,23 @@ Visual: Element bounces into view with spring physics. Playful, attention-grabbi Parameters: - `direction`: top | right | bottom | left | center (default: top) -- `distanceFactor`: 1-4 (default: 1) -- `perspective`: 3D perspective for center direction (default: 800) +- `distanceFactor`: number (default: 1) +- `perspective`: number (default: 800) - only used with center direction ```typescript { type: 'BounceIn' } -{ type: 'BounceIn', direction: 'center', distanceFactor: 2 } // Reward popup -{ type: 'BounceIn', distanceFactor: 2.5 } // Custom distance +{ type: 'BounceIn', direction: 'center', distanceFactor: 2 } ``` #### CurveIn -Visual: Alternative curved 3D motion path. Similar to ArcIn with different trajectory. +Visual: Curved 3D motion path entry. Cinematic arc trajectory. Parameters: -- `direction`: left | right -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +- `direction`: 'left' | 'right' | 'pseudoLeft' | 'pseudoRight' +- `depth`: UnitLengthPercentage (default: 900px) +- `perspective`: number (default: 200) ```typescript { type: 'CurveIn', direction: 'left' } @@ -313,11 +233,11 @@ Parameters: #### DropIn -Visual: Falls from above with subtle scale/bounce on landing. Gravity-like, natural. +Visual: Falls from above with subtle scale on landing. Gravity-like, natural. Parameters: -- `initialScale`: starting scale (default: 1.6) +- `initialScale`: number (default: 1.6) ```typescript { type: 'DropIn' } @@ -331,8 +251,8 @@ Visual: 3D card flip rotation to reveal element. Dramatic, card-like metaphor. Parameters: - `direction`: top | right | bottom | left -- `initialRotate`: starting rotation degrees (default: 90) -- `perspective`: 3D perspective depth (default: 800) +- `initialRotate`: number in degrees (default: 90) +- `perspective`: number (default: 800) ```typescript { type: 'FlipIn', direction: 'left' } @@ -346,8 +266,6 @@ Visual: Gentle floating/drifting entrance. Ethereal, light, dreamy. Parameters: - `direction`: top | right | bottom | left -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) ```typescript { type: 'FloatIn', direction: 'bottom' } @@ -360,41 +278,41 @@ Visual: Paper-folding 3D effect. Origami-like, creative. Parameters: - `direction`: top | right | bottom | left -- `initialRotate`: starting rotation degrees (default: 60) -- `perspective`: 3D perspective depth (default: 800) +- `initialRotate`: number in degrees (default: 60) +- `perspective`: number (default: 800) ```typescript { type: 'FoldIn', direction: 'left' } -{ type: 'FoldIn', direction: 'top', initialRotate: 90 } // More dramatic fold +{ type: 'FoldIn', direction: 'top', initialRotate: 90 } ``` #### GlideIn -Visual: Smooth 2D glide from direction with angle control. Clean, directional. +Visual: Smooth 2D glide from any angle with distance control. Clean, directional. Parameters: -- `angle`: angle in degrees (default: 270, from left). 0° = right, 90° = top, 180° = left, 270° = bottom -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `direction`: number in degrees (default: 270, from left). 0° = right, 90° = top, 180° = left, 270° = bottom +- `distance`: UnitLengthPercentage | EffectFourDirections ```typescript -{ type: 'GlideIn', angle: 270, distance: { value: 100, type: 'px' } } // From left (default) -{ type: 'GlideIn', angle: 90, distance: { value: 50, type: 'percentage' } } // From top +{ type: 'GlideIn' } // From left (default angle 270) +{ type: 'GlideIn', direction: 90, distance: { value: 50, type: 'percentage' } } // From top ``` -#### GrowIn +#### ExpandIn -Visual: Scale from small to full size with optional directional movement. Expanding, emerging. +Visual: Scale from small to full size with directional expansion from edge. Emerging, growing outward. Parameters: -- `angle`: angle in degrees (default: 0). 0° = right, 90° = top, 180° = left, 270° = bottom -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: 120px) -- `initialScale`: starting scale 0-1 (default: 0.6) +- `direction`: number in degrees or keyword (top | right | bottom | left). Default: 90 (from top) +- `distance`: UnitLengthPercentage (default: { value: 120, unit: 'percentage' }) +- `initialScale`: number (default: 0) ```typescript -{ type: 'GrowIn', angle: 0, distance: { value: 0, type: 'px' } } // Pure scale, no movement -{ type: 'GrowIn', angle: 270, distance: { value: 100, type: 'px' }, initialScale: 0.3 } // From bottom with dramatic scale +{ type: 'ExpandIn' } +{ type: 'ExpandIn', direction: 'bottom', distance: { value: 100, type: 'px' }, initialScale: 0.3 } ``` #### RevealIn @@ -404,8 +322,6 @@ Visual: Directional clip/mask reveal like a curtain opening. Theatrical. Parameters: - `direction`: top | right | bottom | left -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) ```typescript { type: 'RevealIn', direction: 'left' } @@ -417,14 +333,11 @@ Visual: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise. Parameters: -- `shape`: circle | ellipse | rectangle | diamond | window -- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' ```typescript -{ type: 'ShapeIn', shape: 'circle', direction: 'center' } -{ type: 'ShapeIn', shape: 'diamond', direction: 'top' } +{ type: 'ShapeIn', shape: 'circle' } +{ type: 'ShapeIn', shape: 'diamond' } ``` #### ShuttersIn @@ -443,12 +356,12 @@ Parameters: #### SlideIn -Visual: Straight movement from direction. Clean, simple, versatile. +Visual: Straight movement from direction with clip. Clean, simple, versatile. Parameters: - `direction`: top | right | bottom | left -- `initialTranslate`: starting offset (0-1, default: 1) +- `initialTranslate`: number 0-1 (default: 1) - starting offset ratio ```typescript { type: 'SlideIn', direction: 'bottom' } @@ -461,9 +374,9 @@ Visual: Rotating entrance with spin. Dynamic, playful. Parameters: -- `direction`: clockwise | counter-clockwise +- `direction`: 'clockwise' | 'counter-clockwise' - `spins`: number of rotations -- `initialScale`: starting scale (default: 0) +- `initialScale`: number (default: 0) - starting scale ```typescript { type: 'SpinIn', direction: 'clockwise', spins: 1 } @@ -476,9 +389,9 @@ Visual: 3D tilt into view. Subtle depth, elegant perspective. Parameters: -- `direction`: left | right -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +- `direction`: 'left' | 'right' +- `depth`: UnitLengthPercentage (default: 200px) +- `perspective`: number (default: 800) ```typescript { type: 'TiltIn', direction: 'left' } @@ -490,12 +403,10 @@ Visual: Corner-pivot 3D rotation. Complex, dramatic, premium. Parameters: -- `direction`: top-left | top-right | bottom-left | bottom-right -- `angle`: rotation angle (default: 50) +- `direction`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' ```typescript { type: 'TurnIn', direction: 'bottom-left' } -{ type: 'TurnIn', direction: 'top-right', angle: 80 } // More dramatic ``` #### WinkIn @@ -504,9 +415,7 @@ Visual: Split-in-half reveal from center. Unique, eye-like opening. Parameters: -- `direction`: vertical | horizontal -- `duration`: 0-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +- `direction`: 'vertical' | 'horizontal' ```typescript { type: 'WinkIn', direction: 'vertical' } @@ -516,64 +425,49 @@ Parameters: ### Scroll Presets -#### ParallaxScroll - -Visual: Element moves slower/faster than scroll, creating depth illusion. - -Parameters: +All scroll presets accept a `range` parameter: `'in'` | `'out'` | `'continuous'` -- `speed`: -1 to 1 (default: 0.5) — positive = same direction, slower; negative = opposite direction -- `range`: continuous - -```typescript -{ type: 'ParallaxScroll' } -{ type: 'ParallaxScroll', speed: 0.3 } // Subtle depth -{ type: 'ParallaxScroll', speed: -0.2 } // Reverse parallax -``` +#### ArcScroll -#### FadeScroll - -Visual: Opacity transition tied to scroll. Fade in on enter, out on exit. +Visual: 3D arc rotation as user scrolls. Dramatic, cinematic. Parameters: -- `range`: in | out (required) -- `opacity`: 0-1 (the "other" opacity value) -- `start`: 0-100% scroll position -- `end`: 0-100% scroll position +- `direction`: 'vertical' | 'horizontal' +- `range`: in | out | continuous +- `perspective`: number ```typescript -{ type: 'FadeScroll', range: 'in' } -{ type: 'FadeScroll', range: 'out' } -{ type: 'FadeScroll', range: 'in', start: 0, end: 30 } // Quick fade +{ type: 'ArcScroll', direction: 'vertical' } +{ type: 'ArcScroll', direction: 'horizontal', range: 'in' } ``` -#### ArcScroll +#### BlurScroll -Visual: 3D tilt/rotation as user scrolls. Dramatic, cinematic. +Visual: Blur/unblur effect controlled by scroll. Focus transitions. Parameters: -- `direction`: vertical | horizontal - `range`: in | out | continuous +- `blur`: number in px (default: 25) ```typescript -{ type: 'ArcScroll', direction: 'vertical' } -{ type: 'ArcScroll', direction: 'horizontal', range: 'in' } +{ type: 'BlurScroll', range: 'in' } +{ type: 'BlurScroll', range: 'out', blur: 50 } ``` -#### BlurScroll +#### FadeScroll -Visual: Blur/unblur effect controlled by scroll. Focus transitions. +Visual: Opacity transition tied to scroll. Fade in on enter, out on exit. Parameters: -- `range`: in | out | continuous -- `blur`: blur amount in px (default: 25) +- `range`: in | out +- `opacity`: number 0-1 ```typescript -{ type: 'BlurScroll', range: 'in' } -{ type: 'BlurScroll', range: 'out', blur: 50 } // More dramatic +{ type: 'FadeScroll', range: 'in' } +{ type: 'FadeScroll', range: 'out' } ``` #### FlipScroll @@ -582,14 +476,14 @@ Visual: Full 3D card flip driven by scroll. Dramatic rotation. Parameters: -- `axis`: vertical | horizontal +- `direction`: 'vertical' | 'horizontal' - `range`: in | out | continuous -- `rotate`: rotation degrees (default: 120) -- `perspective`: 3D perspective depth (default: 800) +- `rotate`: number in degrees (default: 120) +- `perspective`: number (default: 800) ```typescript -{ type: 'FlipScroll', axis: 'horizontal' } -{ type: 'FlipScroll', axis: 'vertical', range: 'in', rotate: 420 } // Multiple rotations +{ type: 'FlipScroll', direction: 'horizontal' } +{ type: 'FlipScroll', direction: 'vertical', range: 'in', rotate: 420 } ``` #### GrowScroll @@ -600,58 +494,56 @@ Parameters: - `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center - `range`: in | out | continuous -- `scale`: target scale (default: 1.7) -- `speed`: animation speed +- `scale`: number (default: 1.7) +- `speed`: number ```typescript { type: 'GrowScroll', direction: 'center' } -{ type: 'GrowScroll', direction: 'center', range: 'in', scale: 4 } // Dramatic scale +{ type: 'GrowScroll', direction: 'center', range: 'in', scale: 4 } ``` -#### ShrinkScroll +#### MoveScroll -Visual: Scale down as element exits viewport. +Visual: Translation movement on scroll in any direction. Parameters: -- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center +- `angle`: 0-360 degrees (default varies). 0° = right, 90° = top, 180° = left, 270° = bottom - `range`: in | out | continuous -- `scale`: target scale (default: 0.3) -- `speed`: animation speed +- `distance`: UnitLengthPercentage (default: 400px) ```typescript -{ type: 'ShrinkScroll', direction: 'center', range: 'out' } -{ type: 'ShrinkScroll', direction: 'center', scale: 0 } // Shrink to nothing +{ type: 'MoveScroll', angle: 90, distance: { value: 100, type: 'px' } } +{ type: 'MoveScroll', angle: 0, distance: { value: 800, type: 'px' } } ``` -#### MoveScroll +#### PanScroll -Visual: Translation movement on scroll in any direction. +Visual: Horizontal panning tied to scroll. Parameters: -- `angle`: 0-360 degrees. 0° = right, 90° = top, 180° = left, 270° = bottom +- `direction`: 'left' | 'right' +- `distance`: UnitLengthPercentage +- `startFromOffScreen`: boolean - `range`: in | out | continuous -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: 400px) ```typescript -{ type: 'MoveScroll', angle: 90, distance: { value: 100, type: 'px' } } -{ type: 'MoveScroll', angle: 0, distance: { value: 800, type: 'px' } } // Long horizontal move +{ type: 'PanScroll', direction: 'left', distance: { value: 200, type: 'px' } } ``` -#### PanScroll +#### ParallaxScroll -Visual: Horizontal or vertical panning tied to scroll. +Visual: Element moves slower/faster than scroll, creating depth illusion. Parameters: -- `direction`: left | right -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `startFromOffScreen`: boolean +- `parallaxFactor`: number (default: 0.5) - movement speed relative to scroll - `range`: in | out | continuous ```typescript -{ type: 'PanScroll', direction: 'left', distance: { value: 200, type: 'px' }, startFromOffScreen: false } +{ type: 'ParallaxScroll' } +{ type: 'ParallaxScroll', parallaxFactor: 0.3 } ``` #### RevealScroll @@ -674,15 +566,31 @@ Visual: Shape mask reveal controlled by scroll. Parameters: -- `shape`: circle | ellipse | rectangle | diamond | window +- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' - `range`: in | out | continuous -- `intensity`: 0-1 (default: varies by shape) +- `intensity`: number 0-1 ```typescript { type: 'ShapeScroll', shape: 'circle' } { type: 'ShapeScroll', shape: 'diamond', intensity: 0.8 } ``` +#### ShrinkScroll + +Visual: Scale down as element exits viewport. + +Parameters: + +- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center +- `range`: in | out | continuous +- `scale`: number (default: 0.3) +- `speed`: number + +```typescript +{ type: 'ShrinkScroll', direction: 'center', range: 'out' } +{ type: 'ShrinkScroll', direction: 'center', scale: 0 } +``` + #### ShuttersScroll Visual: Venetian blind strips revealing on scroll. @@ -704,13 +612,13 @@ Visual: Panning with skew distortion effect. Parameters: -- `direction`: left | right +- `direction`: 'left' | 'right' - `range`: in | out | continuous -- `skew`: skew angle (default: 17) +- `skew`: number in degrees (default: 17) ```typescript { type: 'SkewPanScroll', direction: 'left' } -{ type: 'SkewPanScroll', direction: 'right', skew: 24 } // More dramatic +{ type: 'SkewPanScroll', direction: 'right', skew: 24 } ``` #### SlideScroll @@ -734,13 +642,13 @@ Visual: 3D rotation around axis on scroll. Parameters: - `range`: in | out | continuous -- `rotate`: rotation degrees (default: 100) -- `speed`: animation speed -- `perspective`: 3D perspective depth (default: 1000) +- `rotate`: number in degrees (default: 100) +- `speed`: number +- `perspective`: number (default: 1000) ```typescript { type: 'Spin3dScroll' } -{ type: 'Spin3dScroll', range: 'continuous', rotate: 200 } // More dramatic +{ type: 'Spin3dScroll', range: 'continuous', rotate: 200 } ``` #### SpinScroll @@ -749,10 +657,10 @@ Visual: 2D rotation driven by scroll. Parameters: -- `direction`: clockwise | counter-clockwise +- `direction`: 'clockwise' | 'counter-clockwise' - `spins`: number of rotations - `range`: in | out | continuous -- `scale`: scale factor (default: 0.7) +- `scale`: number (default: 0.7) ```typescript { type: 'SpinScroll', direction: 'clockwise', spins: 1 } @@ -766,11 +674,11 @@ Visual: Stretch/squeeze deformation on scroll. Parameters: - `range`: in | out | continuous -- `stretch`: stretch amount (default: 1.5) +- `stretch`: number (default: 1.5) ```typescript { type: 'StretchScroll' } -{ type: 'StretchScroll', stretch: 2 } // More dramatic +{ type: 'StretchScroll', stretch: 2 } ``` #### TiltScroll @@ -779,14 +687,14 @@ Visual: 3D tilt effect as user scrolls. Subtle perspective. Parameters: -- `direction`: left | right +- `direction`: 'left' | 'right' - `range`: in | out | continuous -- `distance`: tilt distance (default: 0.5) -- `perspective`: 3D perspective depth (default: 400) +- `parallaxFactor`: number (default: 0.5) - tilt distance factor +- `perspective`: number (default: 400) ```typescript { type: 'TiltScroll', direction: 'left' } -{ type: 'TiltScroll', direction: 'right', distance: 1 } // More dramatic +{ type: 'TiltScroll', direction: 'right', parallaxFactor: 1 } ``` #### TurnScroll @@ -795,10 +703,11 @@ Visual: Corner-pivot 3D rotation on scroll. Parameters: -- `direction`: left | right -- `spin`: clockwise | counter-clockwise +- `direction`: 'left' | 'right' +- `spin`: 'clockwise' | 'counter-clockwise' - `range`: in | out | continuous -- `scale`: scale factor (default: 1.3) +- `scale`: number (default: 1.3) +- `rotation`: number ```typescript { type: 'TurnScroll', direction: 'left', spin: 'clockwise' } @@ -809,43 +718,17 @@ Parameters: ### Ongoing Presets -#### Pulse - -Visual: Gentle scale oscillation, heartbeat-like rhythm. Subtle, universal. - -Parameters: - -- `intensity`: 0-1 (default: 0.06) - -```typescript -{ type: 'Pulse' } -{ type: 'Pulse', intensity: 0.12 } // More dramatic -``` - #### Bounce -Visual: Vertical bouncing motion like a ball on trampoline. Playful, energetic. +Visual: Vertical bouncing motion. Playful, energetic. Parameters: -- `intensity`: 0-1 (default: 0.3) +- `intensity`: number 0-1 (default: 0) ```typescript { type: 'Bounce' } -{ type: 'Bounce', intensity: 0.6 } // More energetic -``` - -#### Spin - -Visual: Continuous rotation around center. Mechanical, precise. - -Parameters: - -- `direction`: clockwise | counter-clockwise (default: clockwise) - -```typescript -{ type: 'Spin', direction: 'clockwise' } -{ type: 'Spin', direction: 'clockwise', duration: 1500 } // Loading spinner +{ type: 'Bounce', intensity: 0.5 } ``` #### Breathe @@ -854,53 +737,53 @@ Visual: Slow scale in/out like breathing. Calm, organic, meditative. Parameters: -- `direction`: vertical | horizontal | center -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } +- `direction`: 'vertical' | 'horizontal' | 'center' +- `distance`: UnitLengthPercentage +- `perspective`: number ```typescript +{ type: 'Breathe', direction: 'center' } { type: 'Breathe', direction: 'center', distance: { value: 10, type: 'percentage' } } ``` -#### Flash +#### Cross -Visual: Opacity pulsing/blinking. Attention, warning indicator. +Visual: X-pattern diagonal movement. Unique geometric motion. Parameters: -- `duration`: 100-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) +- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right ```typescript -{ - type: 'Flash'; -} +{ type: 'Cross', direction: 'top-left' } ``` -#### Swing +#### DVD -Visual: Rotation oscillation like a pendulum. Back and forth rhythmic. +Visual: Corner-to-corner bounce (DVD screensaver). Nostalgic, retro. Parameters: -- `swing`: swing angle (default: 40) -- `direction`: top | right | bottom | left +- No preset-specific parameters ```typescript -{ type: 'Swing' } -{ type: 'Swing', swing: 60 } // More dramatic +{ + type: 'DVD'; +} ``` -#### Wiggle +#### Flash -Visual: Horizontal shake/wiggle. Side-to-side for attention. +Visual: Opacity pulsing/blinking. Attention, warning indicator. Parameters: -- `intensity`: 0-1 (default: 0.5) +- No preset-specific parameters ```typescript -{ type: 'Wiggle' } -{ type: 'Wiggle', intensity: 1 } // More vigorous +{ + type: 'Flash'; +} ``` #### Flip @@ -909,10 +792,11 @@ Visual: Periodic 180° flips. Card-like rotation showing front/back. Parameters: -- `axis`: vertical | horizontal +- `direction`: 'vertical' | 'horizontal' +- `perspective`: number ```typescript -{ type: 'Flip', axis: 'horizontal' } +{ type: 'Flip', direction: 'horizontal' } ``` #### Fold @@ -922,11 +806,11 @@ Visual: 3D folding motion. Paper-like folding and unfolding. Parameters: - `direction`: top | right | bottom | left -- `angle`: fold angle (default: 30) +- `angle`: number in degrees (default: 15) ```typescript { type: 'Fold', direction: 'left' } -{ type: 'Fold', direction: 'top', angle: 45 } // More dramatic +{ type: 'Fold', direction: 'top', angle: 45 } ``` #### Jello @@ -935,24 +819,11 @@ Visual: Wobbly elastic deformation. Jiggly, bouncy distortion. Parameters: -- `intensity`: 0-1 (default: 0.5) +- `intensity`: number 0-1 (default: 0.25) ```typescript { type: 'Jello' } -{ type: 'Jello', intensity: 1 } // More wobbly -``` - -#### Rubber - -Visual: Elastic stretch effect. Springy stretching and snapping. - -Parameters: - -- `intensity`: 0-1 (default: 0.05) - -```typescript -{ type: 'Rubber' } -{ type: 'Rubber', intensity: 0.1 } // More stretchy +{ type: 'Jello', intensity: 1 } ``` #### Poke @@ -961,168 +832,112 @@ Visual: Quick scale bump like being tapped. Brief attention "boop". Parameters: -- `direction`: top | right | bottom | left -- `intensity`: 0-1 (default: 0.5) +- `direction`: top | right | bottom | left (default: 'right') +- `intensity`: number 0-1 (default: 0.5) ```typescript { type: 'Poke', direction: 'top' } -{ type: 'Poke', direction: 'right', intensity: 1 } // More dramatic +{ type: 'Poke', direction: 'right', intensity: 1 } ``` -#### Cross - -Visual: X-pattern diagonal movement. Unique geometric motion. - -Parameters: - -- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right - -```typescript -{ type: 'Cross', direction: 'top-left' } -``` - -#### DVD - -Visual: Corner-to-corner bounce (DVD screensaver). Nostalgic, retro. - -Parameters: - -- `duration`: 100-4000ms (default: 1200) -- `delay`: 0-8000ms (default: 0) - -```typescript -{ - type: 'DVD'; -} -``` - ---- - -### Mouse Presets - -#### Tilt3DMouse +#### Pulse -Visual: Element tilts toward cursor in 3D, like angling a card. Premium, interactive. +Visual: Gentle scale oscillation, heartbeat-like rhythm. Subtle, universal. Parameters: -- `angle`: 5-85 degrees (default: 50) -- `perspective`: 200-1000px (default: 500) -- `inverted`: boolean (default: false) +- `intensity`: number 0-1 (default: 0) ```typescript -{ type: 'Tilt3DMouse' } -{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } // Subtle professional -{ type: 'Tilt3DMouse', angle: 85, perspective: 200 } // Dramatic +{ type: 'Pulse' } +{ type: 'Pulse', intensity: 0.5 } ``` -#### TrackMouse +#### Rubber -Visual: Element follows cursor position. Floating, parallax-like. +Visual: Elastic stretch effect. Springy stretching and snapping. Parameters: -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: { value: 250, type: 'px' }) -- `axis`: horizontal | vertical | both (default: both) -- `inverted`: boolean (default: false) +- `intensity`: number 0-1 (default: 0.5) ```typescript -{ type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } -{ type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'horizontal' } // Background layer +{ type: 'Rubber' } +{ type: 'Rubber', intensity: 1 } ``` -#### BounceMouse +#### Spin -Visual: Bouncy/elastic cursor following. Overshoots and wobbles. +Visual: Continuous rotation around center. Mechanical, precise. Parameters: -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } (default: { value: 80, type: 'px' }) -- `axis`: horizontal | vertical | both (default: both) -- `inverted`: boolean (default: false) +- `direction`: 'clockwise' | 'counter-clockwise' (default: clockwise) ```typescript -{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } +{ type: 'Spin', direction: 'clockwise' } ``` -#### Track3DMouse +#### Swing -Visual: Combined translation + 3D rotation following mouse. Complex, immersive. +Visual: Rotation oscillation like a pendulum. Back and forth rhythmic. Parameters: -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `angle`: rotation angle (default: 50) -- `axis`: horizontal | vertical | both -- `perspective`: perspective distance (default: 500) -- `inverted`: boolean +- `swing`: number in degrees (default: 20) +- `direction`: top | right | bottom | left ```typescript -{ type: 'Track3DMouse', distance: { value: 100, type: 'px' }, axis: 'both' } -{ type: 'Track3DMouse', distance: { value: 50, type: 'px' }, angle: 25, perspective: 1000 } // Subtle +{ type: 'Swing' } +{ type: 'Swing', swing: 60 } ``` -#### SpinMouse +#### Wiggle -Visual: Rotation following mouse angle. Element spins based on cursor position. +Visual: Horizontal shake/wiggle. Side-to-side for attention. Parameters: -- `axis`: horizontal | vertical | both -- `inverted`: boolean +- `intensity`: number 0-1 (default: 0.5) ```typescript -{ type: 'SpinMouse' } -{ type: 'SpinMouse', axis: 'both' } +{ type: 'Wiggle' } +{ type: 'Wiggle', intensity: 1 } ``` -#### ScaleMouse - -Visual: Scale based on cursor distance. Grows/shrinks by proximity. - -Parameters: +--- -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `axis`: horizontal | vertical | both -- `scale`: scale factor (default: depends on scaleDirection) -- `scaleDirection`: in | out -- `inverted`: boolean +### Mouse Presets -```typescript -{ type: 'ScaleMouse', distance: { value: 100, type: 'px' }, scaleDirection: 'in' } -{ type: 'ScaleMouse', distance: { value: 100, type: 'px' }, scaleDirection: 'out', scale: 2.4 } // Dramatic grow -``` +All mouse presets accept an optional `inverted`: boolean parameter. -#### SwivelMouse +#### AiryMouse -Visual: Z-axis rotation following cursor. Gyroscope-like vertical rotation. +Visual: Floating/airy cursor response. Ethereal, gentle drift. Parameters: -- `angle`: rotation angle (default: 50) -- `perspective`: perspective distance (default: 700) -- `pivotAxis`: top | bottom | right | left | center-horizontal | center-vertical -- `inverted`: boolean +- `distance`: UnitLengthPercentage +- `axis`: 'horizontal' | 'vertical' | 'both' +- `angle`: number (default: 50) ```typescript -{ type: 'SwivelMouse' } -{ type: 'SwivelMouse', angle: 25, perspective: 1000 } // Subtle +{ type: 'AiryMouse' } +{ type: 'AiryMouse', angle: 10 } // Subtle ``` -#### SkewMouse +#### BlobMouse -Visual: Skew distortion following cursor. Angular distortion. +Visual: Organic blob-like deformation. Fluid shape distortion. Parameters: -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `angle`: skew angle (default: 20) -- `axis`: horizontal | vertical | both -- `inverted`: boolean +- `distance`: UnitLengthPercentage +- `scale`: number (default: 1.6) ```typescript -{ type: 'SkewMouse' } -{ type: 'SkewMouse', angle: 45 } // More dramatic +{ type: 'BlobMouse' } +{ type: 'BlobMouse', scale: 2.4 } ``` #### BlurMouse @@ -1131,47 +946,28 @@ Visual: Blur based on cursor distance. Focus/defocus by proximity. Parameters: -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `angle`: angle (default: 25) -- `scale`: scale factor (default: 0.7) -- `blur`: blur amount -- `perspective`: perspective distance -- `inverted`: boolean +- `distance`: UnitLengthPercentage +- `angle`: number (default: 25) +- `scale`: number (default: 0.7) +- `blur`: number +- `perspective`: number ```typescript { type: 'BlurMouse' } -{ type: 'BlurMouse', angle: 65, scale: 0.25 } // More dramatic +{ type: 'BlurMouse', angle: 65, scale: 0.25 } ``` -#### AiryMouse - -Visual: Floating/airy cursor response. Ethereal, gentle drift. - -Parameters: - -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `axis`: horizontal | vertical | both -- `angle`: angle (default: 50) -- `inverted`: boolean - -```typescript -{ type: 'AiryMouse' } -{ type: 'AiryMouse', angle: 10 } // Subtle -``` - -#### BlobMouse +#### BounceMouse -Visual: Organic blob-like deformation. Fluid shape distortion. +Visual: Bouncy/elastic cursor following. Overshoots and wobbles. Parameters: -- `distance`: { value: number, type: 'px' | 'percentage' | 'vh' | 'vw' } -- `scale`: scale factor (default: 1.6) -- `inverted`: boolean +- `distance`: UnitLengthPercentage (default: 80px) +- `axis`: 'horizontal' | 'vertical' | 'both' ```typescript -{ type: 'BlobMouse' } -{ type: 'BlobMouse', scale: 2.4 } // More dramatic +{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } ``` #### CustomMouse @@ -1184,189 +980,203 @@ Visual: Configurable custom behavior. For advanced custom implementations. } ``` ---- - -### Background Scroll Presets - -**Requires DOM structure with `data-motion-part` attributes** (`BG_LAYER`, `BG_MEDIA`, `BG_IMG`). See [Background Scroll trigger](#background-scroll) for structure details. - -#### BgParallax +#### ScaleMouse -Visual: Background moves slower than scroll, creating depth. Most common bg effect. +Visual: Scale based on cursor distance. Grows/shrinks by proximity. Parameters: -- `speed`: 0.05-0.95 (default: 0.2) — lower = further away feeling +- `distance`: UnitLengthPercentage +- `axis`: 'horizontal' | 'vertical' | 'both' +- `scale`: number ```typescript -{ type: 'BgParallax' } -{ type: 'BgParallax', speed: 0.4 } // Noticeable depth +{ type: 'ScaleMouse', distance: { value: 100, type: 'px' } } ``` -#### BgZoom +#### SkewMouse -Visual: Background zooms in/out as user scrolls. Cinematic dolly effect. +Visual: Skew distortion following cursor. Angular distortion. Parameters: -- `direction`: in | out (default: in) -- `zoom`: 0.1-10 (default: 10) — start lower for subtle effect +- `distance`: UnitLengthPercentage +- `angle`: number (default: 20) +- `axis`: 'horizontal' | 'vertical' | 'both' ```typescript -{ type: 'BgZoom', direction: 'in' } -{ type: 'BgZoom', direction: 'in', zoom: 3 } // Subtle zoom +{ type: 'SkewMouse' } +{ type: 'SkewMouse', angle: 45 } ``` -#### BgFade +#### SpinMouse -Visual: Background opacity changes on scroll. Subtle section transitions. +Visual: Rotation following mouse angle. Element spins based on cursor position. Parameters: -- `range`: in | out (required) -- `start`: 0-100% -- `end`: 0-100% +- `axis`: 'horizontal' | 'vertical' | 'both' ```typescript -{ type: 'BgFade', range: 'in' } -{ type: 'BgFade', range: 'out' } +{ type: 'SpinMouse' } +{ type: 'SpinMouse', axis: 'both' } ``` -#### BgFadeBack +#### SwivelMouse -Visual: Fade targeting back layer specifically. For layered backgrounds. +Visual: Z-axis rotation following cursor. Gyroscope-like vertical rotation. Parameters: -- `scale`: scale factor +- `angle`: number (default: 50) +- `perspective`: number (default: 700) +- `pivotAxis`: 'top' | 'bottom' | 'right' | 'left' | 'center-horizontal' | 'center-vertical' ```typescript -{ - type: 'BgFadeBack'; -} +{ type: 'SwivelMouse' } +{ type: 'SwivelMouse', angle: 25, perspective: 1000 } // Subtle ``` -#### BgPan +#### Tilt3DMouse -Visual: Horizontal/vertical background panning on scroll. +Visual: Element tilts toward cursor in 3D, like angling a card. Premium, interactive. Parameters: -- `direction`: left | right -- `speed`: pan speed +- `angle`: number (default: 50) +- `perspective`: number (default: 500) ```typescript -{ type: 'BgPan', direction: 'left' } +{ type: 'Tilt3DMouse' } +{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } // Subtle professional +{ type: 'Tilt3DMouse', angle: 85, perspective: 200 } // Dramatic ``` -#### BgRotate +#### Track3DMouse -Visual: Background rotation driven by scroll. Dynamic, unusual. +Visual: Combined translation + 3D rotation following mouse. Complex, immersive. Parameters: -- `direction`: clockwise | counter-clockwise -- `angle`: rotation angle +- `distance`: UnitLengthPercentage +- `angle`: number (default: 50) +- `axis`: 'horizontal' | 'vertical' | 'both' +- `perspective`: number (default: 500) ```typescript -{ type: 'BgRotate' } -{ type: 'BgRotate', direction: 'clockwise', angle: 15 } +{ type: 'Track3DMouse', distance: { value: 100, type: 'px' }, axis: 'both' } +{ type: 'Track3DMouse', distance: { value: 50, type: 'px' }, angle: 25, perspective: 1000 } ``` -#### BgSkew +#### TrackMouse -Visual: Background skew distortion on scroll. Experimental. +Visual: Element follows cursor position. Floating, parallax-like. Parameters: -- `direction`: clockwise | counter-clockwise -- `angle`: skew angle +- `distance`: UnitLengthPercentage (default: 250px) +- `axis`: 'horizontal' | 'vertical' | 'both' ```typescript -{ - type: 'BgSkew'; -} +{ type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } +{ type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'horizontal' } ``` -#### BgReveal +--- -Visual: Clip-based background reveal. Theatrical unveiling. +## 5. Selection Tables -```typescript -{ - type: 'BgReveal'; -} -``` +### By Tone -#### BgCloseUp +| Tone | Entrance | Scroll | Ongoing | Mouse | +| ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | +| Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | +| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | -Visual: Alternative zoom implementation. Cinematic close-up approach. +### By Use Case -Parameters: +| Use Case | Recommended Presets | +| ---------------------- | ---------------------------------------------- | +| Hero sections | ArcIn, FloatIn, RevealIn | +| Modals/Popups | FadeIn, DropIn, ExpandIn, SlideIn | +| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | +| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | +| Notifications/Badges | BounceIn, DropIn + Pulse | +| CTAs/Buttons | BounceIn, ExpandIn + Pulse | +| Loading indicators | Spin, Pulse | +| Product images | Tilt3DMouse, ScaleMouse | +| Background depth | ParallaxScroll, TrackMouse (layered) | -- `scale`: zoom scale +### Cross-Category Parallels -```typescript -{ - type: 'BgCloseUp'; -} -``` +Effects with similar visual results across categories: + +| Entrance | Scroll | Ongoing | Mouse | +| -------- | -------------- | ------- | ----------- | +| FadeIn | FadeScroll | Flash | - | +| ArcIn | ArcScroll | - | - | +| SpinIn | SpinScroll | Spin | SpinMouse | +| BounceIn | - | Bounce | BounceMouse | +| TiltIn | TiltScroll | - | Tilt3DMouse | +| FlipIn | FlipScroll | Flip | - | +| ExpandIn | GrowScroll | Pulse | ScaleMouse | +| SlideIn | SlideScroll | - | TrackMouse | +| BlurIn | BlurScroll | - | BlurMouse | +| RevealIn | RevealScroll | - | - | +| - | ParallaxScroll | - | TrackMouse | -#### BgPullBack +--- -Visual: Reverse zoom (pulling away). Expansive revealing. +## 6. Combining Animations -Parameters: +1. Avoid mixing multiple animations on the same element when possible +2. Never combine animations that affect the same CSS properties (e.g., two animations both using `transform`) +3. When combining is necessary, animation order matters - later animations may override earlier ones +4. If possible, use nested containers to separate animations that would conflict - place each animation on a separate wrapper element + +### Common Patterns -- `scale`: zoom scale +**Card reveal on scroll:** ```typescript -{ - type: 'BgPullBack'; -} +{ type: 'FadeScroll', range: 'in' } ``` -#### BgFake3D - -Visual: Simulated 3D depth layers. Immersive parallax-enhanced depth. - -Parameters: - -- `stretch`: stretch amount -- `zoom`: zoom factor +**Interactive product card (nested containers):** ```typescript -{ - type: 'BgFake3D'; -} +// Outer container - entrance +{ type: 'FadeIn' } +// Inner container - mouse interaction +{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } ``` -#### ImageParallax - -Visual: Parallax for regular `` elements (not CSS backgrounds). +**Notification badge:** -Parameters: +```typescript +{ type: 'BounceIn', direction: 'top', distanceFactor: 1 } +{ type: 'Pulse', intensity: 0.5 } +``` -- `reverse`: boolean -- `speed`: parallax speed -- `isPage`: boolean +**Loading indicator:** ```typescript -{ type: 'ImageParallax' } -{ type: 'ImageParallax', speed: 0.3 } +{ type: 'Spin', direction: 'clockwise' } ``` --- -## 5. Accessibility +## 7. Accessibility ### Host vs Preset Responsibility -The presets provide animations; the host platform decides when and whether to apply them. +The presets provide animations; the host platform decides when/whether to apply them. + +Interact supports `conditions` in the config for handling reduced motion. Define a media condition for `(prefers-reduced-motion: reduce)` and use it to swap high-risk presets for safer alternatives (e.g., SpinIn → FadeIn, BounceIn → FadeIn). Conditions can be applied per-interaction or per-effect, and automatically re-evaluate when the user's preference changes. -- When the host handles accessibility globally (e.g., disabling all animations under `prefers-reduced-motion`), presets don't need to address it separately -- Keyboard triggers (`activate`/`interest`) and config options like `allowA11yTriggers` are library-level features, not part of preset configuration -- This section provides guidance for preset selection, not library configuration +When the host handles accessibility globally (e.g., disabling all animations), presets don't need to address it separately. ### Preset Risk Levels @@ -1380,15 +1190,15 @@ The presets provide animations; the host platform decides when and whether to ap **Medium risk** (strong motion, may affect some users): - TurnIn -- ParallaxScroll, BgParallax at high speed values +- ParallaxScroll at high speed values **Low risk / safe** (opacity/blur changes, minimal spatial movement): - FadeIn, FadeScroll, BlurIn, BlurScroll -- SlideIn (subtle settings), GlideIn (subtle settings) -- Pulse (low intensity), Breathe +- SlideIn (subtle), GlideIn (subtle) +- Pulse (subtle), Breathe -### Reduced Motion Fallback Table +### Reduced Motion Fallbacks | Original | Fallback | | --------------------------------- | ------------------------- | @@ -1398,134 +1208,42 @@ The presets provide animations; the host platform decides when and whether to ap | Flash | Reduce frequency (<3/sec) | | ParallaxScroll | Static position | | ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | -| BgParallax, BgZoom | Static background | | All mouse animations | Static state | -### Trigger Considerations +### LLM Guidance Principles -All preset triggers play automatically without explicit user action: - -| Trigger | Behavior | Note | -| ----------------- | ------------------------------------- | ------------------------------------------ | -| Entrance | Plays on viewport entry (`viewEnter`) | Not user-initiated | -| Scroll | Tied to scroll position | Continuous while scrolling | -| Background Scroll | Tied to scroll position | Continuous while scrolling | -| Ongoing | Loops indefinitely | Flash must stay under 3 flashes/sec | -| Mouse | Responds to cursor position | Desktop only, no touch/keyboard equivalent | - -### LLM Guidance for Preset Selection - -**Do not limit creativity by default.** If the user asks for "grand", "energetic", "stunning", or similar, generate accordingly using any appropriate presets. - -**Apply accessibility constraints only when explicitly requested** via phrases like: - -- "accessible", "a11y", "reduced motion safe" -- "subtle", "tone down", "gentle" -- "professional", "minimal" - -**When generating high-risk presets:** Optionally note in your response that some presets may affect users with vestibular sensitivity. This is informational, not a blocker. - -**Mouse presets:** Note that these are desktop-only (no touch/keyboard equivalent). This is informational context, not a restriction. - -**Duration guidelines** (suggestions, not limits): - -- Functional UI (modals, dropdowns): under 500ms -- Decorative content: up to 1200ms -- Hero moments: up to 2000ms - -### Stagger Patterns - -For lists/grids, apply increasing subtle `delay` values +1. **Do not limit creativity by default** - generate what the user asks for +2. **Apply constraints only when explicitly requested** - keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" +3. **High-risk presets are informational, not blockers** - optionally note vestibular concerns in response +4. **Mouse presets may behave differently on mobile** - note this as context, not a restriction +5. **Duration guidelines are suggestions** - functional UI <500ms, decorative up to 1200ms, hero up to 2000ms ### Performance Notes - **Scroll animations run continuously**: use sparingly, test on low-end devices - **Mouse animations calculate on every mousemove**: limit to 1-3 elements -- **Background animations are heavy**: avoid multiple simultaneous bg effects - **3D transforms require GPU**: can cause jank on older devices - **Prefer `transform` and `opacity`**: these are GPU-accelerated -### Combining Animations - -**Single element (natively supported):** - -- Entrance + Ongoing only: `{ entrance: 'BounceIn', ongoing: 'Pulse' }` - -**Requires nested containers:** - -- Entrance + Mouse: Outer container has entrance, inner has mouse effect -- Entrance + Scroll: Separate containers for each -- Any other cross-trigger combination - -**Separate elements:** - -- Scroll + Background: Content element with FadeScroll, background element with BgParallax - -**Invalid (same trigger type on same element):** - -- Two entrance animations -- Multiple scroll animations -- Multiple ongoing animations - -### Common Patterns - -**Card reveal on scroll:** - -```typescript -{ type: 'FadeScroll', range: 'in' } -``` - -**Interactive product card (requires nested containers):** - -```typescript -// Outer container - entrance -{ type: 'FadeIn' } -// Inner container - mouse interaction -{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } // subtle -``` - -**Hero with depth (separate elements):** - -```typescript -// Background element -{ type: 'BgParallax', speed: 0.2 } -// Content element -{ type: 'ArcIn', direction: 'bottom' } -``` - -**Notification badge (single element - entrance + ongoing supported):** - -```typescript -// Same element can have both -{ type: 'BounceIn', direction: 'top', distanceFactor: 1 } // entrance, subtle -{ type: 'Pulse', intensity: 0.06 } // ongoing -``` - -**Loading indicator:** - -```typescript -{ type: 'Spin', direction: 'clockwise', duration: 1500 } -``` - --- -## 7. Intensity Value Guide +## 8. Intensity Value Guide When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use these value mappings as guidance for suggesting appropriate parameter values. ### Entrance Presets Intensity Values -| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | -| -------- | ---------------- | ----------- | ------- | ------------- | -| ArcIn | easing | quintInOut | backOut | backInOut | -| BlurIn | blur | 6px | 25px | 50px | -| BounceIn | distanceFactor | 1 | 2 | 3 | -| DropIn | initialScale | 1.2 | 1.6 | 2 | -| FlipIn | initialRotate | 45° | 90° | 270° | -| FoldIn | initialRotate | 35° | 60° | 90° | -| GrowIn | initialScale | 0.8 | 0.6 | 0 | -| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | -| SpinIn | initialScale | 0.8 | 0.5 | 0 | +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| -------- | ---------------- | ----------- | ---------- | ------------- | +| ArcIn | easing | cubicInOut | quintInOut | backOut | +| BlurIn | blur | 6px | 25px | 50px | +| BounceIn | distanceFactor | 1 | 2 | 3 | +| DropIn | initialScale | 1.2 | 1.6 | 2 | +| FlipIn | initialRotate | 45° | 90° | 270° | +| FoldIn | initialRotate | 35° | 60° | 90° | +| ExpandIn | initialScale | 0.8 | 0.6 | 0 | +| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | +| SpinIn | initialScale | 1 | 0.6 | 0 | ### Scroll Presets Intensity Values @@ -1540,21 +1258,21 @@ When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use | Spin3dScroll | rotate | 45° | 100° | 200° | | SpinScroll | scale | 1 | 0.7 | 0.4 | | StretchScroll | stretch | 1.2 | 1.5 | 2 | -| TiltScroll | distance | 0.25 | 0.5 | 1 | +| TiltScroll | distance | 0 | 0.5 | 1 | | TurnScroll | scale | 1 | 1.3 | 1.6 | ### Ongoing Presets Intensity Values | Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | | ------ | --------- | ----------- | ------ | ------------- | -| Bounce | intensity | 0.3 | 0.5 | 1 | +| Bounce | intensity | 0 | 0.5 | 1 | | Fold | angle | 15° | 30° | 45° | -| Jello | intensity | 0.25 | 0.5 | 1 | -| Poke | intensity | 0.25 | 0.5 | 1 | -| Pulse | intensity | 0 | 0.06 | 0.12 | -| Rubber | intensity | 0 | 0.05 | 0.1 | +| Jello | intensity | 0 | 0.33 | 1 | +| Poke | intensity | 0 | 0.33 | 1 | +| Pulse | intensity | 0 | 0.5 | 1 | +| Rubber | intensity | 0 | 0.5 | 1 | | Swing | swing | 20° | 40° | 60° | -| Wiggle | intensity | 0.25 | 0.5 | 1 | +| Wiggle | intensity | 0 | 0.33 | 1 | ### Mouse Presets Intensity Values @@ -1570,7 +1288,7 @@ When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use | Tilt3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 200 | | Track3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 333 | -### Usage Example +### Intensity Usage Example When a user asks: "I want a subtle flip entrance" diff --git a/packages/motion-presets/rules/presets/scroll.md b/packages/motion-presets/rules/presets/scroll.md index 0389c26e..11fb6de2 100644 --- a/packages/motion-presets/rules/presets/scroll.md +++ b/packages/motion-presets/rules/presets/scroll.md @@ -1,11 +1,11 @@ --- name: Scroll Animations -trigger: scroll +category: scroll --- # Scroll Animations -Animations tied to scroll position. Can animate in, out, or continuously. +Animations whose progress is tied to a ViewTimeline - the element's position in the viewport. ## When to Use Scroll Animations @@ -16,20 +16,19 @@ Animations tied to scroll position. Can animate in, out, or continuously. ## When NOT to Use Scroll Animations -- One-time entrance → see [Entrance](presets-reference.md#entrance) (more performant) -- Continuous loops → see [Ongoing](presets-reference.md#ongoing) -- Background images → see [Background Scroll](presets-reference.md#background-scroll) +- One-time entrance → see [Entrance](presets-reference.md#entrance-presets) (more performant) +- Continuous loops → see [Ongoing](presets-reference.md#ongoing-presets) ## Available Scroll Presets See [Scroll Presets](presets-reference.md#scroll-presets) for full details: -ParallaxScroll, FadeScroll, ArcScroll, BlurScroll, FlipScroll, GrowScroll, ShrinkScroll, MoveScroll, PanScroll, RevealScroll, ShapeScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll +ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll ## Scroll Range Modes -- `in`: Animates as element enters viewport (0% → 50%) -- `out`: Animates as element exits viewport (50% → 100%) +- `in`: Animates as element enters viewport +- `out`: Animates as element exits viewport - `continuous`: Animates throughout entire scroll range ## Scroll Quick Decision From 10431cbdfcf759235983d129c0b0b194df6bbcfe Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Wed, 18 Feb 2026 20:35:48 +0200 Subject: [PATCH 16/20] refactored rules to the structure of skills for future coimpatibility. editd some of the descriptions to be more accurate --- packages/motion-presets/rules/presets/PLAN.md | 338 +++-- .../rules/presets/entrance-presets.md | 326 +++++ .../motion-presets/rules/presets/entrance.md | 46 - .../rules/presets/mouse-presets.md | 224 +++ .../motion-presets/rules/presets/mouse.md | 52 - .../rules/presets/ongoing-presets.md | 222 +++ .../motion-presets/rules/presets/ongoing.md | 46 - .../rules/presets/presets-main.md | 332 +++++ .../rules/presets/presets-reference.md | 1295 ----------------- .../rules/presets/scroll-presets.md | 346 +++++ .../motion-presets/rules/presets/scroll.md | 51 - 11 files changed, 1686 insertions(+), 1592 deletions(-) create mode 100644 packages/motion-presets/rules/presets/entrance-presets.md delete mode 100644 packages/motion-presets/rules/presets/entrance.md create mode 100644 packages/motion-presets/rules/presets/mouse-presets.md delete mode 100644 packages/motion-presets/rules/presets/mouse.md create mode 100644 packages/motion-presets/rules/presets/ongoing-presets.md delete mode 100644 packages/motion-presets/rules/presets/ongoing.md create mode 100644 packages/motion-presets/rules/presets/presets-main.md delete mode 100644 packages/motion-presets/rules/presets/presets-reference.md create mode 100644 packages/motion-presets/rules/presets/scroll-presets.md delete mode 100644 packages/motion-presets/rules/presets/scroll.md diff --git a/packages/motion-presets/rules/presets/PLAN.md b/packages/motion-presets/rules/presets/PLAN.md index b4d6e245..754b250c 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/packages/motion-presets/rules/presets/PLAN.md @@ -1,30 +1,116 @@ --- name: LLM Preset Rules -overview: Consolidated single-file reference with category-specific preset guides. +overview: Single source of truth for generating and maintaining all preset reference files. status: in-progress -version: 2.0 -last-updated: 2026-02-01 +version: 3.0 +last-updated: 2026-02-18 --- # LLM Rules for Motion Presets -This file serves as the **source of truth** for regenerating `presets-reference.md` when presets change. +This file is the **single source of truth** for generating all preset reference files. Every guideline, table, and parameter standard in the generated files originates here. -## Structure +## Table of Contents + +- [Generated Files](#generated-files) +- [Skills Compatibility](#skills-compatibility) +- [Terminology](#terminology) +- [Preset Registry](#preset-registry) +- [Key Constraints](#key-constraints) +- [Parameter Standards](#parameter-standards) +- [Optional Parameters](#optional-parameters) +- [Accessibility](#accessibility) +- [Selection Tables](#selection-tables) +- [Intensity Value Guide](#intensity-value-guide) +- [Preset Entry Format](#preset-entry-format) +- [Regeneration Steps](#regeneration-steps) + +## Generated Files ```text rules/presets/ -├── presets-reference.md # Comprehensive reference (all presets, all info) -├── entrance.md # Entrance preset category guide -├── scroll.md # Scroll preset category guide -├── ongoing.md # Ongoing preset category guide -└── mouse.md # Mouse preset category guide +├── PLAN.md # THIS FILE — source of truth, not read by LLM at runtime +├── presets-main.md # Generated: entry point (<500 lines) — decision flow, categories, standards, selection, a11y +├── entrance-presets.md # Generated: full entrance preset params, examples, optional params, intensity +├── scroll-presets.md # Generated: full scroll preset params, examples, optional params, intensity +├── ongoing-presets.md # Generated: full ongoing preset params, examples, intensity +└── mouse-presets.md # Generated: full mouse preset params, examples, intensity, mobile notes +``` + +### What Goes Where + +| Source Section (this file) | Generates Into | +| ------------------------------------------------- | ----------------------- | +| Terminology | presets-main.md | +| Key Constraints (categories, triggers, combining) | presets-main.md | +| Parameter Standards | presets-main.md | +| Selection Tables | presets-main.md | +| Accessibility | presets-main.md | +| Preset Registry | presets-main.md (lists) | +| Preset Entry Format + source code | {category}-presets.md | +| Optional Parameters | {category}-presets.md | +| Intensity Value Guide | {category}-presets.md | + +--- + +## Skills Compatibility + +The generated files are structured for future conversion to an Agentic Skill. When generating or editing these files, follow these conventions so they can be moved with minimal changes: + +### Frontmatter + +Every generated file must have YAML frontmatter with at least `name` and `description`. The `description` should be written in third person and include both WHAT the file does and WHEN an agent should read it. + +```yaml +--- +name: lowercase-with-hyphens (max 64 chars) +description: Third-person description with trigger terms. Max 1024 chars. +--- ``` +When converting to a real skill, `presets-main.md` becomes `SKILL.md` and its `description` becomes the skill discovery text. + +### Structure Rules + +- **Main entry file** (`presets-main.md` / future `SKILL.md`): under 500 lines +- **Reference files**: linked one level deep from the main file, no further nesting +- **Heading hierarchy**: `#` (title) → `##` (sections) → `###` (subsections) — no skipped levels +- **Progressive disclosure**: essential info in the main file, detailed reference in separate files +- **TOC**: include a table of contents in every file +- **Consistent terminology**: "preset" for selection, "effect" for runtime, "animation" for visual motion +- **No time-sensitive information**: avoid dates, version-specific caveats + +### Future Conversion Checklist + +To convert to a real Cursor Skill: + +1. Create the skill in the right "skills" folder +2. Copy `presets-main.md` → `SKILL.md` +3. Copy `{category}-presets.md` files alongside it +4. Verify `SKILL.md` description has trigger terms for agent discovery +5. Remove `category` field from frontmatter (not needed in skills) +6. Verify all internal links still resolve + +--- + +## Terminology + +| Term | Meaning | +| ------------- | --------------------------------------------------------------------------------------- | +| **Effect** | Interact's term for an operation applied to an element (animation, custom effect, etc.) | +| **Preset** | A pre-built, named effect configuration from this library (e.g., `FadeIn`, `BounceIn`) | +| **Animation** | The actual visual motion that runs in the browser (CSS or WAAPI) | + +A preset is a named effect. "Preset" is used when talking about selection and configuration; "effect" when talking about the Interact runtime; "animation" when referring to the visual motion or CSS/WAAPI mechanism. + --- ## Preset Registry +A list of the presets present in the project. Before continuing, make sure this list is aligned with `../src/library` and update accordingly. + +_Note:_ the descriptions should be verified by a designer + ### Entrance Presets | Preset | Notes | @@ -117,19 +203,23 @@ rules/presets/ These are categories of presets, each optimized for certain use cases but not limited to a single trigger mechanism. -| Category | Optimized For | Notes | -| -------- | ----------------------------------- | ----------------------------------------------------------------------- | -| entrance | `viewEnter` (intersection observer) | Can also be triggered by hover, click, animationend, and other triggers | -| scroll | ViewTimeline (scroll progress) | Animation progress tied to element's position in the viewport | -| ongoing | Continuous loop | Runs indefinitely until stopped | -| mouse | Pointer position binding | Real-time response to cursor position; may behave differently on mobile | +| Category | Optimized For | Implementation | Notes | +| -------- | -------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- | +| entrance | When an element enters the viewport | `viewEnter` (intersection observer) | Can also be triggered by hover, click, animationend, and other triggers | +| scroll | Scroll position of an element relative to document | ViewTimeline (scroll progress) | Animation progress tied to element's position in the viewport | +| ongoing | Continuous loop | infinite CSS/WAAPI animation | Runs indefinitely until stopped | +| mouse | Follow or Repel by Pointer position | transform values driven by pointer position | Real-time response to cursor position; may behave differently on mobile | + +### Trigger and Effect Binding -### Combining Animations +In the simplest case, a trigger and its effect are bound to the same element. However, an effect on one element can also be triggered by another element (e.g., hovering a button triggers a FadeIn on a sibling panel). -1. Avoid mixing multiple animations on the same element when possible -2. Never combine animations that affect the same CSS properties (e.g., two animations both using `transform`) -3. When combining is necessary, animation order matters - later animations may override earlier ones -4. If possible, use nested containers to separate animations that would conflict - place each animation on a separate wrapper element +### Combining Effects + +1. Avoid mixing multiple effects on the same element at the same time when possible +2. Never combine effects that affect the same CSS properties (e.g., two effects both using `transform`) +3. When combining is necessary, effect order matters — later effects may override earlier ones +4. If possible, use nested containers to separate effects that would conflict — place each effect on a separate wrapper element. Note: here also order matters --- @@ -137,7 +227,7 @@ These are categories of presets, each optimized for certain use cases but not li ### Animation Options (Not Preset Parameters) -These are set on the animation/effect configuration level, not on the preset itself: +These are set on the effect configuration level, not on the preset itself: - `duration`: Animation duration in ms (entrance, ongoing) - `delay`: Animation delay in ms (entrance, ongoing) @@ -156,17 +246,27 @@ These are set on the animation/effect configuration level, not on the preset its **Most Scroll presets:** -- `range`: 'in' | 'out' | 'continuous' (controls animation direction relative to scroll) +- `range`: 'in' | 'out' | 'continuous' + - `'in'`: animation ends at the element's idle state (element animates in as it enters) + - `'out'`: animation starts from the element's idle state (element animates out as it exits) + - `'continuous'`: animation passes through the idle state (animates across the full scroll range) ### Overloaded Parameter Names The `direction` parameter accepts different values depending on the preset: -| Meaning | Accepted Values | Presets | -| ------------------ | ------------------------------------------------------------------ | -------------------------------- | -| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | -| Extended cardinal | + 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center' | BounceIn, ShapeIn | -| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | +| Meaning | Accepted Values | Presets | +| ------------------ | ------------------------------------------------------ | -------------------------------- | +| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | +| Cardinal + center | 'top', 'right', 'bottom', 'left', 'center' | BounceIn | +| Corner direction | 'top-left', 'top-right', 'bottom-left', 'bottom-right' | TurnIn | +| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | + +### Using Units + +Interact supports both a CSSUnitValue-style object (e.g., `distance: { value: 120, type: 'px' }`, mapped to the internal type `UnitLengthPercentage`) and flat string values (e.g., `distance: '120px'`). + +Prefer the object notation. In any case, be consistent within a configuration — use one format, not both. ### Coordinate System @@ -179,7 +279,7 @@ The `direction` parameter accepts different values depending on the preset: ### Distance Units -Distance parameters use the `UnitLengthPercentage` type: +Supported unit types: `px`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax`, `percentage` ```typescript distance: { value: 120, type: 'px' } // pixels @@ -187,8 +287,6 @@ distance: { value: 50, type: 'percentage' } // percentage distance: { value: 10, type: 'vh' } // viewport height ``` -Supported unit types: `px`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax`, `percentage` - ### CSS Custom Properties The library uses these CSS custom properties for runtime control: @@ -197,9 +295,9 @@ The library uses these CSS custom properties for runtime control: --- -## Optional Parameters (Previously Hardcoded) +## Optional Parameters -Many presets now expose parameters that were previously hardcoded: +Some preset parameters are exposed, but their defaults have been tuned for good visual results and rarely need adjustment: ### 3D Perspective @@ -217,22 +315,11 @@ Many presets now expose parameters that were previously hardcoded: ### Depth (Z Translation) -| Preset | Parameter | Default | Notes | -| --------- | --------- | ------- | ---------------------- | -| ArcIn | `depth` | 300px | Z translation distance | -| CurveIn | `depth` | 900px | Z translation distance | -| TiltIn | `depth` | 200px | Z translation distance | -| ArcScroll | `depth` | 300 | Z translation distance | - -### Rotation Angles - -| Preset | Parameter | Default | Notes | -| --------- | ----------- | ------- | ------------------ | -| ArcIn | `angle` | 80 | Arc rotation angle | -| ArcScroll | `angle` | 68 | Arc rotation angle | -| TiltIn | `tiltAngle` | 90 | Initial tilt angle | -| FloatIn | `distance` | 120 | Float distance | -| TurnIn | `angle` | 50 | Rotation angle | +| Preset | Parameter | Default | Notes | +| ------- | --------- | ------- | ---------------------- | +| ArcIn | `depth` | 200px | Z translation distance | +| CurveIn | `depth` | 300px | Z translation distance | +| TiltIn | `depth` | 200px | Z translation distance | --- @@ -242,15 +329,17 @@ This section documents preset selection guidance for accessibility. It is not ab ### Host vs Preset Responsibility -The presets provide animations; the host platform decides when/whether to apply them. +The presets generally provide animations; the host platform decides when/whether to apply them. Interact supports `conditions` in the config for handling reduced motion. Define a media condition for `(prefers-reduced-motion: reduce)` and use it to swap high-risk presets for safer alternatives (e.g., SpinIn → FadeIn, BounceIn → FadeIn). Conditions can be applied per-interaction or per-effect, and automatically re-evaluate when the user's preference changes. -When the host handles accessibility globally (e.g., disabling all animations), presets don't need to address it separately. +If it is known that the host handles accessibility globally (e.g., disabling all animations on `(prefers-reduced-motion: reduce)`), presets don't need to address it separately. ### Preset Risk Levels -**High risk** (vestibular triggers, seizure risk): +_Note:_ this section should be confirmed by an a11y expert + +**High risk** (vestibular triggers, seizure risk if motion is fast and repetitive): - Spinning: SpinIn, Spin, SpinScroll, SpinMouse, Spin3dScroll - Bouncing: BounceIn, Bounce, BounceMouse @@ -278,43 +367,15 @@ When the host handles accessibility globally (e.g., disabling all animations), p | Flash | Reduce frequency (<3/sec) | | ParallaxScroll | Static position | | ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | -| All mouse animations | Static state | +| All mouse presets | Static state | ### LLM Guidance Principles -1. **Do not limit creativity by default** - generate what the user asks for -2. **Apply constraints only when explicitly requested** - keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" -3. **High-risk presets are informational, not blockers** - optionally note vestibular concerns in response -4. **Mouse presets may behave differently on mobile** - note this as context, not a restriction -5. **Duration guidelines are suggestions** - functional UI <500ms, decorative up to 1200ms, hero up to 2000ms - ---- - -## Preset Entry Format - -For each preset in presets-reference.md: - -```markdown -#### PresetName - -Visual: [1-2 sentences describing what user SEES] - -Parameters: - -- `param1`: type/range (default: value) -- `param2`: type/range (default: value) - -\`\`\`typescript -{ type: 'PresetName', param1: 'value' } -\`\`\` -``` - -**Notes:** - -- Include all required parameters -- Include optional parameters with their defaults -- For angle-based presets, note that 0° = right (east) -- For 3D presets, include perspective parameter if customizable +1. **Do not limit creativity by default** — generate what the user asks for +2. **Apply constraints only when explicitly requested** — keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" +3. **High-risk presets are informational, not blockers** — optionally note vestibular concerns in response +4. **Mouse presets may behave differently on mobile** — note this as context, not a restriction +5. **Duration guidelines are suggestions** — functional UI <500ms, decorative up to 1200ms, hero up to 2000ms --- @@ -322,6 +383,8 @@ Parameters: ### Preset Selection By Tone +_Note:_ the descriptions should be verified by a designer + | Tone | Entrance | Scroll | Ongoing | Mouse | | ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | | Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | @@ -343,27 +406,27 @@ Parameters: | Product images | Tilt3DMouse, ScaleMouse | | Background depth | ParallaxScroll, TrackMouse (layered) | ---- - -## Regeneration Steps - -To regenerate `presets-reference.md`: - -1. Verify Preset Registry in this file is aligned with actual preset files in `motion-presets/src/library/{category}/` (exclude index.ts and test files) -2. Read preset type definitions from `motion-presets/src/types.ts` -3. For each active preset, get params from `motion-presets/src/library/{category}/{Preset}.ts` -4. Apply parameter naming conventions from this file -5. Generate using preset entry format above -6. Organize by preset category -7. Include selection tables from this file -8. Include accessibility section from this file -9. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks +### Cross-Category Parallels + +| Entrance | Scroll | Ongoing | Mouse | +| -------- | -------------- | ------- | ----------- | +| FadeIn | FadeScroll | Flash | - | +| ArcIn | ArcScroll | - | - | +| SpinIn | SpinScroll | Spin | SpinMouse | +| BounceIn | - | Bounce | BounceMouse | +| TiltIn | TiltScroll | - | Tilt3DMouse | +| FlipIn | FlipScroll | Flip | - | +| ExpandIn | GrowScroll | Pulse | ScaleMouse | +| SlideIn | SlideScroll | - | TrackMouse | +| BlurIn | BlurScroll | - | BlurMouse | +| RevealIn | RevealScroll | - | - | +| - | ParallaxScroll | - | TrackMouse | --- ## Intensity Value Guide -When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use these value mappings as guidance for suggesting appropriate parameter values. +Tested values for different intensity levels of effects. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines for suggesting appropriate parameter values. ### Entrance Presets Intensity Values @@ -427,3 +490,74 @@ When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use When a user asks: "I want a subtle flip entrance" Suggest: `{ type: 'FlipIn', initialRotate: 45 }` + +--- + +## Preset Entry Format + +For each preset in the per-category reference files (`{category}-presets.md`): + +```markdown +### PresetName + +Visual: [1-2 sentences describing what user SEES, (should later be verified by a designer)] + +Parameters: + +- `param1`: type/range (default: value) +- `param2`: type/range (default: value) + +\`\`\`typescript +{ type: 'PresetName', param1: 'value' } +\`\`\` +``` + +**Notes:** + +- Include all required parameters +- Include optional parameters with their defaults +- For angle-based presets, note that 0° = right (east) +- For 3D presets, include perspective parameter if customizable + +--- + +## Regeneration Steps + +To regenerate the preset reference files: + +### Step 1: Verify Registry + +Ensure the Preset Registry (above) is aligned with actual preset files in `motion-presets/src/library/{category}/` (exclude index.ts and test files). + +### Step 2: Generate `presets-main.md` + +Build from these sections of this file: + +- **Terminology** → Terminology section +- **Key Constraints** (categories table, trigger binding, combining effects) → Categories + Decision Flow + Combining Effects +- **Parameter Standards** (all subsections) → Parameter Standards section +- **Selection Tables** (by tone, by use case, cross-category parallels) → Selection Tables section +- **Accessibility** (all subsections) → Accessibility section +- **Preset Registry** → Available preset lists per category +- Add progressive disclosure links to each `{category}-presets.md` +- Keep under 500 lines + +### Step 3: Generate `{category}-presets.md` files + +For each category (entrance, scroll, ongoing, mouse): + +1. Read preset type definitions from `motion-presets/src/types.ts` +2. For each preset in that category, get params from `motion-presets/src/library/{category}/{Preset}.ts` +3. Write each preset entry using the **Preset Entry Format** above +4. Append the **Optional Parameters** tables relevant to that category +5. Append the **Intensity Value** table for that category from the Intensity Value Guide above +6. For mouse: include mobile considerations note + +### Step 4: Validate + +1. `presets-main.md` is under 500 lines +2. Heading hierarchy: `#` → `##` → `###` (no skipped levels) +3. Every file has a table of contents after the title +4. Every file has YAML frontmatter with `name` and `description` (see [Skills Compatibility](#skills-compatibility)) +5. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks +6. Verify no content duplication between PLAN.md and generated files (generated files should stand alone; PLAN.md is the source, not a supplement) diff --git a/packages/motion-presets/rules/presets/entrance-presets.md b/packages/motion-presets/rules/presets/entrance-presets.md new file mode 100644 index 00000000..0295480b --- /dev/null +++ b/packages/motion-presets/rules/presets/entrance-presets.md @@ -0,0 +1,326 @@ +--- +name: entrance-presets-reference +description: Full parameter details, examples, and intensity guide for entrance presets. Read when configuring specific entrance preset parameters or choosing intensity levels for entrance animations. +category: entrance +--- + +# Entrance Presets + +All entrance preset parameters and TypeScript examples. For category overview and selection guidance, see [presets-main.md](presets-main.md). + +## Table of Contents + +- [Preset Reference](#preset-reference) +- [Intensity Values](#intensity-values) +- [Optional Parameters](#optional-parameters) + +--- + +## Preset Reference + +### FadeIn + +Visual: Element transitions from invisible to visible. Simple opacity change, no movement. + +Parameters: + +- No preset-specific parameters + +```typescript +{ + type: 'FadeIn'; +} +``` + +### ArcIn + +Visual: Element swings in along a curved 3D path, like a door opening. Dramatic, cinematic. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'right') +- `depth`: UnitLengthPercentage (default: { value: 200, type: 'px' }) +- `perspective`: number (default: 800) + +```typescript +{ type: 'ArcIn', direction: 'bottom' } +{ type: 'ArcIn', direction: 'left', depth: { value: 500, type: 'px' } } +``` + +### BlurIn + +Visual: Element transitions from blurry to sharp focus while fading in. Soft, dreamy. + +Parameters: + +- `blur`: number in px (default: 6) + +```typescript +{ type: 'BlurIn' } +{ type: 'BlurIn', blur: 25 } // Medium +{ type: 'BlurIn', blur: 50 } // Dramatic +``` + +### BounceIn + +Visual: Element bounces into view with spring physics. Playful, attention-grabbing. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'center' (default: 'bottom') +- `distanceFactor`: number (default: 1) +- `perspective`: number (default: 800) - only used with 'center' direction + +```typescript +{ type: 'BounceIn' } +{ type: 'BounceIn', direction: 'center', distanceFactor: 2 } +``` + +### CurveIn + +Visual: Curved 3D motion path entry. Cinematic arc trajectory. + +Parameters: + +- `direction`: 'left' | 'right' | 'pseudoLeft' | 'pseudoRight' (default: 'right') +- `depth`: UnitLengthPercentage (default: { value: 300, type: 'px' }) +- `perspective`: number (default: 200) + +```typescript +{ type: 'CurveIn', direction: 'left' } +``` + +### DropIn + +Visual: Falls from above with subtle scale on landing. Gravity-like, natural. + +Parameters: + +- `initialScale`: number (default: 1.6) + +```typescript +{ type: 'DropIn' } +{ type: 'DropIn', initialScale: 2 } +``` + +### ExpandIn + +Visual: Scale from small to full size with directional expansion from edge. Emerging, growing outward. + +Parameters: + +- `direction`: number in degrees or keyword ('top' | 'right' | 'bottom' | 'left') (default: 90, from top) +- `distance`: UnitLengthPercentage (default: { value: 120, type: 'percentage' }) +- `initialScale`: number (default: 0) + +```typescript +{ type: 'ExpandIn' } +{ type: 'ExpandIn', direction: 'bottom', distance: { value: 100, type: 'px' }, initialScale: 0.3 } +``` + +### FlipIn + +Visual: 3D card flip rotation to reveal element. Dramatic, card-like metaphor. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'top') +- `initialRotate`: number in degrees (default: 90) +- `perspective`: number (default: 800) + +```typescript +{ type: 'FlipIn', direction: 'left' } +{ type: 'FlipIn', direction: 'top', initialRotate: 270 } +``` + +### FloatIn + +Visual: Gentle floating/drifting entrance. Ethereal, light, dreamy. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'left') + +```typescript +{ type: 'FloatIn', direction: 'bottom' } +``` + +### FoldIn + +Visual: Paper-folding 3D effect. Origami-like, creative. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'top') +- `initialRotate`: number in degrees (default: 90) +- `perspective`: number (default: 800) + +```typescript +{ type: 'FoldIn', direction: 'left' } +{ type: 'FoldIn', direction: 'top', initialRotate: 45 } +``` + +### GlideIn + +Visual: Smooth 2D glide from any angle with distance control. Clean, directional. + +Parameters: + +- `direction`: number in degrees (default: 180, from left). 0° = right, 90° = top, 180° = left, 270° = bottom +- `distance`: UnitLengthPercentage | EffectFourDirections (default: { value: 100, type: 'percentage' }) + +```typescript +{ type: 'GlideIn' } +{ type: 'GlideIn', direction: 90, distance: { value: 50, type: 'percentage' } } +``` + +### RevealIn + +Visual: Directional clip/mask reveal like a curtain opening. Theatrical. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'left') + +```typescript +{ type: 'RevealIn', direction: 'left' } +``` + +### ShapeIn + +Visual: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise. + +Parameters: + +- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' (default: 'rectangle') + +```typescript +{ type: 'ShapeIn', shape: 'circle' } +{ type: 'ShapeIn', shape: 'diamond' } +``` + +### ShuttersIn + +Visual: Venetian blind strip reveal. Segmented, rhythmic. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'right') +- `shutters`: number of strips (default: 12) +- `staggered`: boolean - animate strips sequentially (default: true) + +```typescript +{ type: 'ShuttersIn', direction: 'left', shutters: 5, staggered: true } +``` + +### SlideIn + +Visual: Straight movement from direction with clip. Clean, simple, versatile. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'left') +- `initialTranslate`: number 0-1 (default: 1) - starting offset ratio + +```typescript +{ type: 'SlideIn', direction: 'bottom' } +{ type: 'SlideIn', direction: 'left', initialTranslate: 0.2 } +``` + +### SpinIn + +Visual: Rotating entrance with spin. Dynamic, playful. + +Parameters: + +- `direction`: 'clockwise' | 'counter-clockwise' (default: 'clockwise') +- `spins`: number of rotations (default: 0.5) +- `initialScale`: number (default: 0) - starting scale + +```typescript +{ type: 'SpinIn', direction: 'clockwise', spins: 1 } +{ type: 'SpinIn', direction: 'counter-clockwise', spins: 2, initialScale: 0.5 } +``` + +### TiltIn + +Visual: 3D tilt into view. Subtle depth, elegant perspective. + +Parameters: + +- `direction`: 'left' | 'right' (default: 'left') +- `depth`: UnitLengthPercentage (default: { value: 200, type: 'px' }) +- `perspective`: number (default: 800) + +```typescript +{ type: 'TiltIn', direction: 'left' } +``` + +### TurnIn + +Visual: Corner-pivot 3D rotation. Complex, dramatic, premium. + +Parameters: + +- `direction`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' (default: 'top-left') + +```typescript +{ type: 'TurnIn', direction: 'bottom-left' } +``` + +### WinkIn + +Visual: Split-in-half reveal from center. Unique, eye-like opening. + +Parameters: + +- `direction`: 'vertical' | 'horizontal' (default: 'horizontal') + +```typescript +{ type: 'WinkIn', direction: 'vertical' } +``` + +--- + +## Intensity Values + +Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| -------- | ---------------- | ----------- | ---------- | ------------- | +| ArcIn | easing | cubicInOut | quintInOut | backOut | +| BlurIn | blur | 6px | 25px | 50px | +| BounceIn | distanceFactor | 1 | 2 | 3 | +| DropIn | initialScale | 1.2 | 1.6 | 2 | +| FlipIn | initialRotate | 45° | 90° | 270° | +| FoldIn | initialRotate | 35° | 60° | 90° | +| ExpandIn | initialScale | 0.8 | 0.6 | 0 | +| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | +| SpinIn | initialScale | 1 | 0.6 | 0 | + +Example -- "I want a subtle flip entrance": `{ type: 'FlipIn', initialRotate: 45 }` + +--- + +## Optional Parameters + +These parameters are exposed but their defaults have been tuned for good visual results and rarely need adjustment. + +### 3D Perspective + +| Preset | Parameter | Default | Range | +| ----------------- | ------------- | ------- | -------- | +| ArcIn | `perspective` | 800 | 200-2000 | +| TiltIn | `perspective` | 800 | 200-2000 | +| FoldIn | `perspective` | 800 | 200-2000 | +| FlipIn | `perspective` | 800 | 200-2000 | +| CurveIn | `perspective` | 200 | 100-1000 | +| BounceIn (center) | `perspective` | 800 | 200-2000 | + +### Depth (Z Translation) + +| Preset | Parameter | Default | Notes | +| ------- | --------- | ------- | ---------------------- | +| ArcIn | `depth` | 200px | Z translation distance | +| CurveIn | `depth` | 300px | Z translation distance | +| TiltIn | `depth` | 200px | Z translation distance | diff --git a/packages/motion-presets/rules/presets/entrance.md b/packages/motion-presets/rules/presets/entrance.md deleted file mode 100644 index 2c36f87b..00000000 --- a/packages/motion-presets/rules/presets/entrance.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: Entrance Animations -category: entrance ---- - -# Entrance Animations - -One-shot animations optimized for viewport entry, but can also be triggered by hover, click, animationEnd, and other triggers. - -## When to Use Entrance Animations - -- Element reveals on viewport entry -- First-time visibility animations -- Click/hover-triggered transitions -- Content appearing as user scrolls down - -## When NOT to Use Entrance Animations - -- Scroll-driven reveals → see [Scroll](presets-reference.md#scroll-presets) -- Continuous/looping → see [Ongoing](presets-reference.md#ongoing-presets) -- Mouse-reactive → see [Mouse](presets-reference.md#mouse-presets) - -## Available Entrance Presets - -See [Entrance Presets](presets-reference.md#entrance-presets) for full details: - -FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn - -## Entrance Quick Decision - -| Tone | Presets | -| ------------------- | ---------------------------------------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | -| Playful/Energetic | BounceIn, SpinIn | -| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | - -## Entrance Common Use Cases - -| Use Case | Recommended | -| ---------------------- | -------------------------- | -| Hero sections | ArcIn, FloatIn, RevealIn | -| Modals/Popups | FadeIn, DropIn, ExpandIn | -| List items (staggered) | FadeIn, SlideIn with delay | -| Notifications | BounceIn, DropIn | -| Cards | FlipIn, ArcIn, TiltIn | diff --git a/packages/motion-presets/rules/presets/mouse-presets.md b/packages/motion-presets/rules/presets/mouse-presets.md new file mode 100644 index 00000000..c3696fb9 --- /dev/null +++ b/packages/motion-presets/rules/presets/mouse-presets.md @@ -0,0 +1,224 @@ +--- +name: mouse-presets-reference +description: Full parameter details, examples, and intensity guide for mouse presets. Read when configuring specific mouse preset parameters or choosing intensity levels for cursor-follow and pointer-reactive effects. +category: mouse +--- + +# Mouse Presets + +All mouse preset parameters and TypeScript examples. For category overview and selection guidance, see [presets-main.md](presets-main.md). + +## Table of Contents + +- [Preset Reference](#preset-reference) +- [Intensity Values](#intensity-values) +- [Mobile Considerations](#mobile-considerations) + +All mouse presets accept an optional `inverted`: boolean parameter (default: false). + +--- + +## Preset Reference + +### AiryMouse + +Visual: Floating/airy cursor response. Ethereal, gentle drift. + +Parameters: + +- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) +- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') +- `angle`: number (default: 30) + +```typescript +{ type: 'AiryMouse' } +{ type: 'AiryMouse', angle: 10 } +``` + +### BlobMouse + +Visual: Organic blob-like deformation. Fluid shape distortion. + +Parameters: + +- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) +- `scale`: number (default: 1.4) + +```typescript +{ type: 'BlobMouse' } +{ type: 'BlobMouse', scale: 2.4 } +``` + +### BlurMouse + +Visual: Blur based on cursor distance. Focus/defocus by proximity. + +Parameters: + +- `distance`: UnitLengthPercentage (default: { value: 80, type: 'px' }) +- `angle`: number (default: 5) +- `scale`: number (default: 0.3) +- `blur`: number (default: 20) +- `perspective`: number (default: 600) + +```typescript +{ type: 'BlurMouse' } +{ type: 'BlurMouse', angle: 65, scale: 0.25 } +``` + +### BounceMouse + +Visual: Bouncy/elastic cursor following. Overshoots and wobbles. + +Parameters: + +- `distance`: UnitLengthPercentage (default: { value: 80, type: 'px' }) +- `axis`: 'horizontal' | 'vertical' | 'both' + +```typescript +{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } +``` + +### CustomMouse + +Visual: Configurable custom behavior. For advanced custom implementations. + +Parameters: + +- No preset-specific parameters + +```typescript +{ + type: 'CustomMouse'; +} +``` + +### ScaleMouse + +Visual: Scale based on cursor distance. Grows/shrinks by proximity. + +Parameters: + +- `distance`: UnitLengthPercentage (default: { value: 80, type: 'px' }) +- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') +- `scale`: number (default: 1.4) + +```typescript +{ type: 'ScaleMouse', distance: { value: 100, type: 'px' } } +``` + +### SkewMouse + +Visual: Skew distortion following cursor. Angular distortion. + +Parameters: + +- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) +- `angle`: number (default: 25) +- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') + +```typescript +{ type: 'SkewMouse' } +{ type: 'SkewMouse', angle: 45 } +``` + +### SpinMouse + +Visual: Rotation following mouse angle. Element spins based on cursor position. + +Parameters: + +- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') + +```typescript +{ type: 'SpinMouse' } +{ type: 'SpinMouse', axis: 'both' } +``` + +### SwivelMouse + +Visual: Pivot-axis rotation following cursor. Gyroscope-like rotation. + +Parameters: + +- `angle`: number (default: 5) +- `perspective`: number (default: 800) +- `pivotAxis`: 'top' | 'bottom' | 'right' | 'left' | 'center-horizontal' | 'center-vertical' (default: 'center-horizontal') + +```typescript +{ type: 'SwivelMouse' } +{ type: 'SwivelMouse', angle: 25, perspective: 1000 } +``` + +### Tilt3DMouse + +Visual: Element tilts toward cursor in 3D, like angling a card. Premium, interactive. + +Parameters: + +- `angle`: number (default: 5) +- `perspective`: number (default: 800) + +```typescript +{ type: 'Tilt3DMouse' } +{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } +{ type: 'Tilt3DMouse', angle: 85, perspective: 200 } +``` + +### Track3DMouse + +Visual: Combined translation + 3D rotation following mouse. Complex, immersive. + +Parameters: + +- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) +- `angle`: number (default: 5) +- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') +- `perspective`: number (default: 800) + +```typescript +{ type: 'Track3DMouse', distance: { value: 100, type: 'px' }, axis: 'both' } +{ type: 'Track3DMouse', distance: { value: 50, type: 'px' }, angle: 25, perspective: 1000 } +``` + +### TrackMouse + +Visual: Element follows cursor position. Floating, parallax-like. + +Parameters: + +- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) +- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') + +```typescript +{ type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } +{ type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'horizontal' } +``` + +--- + +## Intensity Values + +Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. + +| Preset | Parameter(s) | Subtle/Soft | Medium | Dramatic/Hard | +| ----------------- | ------------------ | ----------- | -------- | ------------- | +| AiryMouse | angle | 10° | 50° | 85° | +| BlobMouse | scale | 1.2 | 1.6 | 2.4 | +| BlurMouse | angle, scale | 0°, 1 | 25°, 0.7 | 65°, 0.25 | +| ScaleMouse (down) | scale | 0.85 | 0.5 | 0 | +| ScaleMouse (up) | scale | 1.2 | 1.6 | 2.4 | +| SkewMouse | angle | 10° | 20° | 45° | +| SwivelMouse | angle, perspective | 25°, 1000 | 50°, 700 | 85°, 300 | +| Tilt3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 200 | +| Track3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 333 | + +--- + +## Mobile Considerations + +Mouse effects may behave differently on touch devices. Options: + +1. Do nothing (static on mobile) +2. Use entrance animation instead +3. Use device orientation (advanced) diff --git a/packages/motion-presets/rules/presets/mouse.md b/packages/motion-presets/rules/presets/mouse.md deleted file mode 100644 index febddf03..00000000 --- a/packages/motion-presets/rules/presets/mouse.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -name: Mouse Animations -category: mouse ---- - -# Mouse Animations - -Animations that respond to cursor position. May behave differently on mobile. - -## When to Use Mouse Animations - -- Interactive cards/products (tilt effect) -- Parallax depth with cursor -- Hero section interactivity -- Playful/game-like interfaces - -## When NOT to Use Mouse Animations - -- Accessibility-critical interfaces -- Essential functionality (never rely on mouse for core features) -- Multiple simultaneous effects on many elements - -## Available Mouse Presets - -See [Mouse Presets](presets-reference.md#mouse-presets) for full details: - -AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse - -## Mouse Quick Decision - -| Tone | Presets | -| -------------------- | ------------------------------------------ | -| Professional/Premium | Tilt3DMouse (soft), TrackMouse, ScaleMouse | -| Playful/Fun | BounceMouse, BlobMouse, AiryMouse | -| Game-like/Dynamic | SpinMouse, Track3DMouse, SkewMouse | - -## Mouse Common Use Cases - -| Use Case | Recommended | -| ---------------------- | ----------------------------------- | -| Product cards | Tilt3DMouse, ScaleMouse | -| Hero depth layers | TrackMouse with different distances | -| Interactive portfolios | Tilt3DMouse, Track3DMouse | -| Playful interfaces | BounceMouse, BlobMouse | - -## Mobile Considerations - -Mouse animations may behave differently on touch devices. Options: - -1. Do nothing (static on mobile) -2. Use entrance animation instead -3. Use device orientation (advanced) diff --git a/packages/motion-presets/rules/presets/ongoing-presets.md b/packages/motion-presets/rules/presets/ongoing-presets.md new file mode 100644 index 00000000..f76ccc79 --- /dev/null +++ b/packages/motion-presets/rules/presets/ongoing-presets.md @@ -0,0 +1,222 @@ +--- +name: ongoing-presets-reference +description: Full parameter details, examples, and intensity guide for ongoing presets. Read when configuring specific ongoing preset parameters or choosing intensity levels for looping and continuous animations. +category: ongoing +--- + +# Ongoing Presets + +All ongoing preset parameters and TypeScript examples. For category overview and selection guidance, see [presets-main.md](presets-main.md). + +## Table of Contents + +- [Preset Reference](#preset-reference) +- [Intensity Values](#intensity-values) + +--- + +## Preset Reference + +### Bounce + +Visual: Vertical bouncing motion. Playful, energetic. + +Parameters: + +- `intensity`: number 0-1 (default: 0) + +```typescript +{ type: 'Bounce' } +{ type: 'Bounce', intensity: 0.5 } +``` + +### Breathe + +Visual: Slow scale in/out like breathing. Calm, organic, meditative. + +Parameters: + +- `direction`: 'vertical' | 'horizontal' | 'center' (default: 'vertical') +- `distance`: UnitLengthPercentage (default: { value: 25, type: 'px' }) +- `perspective`: number (default: 800) + +```typescript +{ type: 'Breathe', direction: 'center' } +{ type: 'Breathe', direction: 'center', distance: { value: 10, type: 'percentage' } } +``` + +### Cross + +Visual: X-pattern diagonal movement. Unique geometric motion. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' (default: 'right') + +```typescript +{ type: 'Cross', direction: 'top-left' } +``` + +### DVD + +Visual: Corner-to-corner bounce (DVD screensaver). Nostalgic, retro. + +Parameters: + +- No preset-specific parameters + +```typescript +{ + type: 'DVD'; +} +``` + +### Flash + +Visual: Opacity pulsing/blinking. Attention, warning indicator. + +Parameters: + +- No preset-specific parameters + +```typescript +{ + type: 'Flash'; +} +``` + +### Flip + +Visual: Periodic 180° flips. Card-like rotation showing front/back. + +Parameters: + +- `direction`: 'vertical' | 'horizontal' (default: 'horizontal') +- `perspective`: number (default: 800) + +```typescript +{ type: 'Flip', direction: 'horizontal' } +``` + +### Fold + +Visual: 3D folding motion. Paper-like folding and unfolding. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'top') +- `angle`: number in degrees (default: 15) + +```typescript +{ type: 'Fold', direction: 'left' } +{ type: 'Fold', direction: 'top', angle: 45 } +``` + +### Jello + +Visual: Wobbly elastic deformation. Jiggly, bouncy distortion. + +Parameters: + +- `intensity`: number 0-1 (default: 0.25) + +```typescript +{ type: 'Jello' } +{ type: 'Jello', intensity: 1 } +``` + +### Poke + +Visual: Quick scale bump like being tapped. Brief attention "boop". + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'right') +- `intensity`: number 0-1 (default: 0.5) + +```typescript +{ type: 'Poke', direction: 'top' } +{ type: 'Poke', direction: 'right', intensity: 1 } +``` + +### Pulse + +Visual: Gentle scale oscillation, heartbeat-like rhythm. Subtle, universal. + +Parameters: + +- `intensity`: number 0-1 (default: 0) + +```typescript +{ type: 'Pulse' } +{ type: 'Pulse', intensity: 0.5 } +``` + +### Rubber + +Visual: Elastic stretch effect. Springy stretching and snapping. + +Parameters: + +- `intensity`: number 0-1 (default: 0.5) + +```typescript +{ type: 'Rubber' } +{ type: 'Rubber', intensity: 1 } +``` + +### Spin + +Visual: Continuous rotation around center. Mechanical, precise. + +Parameters: + +- `direction`: 'clockwise' | 'counter-clockwise' (default: 'clockwise') + +```typescript +{ type: 'Spin', direction: 'clockwise' } +``` + +### Swing + +Visual: Rotation oscillation like a pendulum. Back and forth rhythmic. + +Parameters: + +- `swing`: number in degrees (default: 20) +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'top') + +```typescript +{ type: 'Swing' } +{ type: 'Swing', swing: 60 } +``` + +### Wiggle + +Visual: Horizontal shake/wiggle. Side-to-side for attention. + +Parameters: + +- `intensity`: number 0-1 (default: 0.5) + +```typescript +{ type: 'Wiggle' } +{ type: 'Wiggle', intensity: 1 } +``` + +--- + +## Intensity Values + +Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| ------ | --------- | ----------- | ------ | ------------- | +| Bounce | intensity | 0 | 0.5 | 1 | +| Fold | angle | 15° | 30° | 45° | +| Jello | intensity | 0 | 0.33 | 1 | +| Poke | intensity | 0 | 0.33 | 1 | +| Pulse | intensity | 0 | 0.5 | 1 | +| Rubber | intensity | 0 | 0.5 | 1 | +| Swing | swing | 20° | 40° | 60° | +| Wiggle | intensity | 0 | 0.33 | 1 | diff --git a/packages/motion-presets/rules/presets/ongoing.md b/packages/motion-presets/rules/presets/ongoing.md deleted file mode 100644 index 269fb863..00000000 --- a/packages/motion-presets/rules/presets/ongoing.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: Ongoing Animations -category: ongoing ---- - -# Ongoing Animations - -Continuous looping animations that run indefinitely. - -## When to Use Ongoing Animations - -- Loading/processing indicators -- Status indicators (live, active, recording) -- Attention-drawing elements (notifications, CTAs) -- Decorative ambient motion - -## When NOT to Use Ongoing Animations - -- Multiple simultaneous animations (visual chaos) -- Content that needs to be read -- One-time reveals → see [Entrance](presets-reference.md#entrance-presets) - -## Available Ongoing Presets - -See [Ongoing Presets](presets-reference.md#ongoing-presets) for full details: - -Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle - -## Ongoing Quick Decision - -| Tone | Presets | -| -------------------- | ----------------------------------- | -| Subtle/Professional | Pulse (soft), Breathe, Flash (soft) | -| Playful/Energetic | Bounce, Wiggle, Jello, DVD | -| Mechanical/Technical | Spin, Flip, Fold | -| Attention-grabbing | Flash, Bounce, Pulse (hard), Poke | - -## Ongoing Common Use Cases - -| Use Case | Recommended | -| ------------------ | --------------------- | -| Loading spinner | Spin | -| Status indicator | Pulse, Breathe | -| Notification badge | Bounce, Pulse, Poke | -| CTA emphasis | Pulse, Bounce | -| Character/Mascot | Bounce, Wiggle, Jello | diff --git a/packages/motion-presets/rules/presets/presets-main.md b/packages/motion-presets/rules/presets/presets-main.md new file mode 100644 index 00000000..475df038 --- /dev/null +++ b/packages/motion-presets/rules/presets/presets-main.md @@ -0,0 +1,332 @@ +--- +name: motion-presets-main-reference +description: Entry point for selecting and configuring Interact motion presets. Read when the user asks about motion animations, presets, effects, entrance/scroll/ongoing/mouse animations, or interaction design. +--- + +# Motion Presets Reference + +## Table of Contents + +- [Terminology](#terminology) +- [Decision Flow](#decision-flow) +- [Preset Categories](#preset-categories) +- [Parameter Standards](#parameter-standards) +- [Selection Tables](#selection-tables) +- [Combining Effects](#combining-effects) +- [Accessibility](#accessibility) + +## Terminology + +| Term | Meaning | +| ------------- | --------------------------------------------------------------------------------------- | +| **Effect** | Interact's term for an operation applied to an element (animation, custom effect, etc.) | +| **Preset** | A pre-built, named effect configuration from this library (e.g., `FadeIn`, `BounceIn`) | +| **Animation** | The actual visual motion that runs in the browser (CSS or WAAPI) | + +A preset is a named effect. "Preset" is used when talking about selection and configuration; "effect" when talking about the Interact runtime; "animation" when referring to the visual motion or CSS/WAAPI mechanism. + +## Decision Flow + +1. **Select Category** - What kind of effect? (entrance, scroll, ongoing, mouse) +2. **Select Preset** - Which visual effect matches the intent? +3. **Configure Parameters** - Customize direction, intensity, timing, etc. + +### Quick Category Lookup + +| User Intent | Category | Notes | +| -------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- | +| "animate when element enters viewport", "reveal on scroll into view" | entrance | Optimized for `viewEnter`; also works with hover, click, animationEnd | +| "animate based on scroll position", "parallax", "scroll-driven" | scroll | Animation progress tied to element's position in the viewport | +| "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely until stopped | +| "react to mouse", "follow cursor", "tilt on hover" | mouse | Real-time response to cursor position; may behave differently on mobile | + +--- + +## Preset Categories + +### Entrance + +One-shot animations optimized for viewport entry, but can also be triggered by hover, click, animationEnd, and other triggers. + +**When to use:** Element reveals on viewport entry, first-time visibility animations, click/hover-triggered transitions + +**When NOT to use:** Scroll-driven reveals → use scroll | Continuous/looping → use ongoing | Mouse-reactive → use mouse + +**Available presets:** FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn + +| Tone | Presets | +| ------------------- | ---------------------------------------- | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | +| Playful/Energetic | BounceIn, SpinIn | +| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | + +For full parameter details and examples, see [entrance-presets.md](entrance-presets.md). + +### Scroll + +Animations whose progress is tied to a ViewTimeline -- the element's position in the viewport. + +**When to use:** Progressive content reveals on scroll, parallax depth effects, storytelling tied to scroll progress, de-emphasizing passed content + +**When NOT to use:** One-time entrance → use entrance (more performant) | Continuous loops → use ongoing + +**Available presets:** ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll + +**Scroll range modes:** + +- `'in'`: animation ends at the element's idle state (element animates in as it enters) +- `'out'`: animation starts from the element's idle state (element animates out as it exits) +- `'continuous'`: animation passes through the idle state (animates across the full scroll range) + +| Effect Type | Presets | +| ----------- | -------------------------------------------------- | +| Opacity | FadeScroll, BlurScroll | +| Movement | ParallaxScroll, MoveScroll, PanScroll, SlideScroll | +| Scale | GrowScroll, ShrinkScroll | +| 3D Rotation | ArcScroll, FlipScroll, TiltScroll, TurnScroll | +| Reveal/Mask | RevealScroll, ShapeScroll, ShuttersScroll | + +For full parameter details and examples, see [scroll-presets.md](scroll-presets.md). + +### Ongoing + +Continuous looping animations that run indefinitely. + +**When to use:** Loading/processing indicators, status indicators (live, active, recording), attention-drawing elements (notifications, CTAs), decorative ambient motion + +**When NOT to use:** Multiple simultaneous effects (visual chaos) | Content that needs to be read | One-time reveals → use entrance + +**Available presets:** Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle + +| Tone | Presets | +| -------------------- | --------------------------------------- | +| Subtle/Professional | Pulse (subtle), Breathe, Flash (subtle) | +| Playful/Energetic | Bounce, Wiggle, Jello, DVD | +| Mechanical/Technical | Spin, Flip, Fold | +| Attention-grabbing | Flash, Bounce, Pulse (hard), Poke | + +For full parameter details and examples, see [ongoing-presets.md](ongoing-presets.md). + +### Mouse + +Effects that respond to cursor position. May behave differently on mobile. + +**When to use:** Interactive cards/products (tilt effect), parallax depth with cursor, hero section interactivity, playful/game-like interfaces + +**When NOT to use:** Accessibility-critical interfaces | Essential functionality (never rely on mouse for core features) + +**Available presets:** AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse + +| Tone | Presets | +| -------------------- | -------------------------------------------- | +| Professional/Premium | Tilt3DMouse (subtle), TrackMouse, ScaleMouse | +| Playful/Fun | BounceMouse, BlobMouse, AiryMouse | +| Game-like/Dynamic | SpinMouse, Track3DMouse, SkewMouse | + +For full parameter details and examples, see [mouse-presets.md](mouse-presets.md). + +--- + +## Parameter Standards + +### Effect Options (Not Preset Parameters) + +These are set on the effect configuration level, not on the preset itself: + +- `duration`: Animation duration in ms (entrance, ongoing) +- `delay`: Animation delay in ms (entrance, ongoing) +- `easing`: Easing function +- `iterations`: Number of iterations +- `alternate`: Alternate direction on each iteration +- `fill`: Animation fill mode +- `reversed`: Reverse the animation + +**Scroll-specific effect options:** + +- `rangeStart` / `rangeEnd`: `RangeOffset` controlling when the scroll animation starts/ends +- `transitionDuration` / `transitionDelay` / `transitionEasing`: Transition smoothing + +### Overloaded Parameter Names + +The `direction` parameter accepts different values depending on the preset: + +| Meaning | Accepted Values | Presets | +| ------------------ | ------------------------------------------------------ | -------------------------------- | +| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | +| Cardinal + center | 'top', 'right', 'bottom', 'left', 'center' | BounceIn | +| Corner direction | 'top-left', 'top-right', 'bottom-left', 'bottom-right' | TurnIn | +| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | + +### Using Units + +Interact supports both a CSSUnitValue-style object (e.g., `distance: { value: 120, type: 'px' }`, mapped to the internal type `UnitLengthPercentage`) and flat string values (e.g., `distance: '120px'`). + +Prefer the object notation. In any case, be consistent within a configuration -- use one format, not both. + +### Coordinate System + +For angle-based parameters: + +- **0°** = right (east) +- **90°** = top (north) +- **180°** = left (west) +- **270°** = bottom (south) + +### Distance Units + +Supported unit types: `px`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax`, `percentage` + +```typescript +distance: { value: 120, type: 'px' } // pixels +distance: { value: 50, type: 'percentage' } // percentage +distance: { value: 10, type: 'vh' } // viewport height +``` + +### CSS Custom Properties + +The library uses these CSS custom properties for runtime control: + +- `--motion-rotate`: Element rotation (used by SpinIn and other rotation presets) + +### Trigger and Effect Binding + +In the simplest case, a trigger and its effect are bound to the same element. However, an effect on one element can also be triggered by another element (e.g., hovering a button triggers a FadeIn on a sibling panel). + +--- + +## Selection Tables + +### By Tone + +| Tone | Entrance | Scroll | Ongoing | Mouse | +| ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | +| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | +| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | +| Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | +| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | + +### By Use Case + +| Use Case | Recommended Presets | +| ---------------------- | ---------------------------------------------- | +| Hero sections | ArcIn, FloatIn, RevealIn | +| Modals/Popups | FadeIn, DropIn, ExpandIn, SlideIn | +| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | +| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | +| Notifications/Badges | BounceIn, DropIn + Pulse | +| CTAs/Buttons | BounceIn, ExpandIn + Pulse | +| Loading indicators | Spin, Pulse | +| Product images | Tilt3DMouse, ScaleMouse | +| Background depth | ParallaxScroll, TrackMouse (layered) | + +### Cross-Category Parallels + +Effects with similar visual results across categories: + +| Entrance | Scroll | Ongoing | Mouse | +| -------- | -------------- | ------- | ----------- | +| FadeIn | FadeScroll | Flash | - | +| ArcIn | ArcScroll | - | - | +| SpinIn | SpinScroll | Spin | SpinMouse | +| BounceIn | - | Bounce | BounceMouse | +| TiltIn | TiltScroll | - | Tilt3DMouse | +| FlipIn | FlipScroll | Flip | - | +| ExpandIn | GrowScroll | Pulse | ScaleMouse | +| SlideIn | SlideScroll | - | TrackMouse | +| BlurIn | BlurScroll | - | BlurMouse | +| RevealIn | RevealScroll | - | - | +| - | ParallaxScroll | - | TrackMouse | + +--- + +## Combining Effects + +1. Avoid mixing multiple effects on the same element at the same time when possible +2. Never combine effects that affect the same CSS properties (e.g., two effects both using `transform`) +3. When combining is necessary, effect order matters -- later effects may override earlier ones +4. If possible, use nested containers to separate effects that would conflict -- place each effect on a separate wrapper element. Note: here also order matters + +### Common Patterns + +**Card reveal on scroll:** + +```typescript +{ type: 'FadeScroll', range: 'in' } +``` + +**Interactive product card (nested containers):** + +```typescript +// Outer container - entrance +{ type: 'FadeIn' } +// Inner container - mouse interaction +{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } +``` + +**Notification badge:** + +```typescript +{ type: 'BounceIn', direction: 'top', distanceFactor: 1 } +{ type: 'Pulse', intensity: 0.5 } +``` + +**Loading indicator:** + +```typescript +{ type: 'Spin', direction: 'clockwise' } +``` + +--- + +## Accessibility + +### Host vs Preset Responsibility + +The presets generally provide animations; the host platform decides when/whether to apply them. + +Interact supports `conditions` in the config for handling reduced motion. Define a media condition for `(prefers-reduced-motion: reduce)` and use it to swap high-risk presets for safer alternatives (e.g., SpinIn → FadeIn, BounceIn → FadeIn). Conditions can be applied per-interaction or per-effect, and automatically re-evaluate when the user's preference changes. + +If it is known that the host handles accessibility globally (e.g., disabling all animations on `(prefers-reduced-motion: reduce)`), presets don't need to address it separately. + +### Preset Risk Levels + +_Note:_ this section should be confirmed by an a11y expert + +**High risk** (vestibular triggers, seizure risk if motion is fast and repetitive): + +- Spinning: SpinIn, Spin, SpinScroll, SpinMouse, Spin3dScroll +- Bouncing: BounceIn, Bounce, BounceMouse +- 3D rotations: ArcIn, FlipIn, ArcScroll, FlipScroll, Tilt3DMouse +- Continuous motion: Flash, DVD, Jello, Wiggle + +**Medium risk** (strong motion, may affect some users): + +- TurnIn +- ParallaxScroll at high speed values + +**Low risk / safe** (opacity/blur changes, minimal spatial movement): + +- FadeIn, FadeScroll, BlurIn, BlurScroll +- SlideIn (subtle), GlideIn (subtle) +- Pulse (subtle), Breathe + +### Reduced Motion Fallbacks + +| Original | Fallback | +| --------------------------------- | ------------------------- | +| BounceIn, SpinIn | FadeIn | +| ArcIn, FlipIn, TurnIn | FadeIn | +| Spin, Bounce, Wiggle | Stop or subtle Pulse | +| Flash | Reduce frequency (<3/sec) | +| ParallaxScroll | Static position | +| ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | +| All mouse presets | Static state | + +### LLM Guidance Principles + +1. **Do not limit creativity by default** -- generate what the user asks for +2. **Apply constraints only when explicitly requested** -- keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" +3. **High-risk presets are informational, not blockers** -- optionally note vestibular concerns in response +4. **Mouse presets may behave differently on mobile** -- note this as context, not a restriction +5. **Duration guidelines are suggestions** -- functional UI <500ms, decorative up to 1200ms, hero up to 2000ms diff --git a/packages/motion-presets/rules/presets/presets-reference.md b/packages/motion-presets/rules/presets/presets-reference.md deleted file mode 100644 index c750c0d6..00000000 --- a/packages/motion-presets/rules/presets/presets-reference.md +++ /dev/null @@ -1,1295 +0,0 @@ ---- -name: Motion Presets Reference -description: Comprehensive LLM reference for Interact motion presets ---- - -# Motion Presets Reference - -## 1. Intro - -This document is a comprehensive reference for Interact motion presets. Use it to select and configure animations based on user requirements. - -### Decision Flow - -1. **Select Category** - What kind of animation? (entrance, scroll, ongoing, mouse) -2. **Select Preset** - Which visual effect matches the intent? -3. **Configure Parameters** - Customize direction, intensity, timing, etc. - -### Quick Category Lookup - -| User Intent | Category | Notes | -| -------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- | -| "animate when element enters viewport", "reveal on scroll into view" | entrance | Optimized for `viewEnter`; also works with hover, click, animationEnd | -| "animate based on scroll position", "parallax", "scroll-driven" | scroll | Animation progress tied to element's position in the viewport | -| "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely until stopped | -| "react to mouse", "follow cursor", "tilt on hover" | mouse | Real-time response to cursor position; may behave differently on mobile | - ---- - -## 2. Preset Categories - -### Entrance - -One-shot animations optimized for viewport entry, but can also be triggered by hover, click, animationEnd, and other triggers. - -**When to use:** - -- Element reveals on viewport entry -- First-time visibility animations -- Click/hover-triggered transitions - -**When NOT to use:** - -- Scroll-driven reveals → use scroll -- Continuous/looping → use ongoing -- Mouse-reactive → use mouse - -**Available presets:** FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn - -### Scroll - -Animations whose progress is tied to a ViewTimeline - the element's position in the viewport. - -**When to use:** - -- Progressive content reveals on scroll -- Parallax depth effects -- Storytelling tied to scroll progress -- De-emphasizing passed content - -**When NOT to use:** - -- One-time entrance → use entrance (more performant) -- Continuous loops → use ongoing - -**Available presets:** ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll - -### Ongoing - -Continuous looping animations that run indefinitely. - -**When to use:** - -- Loading/processing indicators -- Status indicators (live, active, recording) -- Attention-drawing elements (notifications, CTAs) -- Decorative ambient motion - -**When NOT to use:** - -- Multiple simultaneous animations (visual chaos) -- Content that needs to be read -- One-time reveals → use entrance - -**Available presets:** Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle - -### Mouse - -Animations that respond to cursor position. May behave differently on mobile. - -**When to use:** - -- Interactive cards/products (tilt effect) -- Parallax depth with cursor -- Hero section interactivity -- Playful/game-like interfaces - -**When NOT to use:** - -- Accessibility-critical interfaces -- Essential functionality (never rely on mouse for core features) - -**Available presets:** AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse - ---- - -## 3. Parameter Standards - -### Animation Options (Not Preset Parameters) - -These are set on the animation/effect configuration level, not on the preset itself: - -- `duration`: Animation duration in ms (entrance, ongoing) -- `delay`: Animation delay in ms (entrance, ongoing) -- `easing`: Easing function -- `iterations`: Number of iterations -- `alternate`: Alternate direction on each iteration -- `fill`: Animation fill mode -- `reversed`: Reverse the animation - -**Scroll-specific animation options:** - -- `rangeStart` / `rangeEnd`: `RangeOffset` controlling when the scroll animation starts/ends -- `transitionDuration` / `transitionDelay` / `transitionEasing`: Transition smoothing - -### Overloaded Parameter Names - -The `direction` parameter accepts different values depending on the preset: - -| Meaning | Accepted Values | Presets | -| ------------------ | ------------------------------------------------------------------ | -------------------------------- | -| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | -| Extended cardinal | + 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center' | BounceIn, ShapeIn | -| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | - -### Coordinate System - -For angle-based parameters: - -- **0°** = right (east) -- **90°** = top (north) -- **180°** = left (west) -- **270°** = bottom (south) - -### Distance Units - -Distance parameters use the `UnitLengthPercentage` type: - -```typescript -distance: { value: 120, type: 'px' } // pixels -distance: { value: 50, type: 'percentage' } // percentage -distance: { value: 10, type: 'vh' } // viewport height -``` - -Supported unit types: `px`, `em`, `rem`, `vh`, `vw`, `vmin`, `vmax`, `percentage` - ---- - -## 4. Presets - -### Entrance Presets - -#### FadeIn - -Visual: Element transitions from invisible to visible. Simple opacity change, no movement. - -Parameters: - -- No preset-specific parameters - -```typescript -{ - type: 'FadeIn'; -} -``` - -#### ArcIn - -Visual: Element swings in along a curved 3D path, like a door opening. Dramatic, cinematic. - -Parameters: - -- `direction`: top | right | bottom | left (default: left) -- `depth`: UnitLengthPercentage (default: 300px) - Z translation distance -- `perspective`: number (default: 800) - -```typescript -{ type: 'ArcIn', direction: 'bottom' } -{ type: 'ArcIn', direction: 'left', depth: { value: 500, type: 'px' } } -``` - -#### BlurIn - -Visual: Element transitions from blurry to sharp focus while fading in. Soft, dreamy. - -Parameters: - -- `blur`: number in px (default: 25) - -```typescript -{ type: 'BlurIn' } -{ type: 'BlurIn', blur: 6 } // Subtle -{ type: 'BlurIn', blur: 50 } // Dramatic -``` - -#### BounceIn - -Visual: Element bounces into view with spring physics. Playful, attention-grabbing. - -Parameters: - -- `direction`: top | right | bottom | left | center (default: top) -- `distanceFactor`: number (default: 1) -- `perspective`: number (default: 800) - only used with center direction - -```typescript -{ type: 'BounceIn' } -{ type: 'BounceIn', direction: 'center', distanceFactor: 2 } -``` - -#### CurveIn - -Visual: Curved 3D motion path entry. Cinematic arc trajectory. - -Parameters: - -- `direction`: 'left' | 'right' | 'pseudoLeft' | 'pseudoRight' -- `depth`: UnitLengthPercentage (default: 900px) -- `perspective`: number (default: 200) - -```typescript -{ type: 'CurveIn', direction: 'left' } -``` - -#### DropIn - -Visual: Falls from above with subtle scale on landing. Gravity-like, natural. - -Parameters: - -- `initialScale`: number (default: 1.6) - -```typescript -{ type: 'DropIn' } -{ type: 'DropIn', initialScale: 2 } // More dramatic -``` - -#### FlipIn - -Visual: 3D card flip rotation to reveal element. Dramatic, card-like metaphor. - -Parameters: - -- `direction`: top | right | bottom | left -- `initialRotate`: number in degrees (default: 90) -- `perspective`: number (default: 800) - -```typescript -{ type: 'FlipIn', direction: 'left' } -{ type: 'FlipIn', direction: 'top', initialRotate: 270 } // Dramatic flip -``` - -#### FloatIn - -Visual: Gentle floating/drifting entrance. Ethereal, light, dreamy. - -Parameters: - -- `direction`: top | right | bottom | left - -```typescript -{ type: 'FloatIn', direction: 'bottom' } -``` - -#### FoldIn - -Visual: Paper-folding 3D effect. Origami-like, creative. - -Parameters: - -- `direction`: top | right | bottom | left -- `initialRotate`: number in degrees (default: 60) -- `perspective`: number (default: 800) - -```typescript -{ type: 'FoldIn', direction: 'left' } -{ type: 'FoldIn', direction: 'top', initialRotate: 90 } -``` - -#### GlideIn - -Visual: Smooth 2D glide from any angle with distance control. Clean, directional. - -Parameters: - -- `direction`: number in degrees (default: 270, from left). 0° = right, 90° = top, 180° = left, 270° = bottom -- `distance`: UnitLengthPercentage | EffectFourDirections - -```typescript -{ type: 'GlideIn' } // From left (default angle 270) -{ type: 'GlideIn', direction: 90, distance: { value: 50, type: 'percentage' } } // From top -``` - -#### ExpandIn - -Visual: Scale from small to full size with directional expansion from edge. Emerging, growing outward. - -Parameters: - -- `direction`: number in degrees or keyword (top | right | bottom | left). Default: 90 (from top) -- `distance`: UnitLengthPercentage (default: { value: 120, unit: 'percentage' }) -- `initialScale`: number (default: 0) - -```typescript -{ type: 'ExpandIn' } -{ type: 'ExpandIn', direction: 'bottom', distance: { value: 100, type: 'px' }, initialScale: 0.3 } -``` - -#### RevealIn - -Visual: Directional clip/mask reveal like a curtain opening. Theatrical. - -Parameters: - -- `direction`: top | right | bottom | left - -```typescript -{ type: 'RevealIn', direction: 'left' } -``` - -#### ShapeIn - -Visual: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise. - -Parameters: - -- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' - -```typescript -{ type: 'ShapeIn', shape: 'circle' } -{ type: 'ShapeIn', shape: 'diamond' } -``` - -#### ShuttersIn - -Visual: Venetian blind strip reveal. Segmented, rhythmic. - -Parameters: - -- `direction`: top | right | bottom | left -- `shutters`: number of strips -- `staggered`: boolean (animate strips sequentially) - -```typescript -{ type: 'ShuttersIn', direction: 'left', shutters: 5, staggered: true } -``` - -#### SlideIn - -Visual: Straight movement from direction with clip. Clean, simple, versatile. - -Parameters: - -- `direction`: top | right | bottom | left -- `initialTranslate`: number 0-1 (default: 1) - starting offset ratio - -```typescript -{ type: 'SlideIn', direction: 'bottom' } -{ type: 'SlideIn', direction: 'left', initialTranslate: 0.2 } // Subtle slide -``` - -#### SpinIn - -Visual: Rotating entrance with spin. Dynamic, playful. - -Parameters: - -- `direction`: 'clockwise' | 'counter-clockwise' -- `spins`: number of rotations -- `initialScale`: number (default: 0) - starting scale - -```typescript -{ type: 'SpinIn', direction: 'clockwise', spins: 1 } -{ type: 'SpinIn', direction: 'counter-clockwise', spins: 2, initialScale: 0.5 } -``` - -#### TiltIn - -Visual: 3D tilt into view. Subtle depth, elegant perspective. - -Parameters: - -- `direction`: 'left' | 'right' -- `depth`: UnitLengthPercentage (default: 200px) -- `perspective`: number (default: 800) - -```typescript -{ type: 'TiltIn', direction: 'left' } -``` - -#### TurnIn - -Visual: Corner-pivot 3D rotation. Complex, dramatic, premium. - -Parameters: - -- `direction`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' - -```typescript -{ type: 'TurnIn', direction: 'bottom-left' } -``` - -#### WinkIn - -Visual: Split-in-half reveal from center. Unique, eye-like opening. - -Parameters: - -- `direction`: 'vertical' | 'horizontal' - -```typescript -{ type: 'WinkIn', direction: 'vertical' } -``` - ---- - -### Scroll Presets - -All scroll presets accept a `range` parameter: `'in'` | `'out'` | `'continuous'` - -#### ArcScroll - -Visual: 3D arc rotation as user scrolls. Dramatic, cinematic. - -Parameters: - -- `direction`: 'vertical' | 'horizontal' -- `range`: in | out | continuous -- `perspective`: number - -```typescript -{ type: 'ArcScroll', direction: 'vertical' } -{ type: 'ArcScroll', direction: 'horizontal', range: 'in' } -``` - -#### BlurScroll - -Visual: Blur/unblur effect controlled by scroll. Focus transitions. - -Parameters: - -- `range`: in | out | continuous -- `blur`: number in px (default: 25) - -```typescript -{ type: 'BlurScroll', range: 'in' } -{ type: 'BlurScroll', range: 'out', blur: 50 } -``` - -#### FadeScroll - -Visual: Opacity transition tied to scroll. Fade in on enter, out on exit. - -Parameters: - -- `range`: in | out -- `opacity`: number 0-1 - -```typescript -{ type: 'FadeScroll', range: 'in' } -{ type: 'FadeScroll', range: 'out' } -``` - -#### FlipScroll - -Visual: Full 3D card flip driven by scroll. Dramatic rotation. - -Parameters: - -- `direction`: 'vertical' | 'horizontal' -- `range`: in | out | continuous -- `rotate`: number in degrees (default: 120) -- `perspective`: number (default: 800) - -```typescript -{ type: 'FlipScroll', direction: 'horizontal' } -{ type: 'FlipScroll', direction: 'vertical', range: 'in', rotate: 420 } -``` - -#### GrowScroll - -Visual: Scale up as element enters viewport. - -Parameters: - -- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center -- `range`: in | out | continuous -- `scale`: number (default: 1.7) -- `speed`: number - -```typescript -{ type: 'GrowScroll', direction: 'center' } -{ type: 'GrowScroll', direction: 'center', range: 'in', scale: 4 } -``` - -#### MoveScroll - -Visual: Translation movement on scroll in any direction. - -Parameters: - -- `angle`: 0-360 degrees (default varies). 0° = right, 90° = top, 180° = left, 270° = bottom -- `range`: in | out | continuous -- `distance`: UnitLengthPercentage (default: 400px) - -```typescript -{ type: 'MoveScroll', angle: 90, distance: { value: 100, type: 'px' } } -{ type: 'MoveScroll', angle: 0, distance: { value: 800, type: 'px' } } -``` - -#### PanScroll - -Visual: Horizontal panning tied to scroll. - -Parameters: - -- `direction`: 'left' | 'right' -- `distance`: UnitLengthPercentage -- `startFromOffScreen`: boolean -- `range`: in | out | continuous - -```typescript -{ type: 'PanScroll', direction: 'left', distance: { value: 200, type: 'px' } } -``` - -#### ParallaxScroll - -Visual: Element moves slower/faster than scroll, creating depth illusion. - -Parameters: - -- `parallaxFactor`: number (default: 0.5) - movement speed relative to scroll -- `range`: in | out | continuous - -```typescript -{ type: 'ParallaxScroll' } -{ type: 'ParallaxScroll', parallaxFactor: 0.3 } -``` - -#### RevealScroll - -Visual: Clip-based directional reveal on scroll. - -Parameters: - -- `direction`: top | right | bottom | left -- `range`: in | out | continuous - -```typescript -{ type: 'RevealScroll', direction: 'left' } -{ type: 'RevealScroll', direction: 'bottom', range: 'in' } -``` - -#### ShapeScroll - -Visual: Shape mask reveal controlled by scroll. - -Parameters: - -- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' -- `range`: in | out | continuous -- `intensity`: number 0-1 - -```typescript -{ type: 'ShapeScroll', shape: 'circle' } -{ type: 'ShapeScroll', shape: 'diamond', intensity: 0.8 } -``` - -#### ShrinkScroll - -Visual: Scale down as element exits viewport. - -Parameters: - -- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right | center -- `range`: in | out | continuous -- `scale`: number (default: 0.3) -- `speed`: number - -```typescript -{ type: 'ShrinkScroll', direction: 'center', range: 'out' } -{ type: 'ShrinkScroll', direction: 'center', scale: 0 } -``` - -#### ShuttersScroll - -Visual: Venetian blind strips revealing on scroll. - -Parameters: - -- `direction`: top | right | bottom | left -- `shutters`: number of strips -- `staggered`: boolean -- `range`: in | out | continuous - -```typescript -{ type: 'ShuttersScroll', direction: 'left', shutters: 5, staggered: true } -``` - -#### SkewPanScroll - -Visual: Panning with skew distortion effect. - -Parameters: - -- `direction`: 'left' | 'right' -- `range`: in | out | continuous -- `skew`: number in degrees (default: 17) - -```typescript -{ type: 'SkewPanScroll', direction: 'left' } -{ type: 'SkewPanScroll', direction: 'right', skew: 24 } -``` - -#### SlideScroll - -Visual: Slide movement tied to scroll position. - -Parameters: - -- `direction`: top | right | bottom | left -- `range`: in | out | continuous - -```typescript -{ type: 'SlideScroll', direction: 'bottom' } -{ type: 'SlideScroll', direction: 'left', range: 'in' } -``` - -#### Spin3dScroll - -Visual: 3D rotation around axis on scroll. - -Parameters: - -- `range`: in | out | continuous -- `rotate`: number in degrees (default: 100) -- `speed`: number -- `perspective`: number (default: 1000) - -```typescript -{ type: 'Spin3dScroll' } -{ type: 'Spin3dScroll', range: 'continuous', rotate: 200 } -``` - -#### SpinScroll - -Visual: 2D rotation driven by scroll. - -Parameters: - -- `direction`: 'clockwise' | 'counter-clockwise' -- `spins`: number of rotations -- `range`: in | out | continuous -- `scale`: number (default: 0.7) - -```typescript -{ type: 'SpinScroll', direction: 'clockwise', spins: 1 } -{ type: 'SpinScroll', direction: 'counter-clockwise', spins: 2, scale: 0.4 } -``` - -#### StretchScroll - -Visual: Stretch/squeeze deformation on scroll. - -Parameters: - -- `range`: in | out | continuous -- `stretch`: number (default: 1.5) - -```typescript -{ type: 'StretchScroll' } -{ type: 'StretchScroll', stretch: 2 } -``` - -#### TiltScroll - -Visual: 3D tilt effect as user scrolls. Subtle perspective. - -Parameters: - -- `direction`: 'left' | 'right' -- `range`: in | out | continuous -- `parallaxFactor`: number (default: 0.5) - tilt distance factor -- `perspective`: number (default: 400) - -```typescript -{ type: 'TiltScroll', direction: 'left' } -{ type: 'TiltScroll', direction: 'right', parallaxFactor: 1 } -``` - -#### TurnScroll - -Visual: Corner-pivot 3D rotation on scroll. - -Parameters: - -- `direction`: 'left' | 'right' -- `spin`: 'clockwise' | 'counter-clockwise' -- `range`: in | out | continuous -- `scale`: number (default: 1.3) -- `rotation`: number - -```typescript -{ type: 'TurnScroll', direction: 'left', spin: 'clockwise' } -{ type: 'TurnScroll', direction: 'right', spin: 'counter-clockwise', scale: 1.6 } -``` - ---- - -### Ongoing Presets - -#### Bounce - -Visual: Vertical bouncing motion. Playful, energetic. - -Parameters: - -- `intensity`: number 0-1 (default: 0) - -```typescript -{ type: 'Bounce' } -{ type: 'Bounce', intensity: 0.5 } -``` - -#### Breathe - -Visual: Slow scale in/out like breathing. Calm, organic, meditative. - -Parameters: - -- `direction`: 'vertical' | 'horizontal' | 'center' -- `distance`: UnitLengthPercentage -- `perspective`: number - -```typescript -{ type: 'Breathe', direction: 'center' } -{ type: 'Breathe', direction: 'center', distance: { value: 10, type: 'percentage' } } -``` - -#### Cross - -Visual: X-pattern diagonal movement. Unique geometric motion. - -Parameters: - -- `direction`: top | right | bottom | left | top-left | top-right | bottom-left | bottom-right - -```typescript -{ type: 'Cross', direction: 'top-left' } -``` - -#### DVD - -Visual: Corner-to-corner bounce (DVD screensaver). Nostalgic, retro. - -Parameters: - -- No preset-specific parameters - -```typescript -{ - type: 'DVD'; -} -``` - -#### Flash - -Visual: Opacity pulsing/blinking. Attention, warning indicator. - -Parameters: - -- No preset-specific parameters - -```typescript -{ - type: 'Flash'; -} -``` - -#### Flip - -Visual: Periodic 180° flips. Card-like rotation showing front/back. - -Parameters: - -- `direction`: 'vertical' | 'horizontal' -- `perspective`: number - -```typescript -{ type: 'Flip', direction: 'horizontal' } -``` - -#### Fold - -Visual: 3D folding motion. Paper-like folding and unfolding. - -Parameters: - -- `direction`: top | right | bottom | left -- `angle`: number in degrees (default: 15) - -```typescript -{ type: 'Fold', direction: 'left' } -{ type: 'Fold', direction: 'top', angle: 45 } -``` - -#### Jello - -Visual: Wobbly elastic deformation. Jiggly, bouncy distortion. - -Parameters: - -- `intensity`: number 0-1 (default: 0.25) - -```typescript -{ type: 'Jello' } -{ type: 'Jello', intensity: 1 } -``` - -#### Poke - -Visual: Quick scale bump like being tapped. Brief attention "boop". - -Parameters: - -- `direction`: top | right | bottom | left (default: 'right') -- `intensity`: number 0-1 (default: 0.5) - -```typescript -{ type: 'Poke', direction: 'top' } -{ type: 'Poke', direction: 'right', intensity: 1 } -``` - -#### Pulse - -Visual: Gentle scale oscillation, heartbeat-like rhythm. Subtle, universal. - -Parameters: - -- `intensity`: number 0-1 (default: 0) - -```typescript -{ type: 'Pulse' } -{ type: 'Pulse', intensity: 0.5 } -``` - -#### Rubber - -Visual: Elastic stretch effect. Springy stretching and snapping. - -Parameters: - -- `intensity`: number 0-1 (default: 0.5) - -```typescript -{ type: 'Rubber' } -{ type: 'Rubber', intensity: 1 } -``` - -#### Spin - -Visual: Continuous rotation around center. Mechanical, precise. - -Parameters: - -- `direction`: 'clockwise' | 'counter-clockwise' (default: clockwise) - -```typescript -{ type: 'Spin', direction: 'clockwise' } -``` - -#### Swing - -Visual: Rotation oscillation like a pendulum. Back and forth rhythmic. - -Parameters: - -- `swing`: number in degrees (default: 20) -- `direction`: top | right | bottom | left - -```typescript -{ type: 'Swing' } -{ type: 'Swing', swing: 60 } -``` - -#### Wiggle - -Visual: Horizontal shake/wiggle. Side-to-side for attention. - -Parameters: - -- `intensity`: number 0-1 (default: 0.5) - -```typescript -{ type: 'Wiggle' } -{ type: 'Wiggle', intensity: 1 } -``` - ---- - -### Mouse Presets - -All mouse presets accept an optional `inverted`: boolean parameter. - -#### AiryMouse - -Visual: Floating/airy cursor response. Ethereal, gentle drift. - -Parameters: - -- `distance`: UnitLengthPercentage -- `axis`: 'horizontal' | 'vertical' | 'both' -- `angle`: number (default: 50) - -```typescript -{ type: 'AiryMouse' } -{ type: 'AiryMouse', angle: 10 } // Subtle -``` - -#### BlobMouse - -Visual: Organic blob-like deformation. Fluid shape distortion. - -Parameters: - -- `distance`: UnitLengthPercentage -- `scale`: number (default: 1.6) - -```typescript -{ type: 'BlobMouse' } -{ type: 'BlobMouse', scale: 2.4 } -``` - -#### BlurMouse - -Visual: Blur based on cursor distance. Focus/defocus by proximity. - -Parameters: - -- `distance`: UnitLengthPercentage -- `angle`: number (default: 25) -- `scale`: number (default: 0.7) -- `blur`: number -- `perspective`: number - -```typescript -{ type: 'BlurMouse' } -{ type: 'BlurMouse', angle: 65, scale: 0.25 } -``` - -#### BounceMouse - -Visual: Bouncy/elastic cursor following. Overshoots and wobbles. - -Parameters: - -- `distance`: UnitLengthPercentage (default: 80px) -- `axis`: 'horizontal' | 'vertical' | 'both' - -```typescript -{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } -``` - -#### CustomMouse - -Visual: Configurable custom behavior. For advanced custom implementations. - -```typescript -{ - type: 'CustomMouse'; -} -``` - -#### ScaleMouse - -Visual: Scale based on cursor distance. Grows/shrinks by proximity. - -Parameters: - -- `distance`: UnitLengthPercentage -- `axis`: 'horizontal' | 'vertical' | 'both' -- `scale`: number - -```typescript -{ type: 'ScaleMouse', distance: { value: 100, type: 'px' } } -``` - -#### SkewMouse - -Visual: Skew distortion following cursor. Angular distortion. - -Parameters: - -- `distance`: UnitLengthPercentage -- `angle`: number (default: 20) -- `axis`: 'horizontal' | 'vertical' | 'both' - -```typescript -{ type: 'SkewMouse' } -{ type: 'SkewMouse', angle: 45 } -``` - -#### SpinMouse - -Visual: Rotation following mouse angle. Element spins based on cursor position. - -Parameters: - -- `axis`: 'horizontal' | 'vertical' | 'both' - -```typescript -{ type: 'SpinMouse' } -{ type: 'SpinMouse', axis: 'both' } -``` - -#### SwivelMouse - -Visual: Z-axis rotation following cursor. Gyroscope-like vertical rotation. - -Parameters: - -- `angle`: number (default: 50) -- `perspective`: number (default: 700) -- `pivotAxis`: 'top' | 'bottom' | 'right' | 'left' | 'center-horizontal' | 'center-vertical' - -```typescript -{ type: 'SwivelMouse' } -{ type: 'SwivelMouse', angle: 25, perspective: 1000 } // Subtle -``` - -#### Tilt3DMouse - -Visual: Element tilts toward cursor in 3D, like angling a card. Premium, interactive. - -Parameters: - -- `angle`: number (default: 50) -- `perspective`: number (default: 500) - -```typescript -{ type: 'Tilt3DMouse' } -{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } // Subtle professional -{ type: 'Tilt3DMouse', angle: 85, perspective: 200 } // Dramatic -``` - -#### Track3DMouse - -Visual: Combined translation + 3D rotation following mouse. Complex, immersive. - -Parameters: - -- `distance`: UnitLengthPercentage -- `angle`: number (default: 50) -- `axis`: 'horizontal' | 'vertical' | 'both' -- `perspective`: number (default: 500) - -```typescript -{ type: 'Track3DMouse', distance: { value: 100, type: 'px' }, axis: 'both' } -{ type: 'Track3DMouse', distance: { value: 50, type: 'px' }, angle: 25, perspective: 1000 } -``` - -#### TrackMouse - -Visual: Element follows cursor position. Floating, parallax-like. - -Parameters: - -- `distance`: UnitLengthPercentage (default: 250px) -- `axis`: 'horizontal' | 'vertical' | 'both' - -```typescript -{ type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } -{ type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'horizontal' } -``` - ---- - -## 5. Selection Tables - -### By Tone - -| Tone | Entrance | Scroll | Ongoing | Mouse | -| ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | -| Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | -| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | - -### By Use Case - -| Use Case | Recommended Presets | -| ---------------------- | ---------------------------------------------- | -| Hero sections | ArcIn, FloatIn, RevealIn | -| Modals/Popups | FadeIn, DropIn, ExpandIn, SlideIn | -| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | -| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | -| Notifications/Badges | BounceIn, DropIn + Pulse | -| CTAs/Buttons | BounceIn, ExpandIn + Pulse | -| Loading indicators | Spin, Pulse | -| Product images | Tilt3DMouse, ScaleMouse | -| Background depth | ParallaxScroll, TrackMouse (layered) | - -### Cross-Category Parallels - -Effects with similar visual results across categories: - -| Entrance | Scroll | Ongoing | Mouse | -| -------- | -------------- | ------- | ----------- | -| FadeIn | FadeScroll | Flash | - | -| ArcIn | ArcScroll | - | - | -| SpinIn | SpinScroll | Spin | SpinMouse | -| BounceIn | - | Bounce | BounceMouse | -| TiltIn | TiltScroll | - | Tilt3DMouse | -| FlipIn | FlipScroll | Flip | - | -| ExpandIn | GrowScroll | Pulse | ScaleMouse | -| SlideIn | SlideScroll | - | TrackMouse | -| BlurIn | BlurScroll | - | BlurMouse | -| RevealIn | RevealScroll | - | - | -| - | ParallaxScroll | - | TrackMouse | - ---- - -## 6. Combining Animations - -1. Avoid mixing multiple animations on the same element when possible -2. Never combine animations that affect the same CSS properties (e.g., two animations both using `transform`) -3. When combining is necessary, animation order matters - later animations may override earlier ones -4. If possible, use nested containers to separate animations that would conflict - place each animation on a separate wrapper element - -### Common Patterns - -**Card reveal on scroll:** - -```typescript -{ type: 'FadeScroll', range: 'in' } -``` - -**Interactive product card (nested containers):** - -```typescript -// Outer container - entrance -{ type: 'FadeIn' } -// Inner container - mouse interaction -{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } -``` - -**Notification badge:** - -```typescript -{ type: 'BounceIn', direction: 'top', distanceFactor: 1 } -{ type: 'Pulse', intensity: 0.5 } -``` - -**Loading indicator:** - -```typescript -{ type: 'Spin', direction: 'clockwise' } -``` - ---- - -## 7. Accessibility - -### Host vs Preset Responsibility - -The presets provide animations; the host platform decides when/whether to apply them. - -Interact supports `conditions` in the config for handling reduced motion. Define a media condition for `(prefers-reduced-motion: reduce)` and use it to swap high-risk presets for safer alternatives (e.g., SpinIn → FadeIn, BounceIn → FadeIn). Conditions can be applied per-interaction or per-effect, and automatically re-evaluate when the user's preference changes. - -When the host handles accessibility globally (e.g., disabling all animations), presets don't need to address it separately. - -### Preset Risk Levels - -**High risk** (vestibular triggers, seizure risk): - -- Spinning: SpinIn, Spin, SpinScroll, SpinMouse, Spin3dScroll -- Bouncing: BounceIn, Bounce, BounceMouse -- 3D rotations: ArcIn, FlipIn, ArcScroll, FlipScroll, Tilt3DMouse -- Continuous motion: Flash, DVD, Jello, Wiggle - -**Medium risk** (strong motion, may affect some users): - -- TurnIn -- ParallaxScroll at high speed values - -**Low risk / safe** (opacity/blur changes, minimal spatial movement): - -- FadeIn, FadeScroll, BlurIn, BlurScroll -- SlideIn (subtle), GlideIn (subtle) -- Pulse (subtle), Breathe - -### Reduced Motion Fallbacks - -| Original | Fallback | -| --------------------------------- | ------------------------- | -| BounceIn, SpinIn | FadeIn | -| ArcIn, FlipIn, TurnIn | FadeIn | -| Spin, Bounce, Wiggle | Stop or subtle Pulse | -| Flash | Reduce frequency (<3/sec) | -| ParallaxScroll | Static position | -| ArcScroll, FlipScroll, SpinScroll | FadeScroll or disable | -| All mouse animations | Static state | - -### LLM Guidance Principles - -1. **Do not limit creativity by default** - generate what the user asks for -2. **Apply constraints only when explicitly requested** - keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" -3. **High-risk presets are informational, not blockers** - optionally note vestibular concerns in response -4. **Mouse presets may behave differently on mobile** - note this as context, not a restriction -5. **Duration guidelines are suggestions** - functional UI <500ms, decorative up to 1200ms, hero up to 2000ms - -### Performance Notes - -- **Scroll animations run continuously**: use sparingly, test on low-end devices -- **Mouse animations calculate on every mousemove**: limit to 1-3 elements -- **3D transforms require GPU**: can cause jank on older devices -- **Prefer `transform` and `opacity`**: these are GPU-accelerated - ---- - -## 8. Intensity Value Guide - -When users ask for "soft", "subtle", "medium", or "hard"/"dramatic" effects, use these value mappings as guidance for suggesting appropriate parameter values. - -### Entrance Presets Intensity Values - -| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | -| -------- | ---------------- | ----------- | ---------- | ------------- | -| ArcIn | easing | cubicInOut | quintInOut | backOut | -| BlurIn | blur | 6px | 25px | 50px | -| BounceIn | distanceFactor | 1 | 2 | 3 | -| DropIn | initialScale | 1.2 | 1.6 | 2 | -| FlipIn | initialRotate | 45° | 90° | 270° | -| FoldIn | initialRotate | 35° | 60° | 90° | -| ExpandIn | initialScale | 0.8 | 0.6 | 0 | -| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | -| SpinIn | initialScale | 1 | 0.6 | 0 | - -### Scroll Presets Intensity Values - -| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | -| ------------- | --------- | ----------- | ------ | ------------- | -| BlurScroll | blur | 6px | 25px | 50px | -| FlipScroll | rotate | 60° | 120° | 420° | -| GrowScroll | scale | 1.2 | 1.7 | 4 | -| MoveScroll | distance | 150px | 400px | 800px | -| ShrinkScroll | scale | 0.8 | 0.3 | 0 | -| SkewPanScroll | skew | 10° | 17° | 24° | -| Spin3dScroll | rotate | 45° | 100° | 200° | -| SpinScroll | scale | 1 | 0.7 | 0.4 | -| StretchScroll | stretch | 1.2 | 1.5 | 2 | -| TiltScroll | distance | 0 | 0.5 | 1 | -| TurnScroll | scale | 1 | 1.3 | 1.6 | - -### Ongoing Presets Intensity Values - -| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | -| ------ | --------- | ----------- | ------ | ------------- | -| Bounce | intensity | 0 | 0.5 | 1 | -| Fold | angle | 15° | 30° | 45° | -| Jello | intensity | 0 | 0.33 | 1 | -| Poke | intensity | 0 | 0.33 | 1 | -| Pulse | intensity | 0 | 0.5 | 1 | -| Rubber | intensity | 0 | 0.5 | 1 | -| Swing | swing | 20° | 40° | 60° | -| Wiggle | intensity | 0 | 0.33 | 1 | - -### Mouse Presets Intensity Values - -| Preset | Parameter(s) | Subtle/Soft | Medium | Dramatic/Hard | -| ----------------- | ------------------ | ----------- | -------- | ------------- | -| AiryMouse | angle | 10° | 50° | 85° | -| BlobMouse | scale | 1.2 | 1.6 | 2.4 | -| BlurMouse | angle, scale | 0°, 1 | 25°, 0.7 | 65°, 0.25 | -| ScaleMouse (down) | scale | 0.85 | 0.5 | 0 | -| ScaleMouse (up) | scale | 1.2 | 1.6 | 2.4 | -| SkewMouse | angle | 10° | 20° | 45° | -| SwivelMouse | angle, perspective | 25°, 1000 | 50°, 700 | 85°, 300 | -| Tilt3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 200 | -| Track3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 333 | - -### Intensity Usage Example - -When a user asks: "I want a subtle flip entrance" - -Suggest: `{ type: 'FlipIn', initialRotate: 45 }` diff --git a/packages/motion-presets/rules/presets/scroll-presets.md b/packages/motion-presets/rules/presets/scroll-presets.md new file mode 100644 index 00000000..0aa247d8 --- /dev/null +++ b/packages/motion-presets/rules/presets/scroll-presets.md @@ -0,0 +1,346 @@ +--- +name: scroll-presets-reference +description: Full parameter details, examples, and intensity guide for scroll presets. Read when configuring specific scroll preset parameters or choosing intensity levels for scroll-driven animations. +category: scroll +--- + +# Scroll Presets + +All scroll preset parameters and TypeScript examples. For category overview and selection guidance, see [presets-main.md](presets-main.md). + +## Table of Contents + +- [Preset Reference](#preset-reference) +- [Intensity Values](#intensity-values) +- [Optional Parameters](#optional-parameters) + +All scroll presets accept a `range` parameter: + +- `'in'`: animation ends at the element's idle state (element animates in as it enters) +- `'out'`: animation starts from the element's idle state (element animates out as it exits) +- `'continuous'`: animation passes through the idle state (animates across the full scroll range) + +--- + +## Preset Reference + +### ArcScroll + +Visual: 3D arc rotation as user scrolls. Dramatic, cinematic. + +Parameters: + +- `direction`: 'vertical' | 'horizontal' (default: 'horizontal') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `perspective`: number (default: 500) + +```typescript +{ type: 'ArcScroll', direction: 'vertical' } +{ type: 'ArcScroll', direction: 'horizontal', range: 'in' } +``` + +### BlurScroll + +Visual: Blur/unblur effect controlled by scroll. Focus transitions. + +Parameters: + +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `blur`: number in px (default: 6) + +```typescript +{ type: 'BlurScroll', range: 'in' } +{ type: 'BlurScroll', range: 'out', blur: 50 } +``` + +### FadeScroll + +Visual: Opacity transition tied to scroll. Fade in on enter, out on exit. + +Parameters: + +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `opacity`: number 0-1 (default: 0) + +```typescript +{ type: 'FadeScroll', range: 'in' } +{ type: 'FadeScroll', range: 'out' } +``` + +### FlipScroll + +Visual: Full 3D card flip driven by scroll. Dramatic rotation. + +Parameters: + +- `direction`: 'vertical' | 'horizontal' (default: 'horizontal') +- `range`: 'in' | 'out' | 'continuous' (default: 'continuous') +- `rotate`: number in degrees (default: 240) +- `perspective`: number (default: 800) + +```typescript +{ type: 'FlipScroll', direction: 'horizontal' } +{ type: 'FlipScroll', direction: 'vertical', range: 'in', rotate: 420 } +``` + +### GrowScroll + +Visual: Scale up as element enters viewport. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' (default: 'center') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `scale`: number (default: varies by range) +- `speed`: number (default: 0) + +```typescript +{ type: 'GrowScroll', direction: 'center' } +{ type: 'GrowScroll', direction: 'center', range: 'in', scale: 4 } +``` + +### MoveScroll + +Visual: Translation movement on scroll in any direction. + +Parameters: + +- `angle`: 0-360 degrees (default: 120). 0° = right, 90° = top, 180° = left, 270° = bottom +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `distance`: UnitLengthPercentage (default: { value: 400, type: 'px' }) + +```typescript +{ type: 'MoveScroll', angle: 90, distance: { value: 100, type: 'px' } } +{ type: 'MoveScroll', angle: 0, distance: { value: 800, type: 'px' } } +``` + +### PanScroll + +Visual: Horizontal panning tied to scroll. + +Parameters: + +- `direction`: 'left' | 'right' (default: 'left') +- `distance`: UnitLengthPercentage (default: { value: 400, type: 'px' }) +- `startFromOffScreen`: boolean (default: true) +- `range`: 'in' | 'out' | 'continuous' (default: 'in') + +```typescript +{ type: 'PanScroll', direction: 'left', distance: { value: 200, type: 'px' } } +``` + +### ParallaxScroll + +Visual: Element moves slower/faster than scroll, creating depth illusion. + +Parameters: + +- `parallaxFactor`: number (default: 0.5) - movement speed relative to scroll +- `range`: 'in' | 'out' | 'continuous' + +```typescript +{ type: 'ParallaxScroll' } +{ type: 'ParallaxScroll', parallaxFactor: 0.3 } +``` + +### RevealScroll + +Visual: Clip-based directional reveal on scroll. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'bottom') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') + +```typescript +{ type: 'RevealScroll', direction: 'left' } +{ type: 'RevealScroll', direction: 'bottom', range: 'in' } +``` + +### ShapeScroll + +Visual: Shape mask reveal controlled by scroll. + +Parameters: + +- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' (default: 'circle') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `intensity`: number 0-1 (default: 0.5) + +```typescript +{ type: 'ShapeScroll', shape: 'circle' } +{ type: 'ShapeScroll', shape: 'diamond', intensity: 0.8 } +``` + +### ShrinkScroll + +Visual: Scale down as element exits viewport. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' (default: 'center') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `scale`: number (default: varies by range) +- `speed`: number (default: 0) + +```typescript +{ type: 'ShrinkScroll', direction: 'center', range: 'out' } +{ type: 'ShrinkScroll', direction: 'center', scale: 0 } +``` + +### ShuttersScroll + +Visual: Venetian blind strips revealing on scroll. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'right') +- `shutters`: number of strips (default: 12) +- `staggered`: boolean (default: true) +- `range`: 'in' | 'out' | 'continuous' (default: 'in') + +```typescript +{ type: 'ShuttersScroll', direction: 'left', shutters: 5, staggered: true } +``` + +### SkewPanScroll + +Visual: Panning with skew distortion effect. + +Parameters: + +- `direction`: 'left' | 'right' (default: 'right') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `skew`: number in degrees (default: 10) + +```typescript +{ type: 'SkewPanScroll', direction: 'left' } +{ type: 'SkewPanScroll', direction: 'right', skew: 24 } +``` + +### SlideScroll + +Visual: Slide movement tied to scroll position. + +Parameters: + +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'bottom') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') + +```typescript +{ type: 'SlideScroll', direction: 'bottom' } +{ type: 'SlideScroll', direction: 'left', range: 'in' } +``` + +### Spin3dScroll + +Visual: 3D rotation around axis on scroll. + +Parameters: + +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `rotate`: number in degrees (default: -100) +- `speed`: number (default: 0) +- `perspective`: number (default: 1000) + +```typescript +{ type: 'Spin3dScroll' } +{ type: 'Spin3dScroll', range: 'continuous', rotate: 200 } +``` + +### SpinScroll + +Visual: 2D rotation driven by scroll. + +Parameters: + +- `direction`: 'clockwise' | 'counter-clockwise' (default: 'clockwise') +- `spins`: number of rotations (default: 0.15) +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `scale`: number (default: 1) + +```typescript +{ type: 'SpinScroll', direction: 'clockwise', spins: 1 } +{ type: 'SpinScroll', direction: 'counter-clockwise', spins: 2, scale: 0.4 } +``` + +### StretchScroll + +Visual: Stretch/squeeze deformation on scroll. + +Parameters: + +- `range`: 'in' | 'out' | 'continuous' (default: 'out') +- `stretch`: number (default: 0.6) + +```typescript +{ type: 'StretchScroll' } +{ type: 'StretchScroll', stretch: 2 } +``` + +### TiltScroll + +Visual: 3D tilt effect as user scrolls. Subtle perspective. + +Parameters: + +- `direction`: 'left' | 'right' (default: 'right') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `parallaxFactor`: number (default: 0) - tilt distance factor +- `perspective`: number (default: 400) + +```typescript +{ type: 'TiltScroll', direction: 'left' } +{ type: 'TiltScroll', direction: 'right', parallaxFactor: 1 } +``` + +### TurnScroll + +Visual: Corner-pivot 3D rotation on scroll. + +Parameters: + +- `direction`: 'left' | 'right' (default: 'right') +- `spin`: 'clockwise' | 'counter-clockwise' (default: 'clockwise') +- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `scale`: number (default: 1) +- `rotation`: number + +```typescript +{ type: 'TurnScroll', direction: 'left', spin: 'clockwise' } +{ type: 'TurnScroll', direction: 'right', spin: 'counter-clockwise', scale: 1.6 } +``` + +--- + +## Intensity Values + +Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| ------------- | --------- | ----------- | ------ | ------------- | +| BlurScroll | blur | 6px | 25px | 50px | +| FlipScroll | rotate | 60° | 120° | 420° | +| GrowScroll | scale | 1.2 | 1.7 | 4 | +| MoveScroll | distance | 150px | 400px | 800px | +| ShrinkScroll | scale | 0.8 | 0.3 | 0 | +| SkewPanScroll | skew | 10° | 17° | 24° | +| Spin3dScroll | rotate | 45° | 100° | 200° | +| SpinScroll | scale | 1 | 0.7 | 0.4 | +| StretchScroll | stretch | 1.2 | 1.5 | 2 | +| TiltScroll | distance | 0 | 0.5 | 1 | +| TurnScroll | scale | 1 | 1.3 | 1.6 | + +--- + +## Optional Parameters + +These parameters are exposed but their defaults have been tuned for good visual results and rarely need adjustment. + +### 3D Perspective + +| Preset | Parameter | Default | Range | +| ------------ | ------------- | ------- | -------- | +| FlipScroll | `perspective` | 800 | 200-2000 | +| TiltScroll | `perspective` | 400 | 200-2000 | +| Spin3dScroll | `perspective` | 1000 | 200-2000 | diff --git a/packages/motion-presets/rules/presets/scroll.md b/packages/motion-presets/rules/presets/scroll.md deleted file mode 100644 index 11fb6de2..00000000 --- a/packages/motion-presets/rules/presets/scroll.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: Scroll Animations -category: scroll ---- - -# Scroll Animations - -Animations whose progress is tied to a ViewTimeline - the element's position in the viewport. - -## When to Use Scroll Animations - -- Progressive content reveals on scroll -- Parallax depth effects -- Storytelling tied to scroll progress -- De-emphasizing passed content - -## When NOT to Use Scroll Animations - -- One-time entrance → see [Entrance](presets-reference.md#entrance-presets) (more performant) -- Continuous loops → see [Ongoing](presets-reference.md#ongoing-presets) - -## Available Scroll Presets - -See [Scroll Presets](presets-reference.md#scroll-presets) for full details: - -ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll - -## Scroll Range Modes - -- `in`: Animates as element enters viewport -- `out`: Animates as element exits viewport -- `continuous`: Animates throughout entire scroll range - -## Scroll Quick Decision - -| Effect Type | Presets | -| ----------- | -------------------------------------------------- | -| Opacity | FadeScroll, BlurScroll | -| Movement | ParallaxScroll, MoveScroll, PanScroll, SlideScroll | -| Scale | GrowScroll, ShrinkScroll | -| 3D Rotation | ArcScroll, FlipScroll, TiltScroll, TurnScroll | -| Reveal/Mask | RevealScroll, ShapeScroll, ShuttersScroll | - -## Scroll Common Use Cases - -| Use Case | Recommended | -| ------------------- | ------------------------------------ | -| Depth/Layering | ParallaxScroll with different speeds | -| Content reveal | FadeScroll (in), RevealScroll | -| Dramatic sections | ArcScroll, FlipScroll, TiltScroll | -| De-emphasize passed | FadeScroll (out), ShrinkScroll | From 77b240eb00eb31984ed599eab9f22c9bf488a492 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Wed, 18 Feb 2026 20:52:17 +0200 Subject: [PATCH 17/20] regeneratwd all files from scratch --- .../rules/presets/entrance-presets.md | 265 ++++++++------- .../rules/presets/mouse-presets.md | 205 ++++++----- .../rules/presets/ongoing-presets.md | 153 +++++---- .../rules/presets/presets-main.md | 232 ++++--------- .../rules/presets/scroll-presets.md | 318 ++++++++++-------- 5 files changed, 602 insertions(+), 571 deletions(-) diff --git a/packages/motion-presets/rules/presets/entrance-presets.md b/packages/motion-presets/rules/presets/entrance-presets.md index 0295480b..c6eb9fa9 100644 --- a/packages/motion-presets/rules/presets/entrance-presets.md +++ b/packages/motion-presets/rules/presets/entrance-presets.md @@ -1,30 +1,43 @@ --- -name: entrance-presets-reference -description: Full parameter details, examples, and intensity guide for entrance presets. Read when configuring specific entrance preset parameters or choosing intensity levels for entrance animations. -category: entrance +name: entrance-presets +description: Full parameter reference for entrance motion presets. Read when configuring FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, or WinkIn entrance animations. --- # Entrance Presets -All entrance preset parameters and TypeScript examples. For category overview and selection guidance, see [presets-main.md](presets-main.md). +Entrance presets animate an element's first appearance, typically triggered when it enters the viewport. They can also be triggered by hover, click, or other events. ## Table of Contents -- [Preset Reference](#preset-reference) -- [Intensity Values](#intensity-values) +- [FadeIn](#fadein) +- [ArcIn](#arcin) +- [BlurIn](#blurin) +- [BounceIn](#bouncein) +- [CurveIn](#curvein) +- [DropIn](#dropin) +- [ExpandIn](#expandin) +- [FlipIn](#flipin) +- [FloatIn](#floatin) +- [FoldIn](#foldin) +- [GlideIn](#glidein) +- [RevealIn](#revealin) +- [ShapeIn](#shapein) +- [ShuttersIn](#shuttersin) +- [SlideIn](#slidein) +- [SpinIn](#spinin) +- [TiltIn](#tiltin) +- [TurnIn](#turnin) +- [WinkIn](#winkin) - [Optional Parameters](#optional-parameters) +- [Intensity Value Guide](#intensity-value-guide) --- -## Preset Reference - ### FadeIn -Visual: Element transitions from invisible to visible. Simple opacity change, no movement. - -Parameters: +Visual: Element fades in smoothly from fully transparent to fully opaque. -- No preset-specific parameters +Parameters: None — this preset has no configurable parameters. ```typescript { @@ -32,249 +45,273 @@ Parameters: } ``` +--- + ### ArcIn -Visual: Element swings in along a curved 3D path, like a door opening. Dramatic, cinematic. +Visual: Element enters along a 3D arc path, rotating into view with depth motion and a fade-in. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'right') -- `depth`: UnitLengthPercentage (default: { value: 200, type: 'px' }) -- `perspective`: number (default: 800) +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'right'`) +- `depth`: UnitLengthPercentage — Z translation distance (default: `{ value: 200, unit: 'px' }`) +- `perspective`: number — 3D perspective in px (default: `800`) ```typescript { type: 'ArcIn', direction: 'bottom' } -{ type: 'ArcIn', direction: 'left', depth: { value: 500, type: 'px' } } ``` +--- + ### BlurIn -Visual: Element transitions from blurry to sharp focus while fading in. Soft, dreamy. +Visual: Element transitions from blurred to clear while fading in. Parameters: -- `blur`: number in px (default: 6) +- `blur`: number — initial blur amount in px (default: `6`) ```typescript -{ type: 'BlurIn' } -{ type: 'BlurIn', blur: 25 } // Medium -{ type: 'BlurIn', blur: 50 } // Dramatic +{ type: 'BlurIn', blur: 25 } ``` +--- + ### BounceIn -Visual: Element bounces into view with spring physics. Playful, attention-grabbing. +Visual: Element bounces into place from a direction with an elastic multi-step curve. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'center' (default: 'bottom') -- `distanceFactor`: number (default: 1) -- `perspective`: number (default: 800) - only used with 'center' direction +- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'center' (default: `'bottom'`) +- `distanceFactor`: number — bounce distance multiplier (default: `1`) +- `perspective`: number — 3D perspective for center direction (default: `800`) ```typescript -{ type: 'BounceIn' } -{ type: 'BounceIn', direction: 'center', distanceFactor: 2 } +{ type: 'BounceIn', direction: 'left', distanceFactor: 2 } ``` +--- + ### CurveIn -Visual: Curved 3D motion path entry. Cinematic arc trajectory. +Visual: Element curves in with a 180° rotation and depth motion, creating a swinging arc entrance. Parameters: -- `direction`: 'left' | 'right' | 'pseudoLeft' | 'pseudoRight' (default: 'right') -- `depth`: UnitLengthPercentage (default: { value: 300, type: 'px' }) -- `perspective`: number (default: 200) +- `direction`: 'left' | 'right' | 'pseudoLeft' | 'pseudoRight' (default: `'right'`) +- `depth`: UnitLengthPercentage — Z translation distance (default: `{ value: 300, unit: 'px' }`) +- `perspective`: number — 3D perspective in px (default: `200`) ```typescript { type: 'CurveIn', direction: 'left' } ``` +--- + ### DropIn -Visual: Falls from above with subtle scale on landing. Gravity-like, natural. +Visual: Element drops in from above, scaling down from a larger size to its final scale. Parameters: -- `initialScale`: number (default: 1.6) +- `initialScale`: number — starting scale before settling to 1 (default: `1.6`) ```typescript -{ type: 'DropIn' } { type: 'DropIn', initialScale: 2 } ``` +--- + ### ExpandIn -Visual: Scale from small to full size with directional expansion from edge. Emerging, growing outward. +Visual: Element expands from a point in a given direction, scaling from small to full size with a fade-in. Parameters: -- `direction`: number in degrees or keyword ('top' | 'right' | 'bottom' | 'left') (default: 90, from top) -- `distance`: UnitLengthPercentage (default: { value: 120, type: 'percentage' }) -- `initialScale`: number (default: 0) +- `initialScale`: number — starting scale, 0 = invisible (default: `0`) +- `direction`: number | 'top' | 'right' | 'bottom' | 'left' — angle or cardinal direction (default: `90` / top). 0° = right, 90° = top, 180° = left, 270° = bottom +- `distance`: UnitLengthPercentage — how far the element travels (default: `{ value: 120, unit: 'percentage' }`) ```typescript -{ type: 'ExpandIn' } -{ type: 'ExpandIn', direction: 'bottom', distance: { value: 100, type: 'px' }, initialScale: 0.3 } +{ type: 'ExpandIn', direction: 'bottom', initialScale: 0.5 } ``` +--- + ### FlipIn -Visual: 3D card flip rotation to reveal element. Dramatic, card-like metaphor. +Visual: Element flips into view with a 3D rotation around the X or Y axis. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'top') -- `initialRotate`: number in degrees (default: 90) -- `perspective`: number (default: 800) +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'top'`) +- `initialRotate`: number — starting rotation in degrees (default: `90`) +- `perspective`: number — 3D perspective in px (default: `800`) ```typescript -{ type: 'FlipIn', direction: 'left' } -{ type: 'FlipIn', direction: 'top', initialRotate: 270 } +{ type: 'FlipIn', direction: 'right', initialRotate: 180 } ``` +--- + ### FloatIn -Visual: Gentle floating/drifting entrance. Ethereal, light, dreamy. +Visual: Element drifts gently into place from a direction with a fade-in. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'left') +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'left'`) ```typescript { type: 'FloatIn', direction: 'bottom' } ``` +--- + ### FoldIn -Visual: Paper-folding 3D effect. Origami-like, creative. +Visual: Element unfolds from an edge, rotating around an axis at the edge as if hinged. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'top') -- `initialRotate`: number in degrees (default: 90) -- `perspective`: number (default: 800) +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'top'`) +- `initialRotate`: number — starting fold angle in degrees (default: `90`) +- `perspective`: number — 3D perspective in px (default: `800`) ```typescript -{ type: 'FoldIn', direction: 'left' } -{ type: 'FoldIn', direction: 'top', initialRotate: 45 } +{ type: 'FoldIn', direction: 'left', initialRotate: 60 } ``` +--- + ### GlideIn -Visual: Smooth 2D glide from any angle with distance control. Clean, directional. +Visual: Element glides in smoothly from off-screen along a direction with a fade-in. Parameters: -- `direction`: number in degrees (default: 180, from left). 0° = right, 90° = top, 180° = left, 270° = bottom -- `distance`: UnitLengthPercentage | EffectFourDirections (default: { value: 100, type: 'percentage' }) +- `direction`: number | 'top' | 'right' | 'bottom' | 'left' — angle or cardinal (default: `180` / left). 0° = right, 90° = top, 180° = left, 270° = bottom +- `distance`: UnitLengthPercentage | 'top' | 'right' | 'bottom' | 'left' — travel distance or edge keyword (default: `{ value: 100, unit: 'percentage' }`) ```typescript -{ type: 'GlideIn' } -{ type: 'GlideIn', direction: 90, distance: { value: 50, type: 'percentage' } } +{ type: 'GlideIn', direction: 270, distance: { value: 200, type: 'px' } } ``` +--- + ### RevealIn -Visual: Directional clip/mask reveal like a curtain opening. Theatrical. +Visual: Element is progressively revealed by an expanding clip-path from one edge. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'left') +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'left'`) ```typescript -{ type: 'RevealIn', direction: 'left' } +{ type: 'RevealIn', direction: 'bottom' } ``` +--- + ### ShapeIn -Visual: Shape mask reveal (circle, square, diamond, etc.). Geometric, precise. +Visual: Element appears through an expanding geometric clip-path shape. Parameters: -- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' (default: 'rectangle') +- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' (default: `'rectangle'`) ```typescript { type: 'ShapeIn', shape: 'circle' } -{ type: 'ShapeIn', shape: 'diamond' } ``` +--- + ### ShuttersIn -Visual: Venetian blind strip reveal. Segmented, rhythmic. +Visual: Element is revealed through multiple shutter-like strips that open in sequence. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'right') -- `shutters`: number of strips (default: 12) -- `staggered`: boolean - animate strips sequentially (default: true) +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'right'`) +- `shutters`: number — number of shutter segments (default: `12`) +- `staggered`: boolean — whether shutters open in a staggered pattern (default: `true`) ```typescript -{ type: 'ShuttersIn', direction: 'left', shutters: 5, staggered: true } +{ type: 'ShuttersIn', direction: 'top', shutters: 8 } ``` +--- + ### SlideIn -Visual: Straight movement from direction with clip. Clean, simple, versatile. +Visual: Element slides in from one side while being revealed with a clip-path mask. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'left') -- `initialTranslate`: number 0-1 (default: 1) - starting offset ratio +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'left'`) +- `initialTranslate`: number — 0 to 1, how far off-screen the element starts (default: `1`) ```typescript -{ type: 'SlideIn', direction: 'bottom' } -{ type: 'SlideIn', direction: 'left', initialTranslate: 0.2 } +{ type: 'SlideIn', direction: 'right', initialTranslate: 0.5 } ``` +--- + ### SpinIn -Visual: Rotating entrance with spin. Dynamic, playful. +Visual: Element spins into view while scaling from small to full size. Parameters: -- `direction`: 'clockwise' | 'counter-clockwise' (default: 'clockwise') -- `spins`: number of rotations (default: 0.5) -- `initialScale`: number (default: 0) - starting scale +- `spins`: number — number of full rotations (default: `0.5`) +- `direction`: 'clockwise' | 'counter-clockwise' (default: `'clockwise'`) +- `initialScale`: number — starting scale, 0 = invisible (default: `0`) ```typescript -{ type: 'SpinIn', direction: 'clockwise', spins: 1 } -{ type: 'SpinIn', direction: 'counter-clockwise', spins: 2, initialScale: 0.5 } +{ type: 'SpinIn', spins: 1, direction: 'counter-clockwise' } ``` +--- + ### TiltIn -Visual: 3D tilt into view. Subtle depth, elegant perspective. +Visual: Element tilts in from the side with 3D rotation and a clip-path reveal. Parameters: -- `direction`: 'left' | 'right' (default: 'left') -- `depth`: UnitLengthPercentage (default: { value: 200, type: 'px' }) -- `perspective`: number (default: 800) +- `direction`: 'left' | 'right' (default: `'left'`) +- `depth`: UnitLengthPercentage — Z translation distance (default: `{ value: 200, unit: 'px' }`) +- `perspective`: number — 3D perspective in px (default: `800`) ```typescript -{ type: 'TiltIn', direction: 'left' } +{ type: 'TiltIn', direction: 'right' } ``` +--- + ### TurnIn -Visual: Corner-pivot 3D rotation. Complex, dramatic, premium. +Visual: Element rotates into view around a corner pivot point. Parameters: -- `direction`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' (default: 'top-left') +- `direction`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' (default: `'top-left'`) ```typescript -{ type: 'TurnIn', direction: 'bottom-left' } +{ type: 'TurnIn', direction: 'bottom-right' } ``` +--- + ### WinkIn -Visual: Split-in-half reveal from center. Unique, eye-like opening. +Visual: Element winks into view by scaling along one axis while being revealed with a clip-path. Parameters: -- `direction`: 'vertical' | 'horizontal' (default: 'horizontal') +- `direction`: 'horizontal' | 'vertical' (default: `'horizontal'`) ```typescript { type: 'WinkIn', direction: 'vertical' } @@ -282,29 +319,9 @@ Parameters: --- -## Intensity Values - -Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. - -| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | -| -------- | ---------------- | ----------- | ---------- | ------------- | -| ArcIn | easing | cubicInOut | quintInOut | backOut | -| BlurIn | blur | 6px | 25px | 50px | -| BounceIn | distanceFactor | 1 | 2 | 3 | -| DropIn | initialScale | 1.2 | 1.6 | 2 | -| FlipIn | initialRotate | 45° | 90° | 270° | -| FoldIn | initialRotate | 35° | 60° | 90° | -| ExpandIn | initialScale | 0.8 | 0.6 | 0 | -| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | -| SpinIn | initialScale | 1 | 0.6 | 0 | - -Example -- "I want a subtle flip entrance": `{ type: 'FlipIn', initialRotate: 45 }` - ---- - ## Optional Parameters -These parameters are exposed but their defaults have been tuned for good visual results and rarely need adjustment. +Some preset parameters are exposed but their defaults have been tuned for good visual results and rarely need adjustment. ### 3D Perspective @@ -324,3 +341,25 @@ These parameters are exposed but their defaults have been tuned for good visual | ArcIn | `depth` | 200px | Z translation distance | | CurveIn | `depth` | 300px | Z translation distance | | TiltIn | `depth` | 200px | Z translation distance | + +## Intensity Value Guide + +Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. + +| Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | +| -------- | ---------------- | ----------- | ---------- | ------------- | +| ArcIn | easing | cubicInOut | quintInOut | backOut | +| BlurIn | blur | 6px | 25px | 50px | +| BounceIn | distanceFactor | 1 | 2 | 3 | +| DropIn | initialScale | 1.2 | 1.6 | 2 | +| FlipIn | initialRotate | 45° | 90° | 270° | +| FoldIn | initialRotate | 35° | 60° | 90° | +| ExpandIn | initialScale | 0.8 | 0.6 | 0 | +| SlideIn | initialTranslate | 0.2 | 0.8 | 1 | +| SpinIn | initialScale | 1 | 0.6 | 0 | + +### Intensity Usage Example + +When a user asks: "I want a subtle flip entrance" + +Suggest: `{ type: 'FlipIn', initialRotate: 45 }` diff --git a/packages/motion-presets/rules/presets/mouse-presets.md b/packages/motion-presets/rules/presets/mouse-presets.md index c3696fb9..22e4f42c 100644 --- a/packages/motion-presets/rules/presets/mouse-presets.md +++ b/packages/motion-presets/rules/presets/mouse-presets.md @@ -1,91 +1,122 @@ --- -name: mouse-presets-reference -description: Full parameter details, examples, and intensity guide for mouse presets. Read when configuring specific mouse preset parameters or choosing intensity levels for cursor-follow and pointer-reactive effects. -category: mouse +name: mouse-presets +description: Full parameter reference for mouse motion presets. Read when configuring AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, or TrackMouse pointer-driven animations. --- # Mouse Presets -All mouse preset parameters and TypeScript examples. For category overview and selection guidance, see [presets-main.md](presets-main.md). +Mouse presets drive element transforms in real-time based on pointer position. The element responds to cursor movement with translation, rotation, scale, or other effects. All mouse presets (except CustomMouse) share the `inverted` base parameter. -## Table of Contents +**Mobile note:** Mouse presets respond to pointer events. On touch devices, behavior may differ — the element responds to touch position rather than a persistent cursor, so effects may only activate during active touch. Consider this when designing for cross-device experiences. -- [Preset Reference](#preset-reference) -- [Intensity Values](#intensity-values) -- [Mobile Considerations](#mobile-considerations) +## Table of Contents -All mouse presets accept an optional `inverted`: boolean parameter (default: false). +- [Shared Parameters](#shared-parameters) +- [AiryMouse](#airymouse) +- [BlobMouse](#blobmouse) +- [BlurMouse](#blurmouse) +- [BounceMouse](#bouncemouse) +- [CustomMouse](#custommouse) +- [ScaleMouse](#scalemouse) +- [SkewMouse](#skewmouse) +- [SpinMouse](#spinmouse) +- [SwivelMouse](#swivelmouse) +- [Tilt3DMouse](#tilt3dmouse) +- [Track3DMouse](#track3dmouse) +- [TrackMouse](#trackmouse) +- [Intensity Value Guide](#intensity-value-guide) --- -## Preset Reference +## Shared Parameters + +These parameters are available on all mouse presets (except CustomMouse): + +- `inverted`: boolean — reverses the movement/effect direction (default: `false`) + +The `axis` parameter, where available, accepts: + +- `'both'`: respond on both axes +- `'horizontal'`: respond only on X +- `'vertical'`: respond only on Y + +--- ### AiryMouse -Visual: Floating/airy cursor response. Ethereal, gentle drift. +Visual: Element floats and rotates gently following the cursor, creating an airy, weightless feel. Parameters: -- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) -- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') -- `angle`: number (default: 30) +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 200, unit: 'px' }`) +- `angle`: number — max rotation in degrees (default: `30`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) ```typescript -{ type: 'AiryMouse' } -{ type: 'AiryMouse', angle: 10 } +{ type: 'AiryMouse', angle: 50, distance: { value: 150, type: 'px' } } ``` +--- + ### BlobMouse -Visual: Organic blob-like deformation. Fluid shape distortion. +Visual: Element translates and scales non-uniformly following the cursor, creating a blob-like deformation. Parameters: -- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) -- `scale`: number (default: 1.4) +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 200, unit: 'px' }`) +- `scale`: number — max scale at edges (default: `1.4`) ```typescript -{ type: 'BlobMouse' } -{ type: 'BlobMouse', scale: 2.4 } +{ type: 'BlobMouse', scale: 2, distance: { value: 100, type: 'px' } } ``` +--- + ### BlurMouse -Visual: Blur based on cursor distance. Focus/defocus by proximity. +Visual: Element translates, tilts in 3D, scales, and blurs based on distance from the cursor — the farther away, the stronger the blur and tilt. Parameters: -- `distance`: UnitLengthPercentage (default: { value: 80, type: 'px' }) -- `angle`: number (default: 5) -- `scale`: number (default: 0.3) -- `blur`: number (default: 20) -- `perspective`: number (default: 600) +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 80, unit: 'px' }`) +- `angle`: number — max 3D rotation in degrees (default: `5`) +- `scale`: number — min scale at edges (default: `0.3`) +- `blur`: number — max blur in px (default: `20`) +- `perspective`: number — 3D perspective in px (default: `600`) ```typescript -{ type: 'BlurMouse' } -{ type: 'BlurMouse', angle: 65, scale: 0.25 } +{ type: 'BlurMouse', blur: 30, angle: 10 } ``` +--- + ### BounceMouse -Visual: Bouncy/elastic cursor following. Overshoots and wobbles. +Visual: Element follows the cursor with an elastic, bouncy motion. Parameters: -- `distance`: UnitLengthPercentage (default: { value: 80, type: 'px' }) -- `axis`: 'horizontal' | 'vertical' | 'both' +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 80, unit: 'px' }`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) ```typescript -{ type: 'BounceMouse', distance: { value: 80, type: 'px' }, axis: 'both' } +{ type: 'BounceMouse', distance: { value: 120, type: 'px' } } ``` +--- + ### CustomMouse -Visual: Configurable custom behavior. For advanced custom implementations. +Visual: Fully custom effect — behavior is defined by a provided callback function. Parameters: -- No preset-specific parameters +- `customEffect`: (target: HTMLElement, progress: Progress) => void — custom function receiving the target element and normalized cursor progress `{ x, y, v: { x, y }, active }` ```typescript { @@ -93,111 +124,125 @@ Parameters: } ``` +--- + ### ScaleMouse -Visual: Scale based on cursor distance. Grows/shrinks by proximity. +Visual: Element translates and scales uniformly following the cursor. Parameters: -- `distance`: UnitLengthPercentage (default: { value: 80, type: 'px' }) -- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') -- `scale`: number (default: 1.4) +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 80, unit: 'px' }`) +- `scale`: number — scale at edges, >1 for grow, <1 for shrink (default: `1.4`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) ```typescript -{ type: 'ScaleMouse', distance: { value: 100, type: 'px' } } +{ type: 'ScaleMouse', scale: 0.5 } ``` +--- + ### SkewMouse -Visual: Skew distortion following cursor. Angular distortion. +Visual: Element translates and skews following the cursor, creating a directional distortion. Parameters: -- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) -- `angle`: number (default: 25) -- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 200, unit: 'px' }`) +- `angle`: number — max skew angle in degrees (default: `25`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) ```typescript -{ type: 'SkewMouse' } -{ type: 'SkewMouse', angle: 45 } +{ type: 'SkewMouse', angle: 15, axis: 'horizontal' } ``` +--- + ### SpinMouse -Visual: Rotation following mouse angle. Element spins based on cursor position. +Visual: Element rotates toward the cursor position. Parameters: -- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') +- `inverted`: boolean (default: `false`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) ```typescript -{ type: 'SpinMouse' } -{ type: 'SpinMouse', axis: 'both' } +{ type: 'SpinMouse', axis: 'horizontal' } ``` +--- + ### SwivelMouse -Visual: Pivot-axis rotation following cursor. Gyroscope-like rotation. +Visual: Element tilts in 3D around a chosen pivot axis following the cursor. Parameters: -- `angle`: number (default: 5) -- `perspective`: number (default: 800) -- `pivotAxis`: 'top' | 'bottom' | 'right' | 'left' | 'center-horizontal' | 'center-vertical' (default: 'center-horizontal') +- `inverted`: boolean (default: `false`) +- `angle`: number — max tilt angle in degrees (default: `5`) +- `perspective`: number — 3D perspective in px (default: `800`) +- `pivotAxis`: 'top' | 'bottom' | 'right' | 'left' | 'center-horizontal' | 'center-vertical' (default: `'center-horizontal'`) ```typescript -{ type: 'SwivelMouse' } -{ type: 'SwivelMouse', angle: 25, perspective: 1000 } +{ type: 'SwivelMouse', angle: 25, pivotAxis: 'top' } ``` +--- + ### Tilt3DMouse -Visual: Element tilts toward cursor in 3D, like angling a card. Premium, interactive. +Visual: Element tilts in 3D based on cursor position, rotating on X and Y axes from center. Parameters: -- `angle`: number (default: 5) -- `perspective`: number (default: 800) +- `inverted`: boolean (default: `false`) +- `angle`: number — max tilt angle in degrees (default: `5`) +- `perspective`: number — 3D perspective in px (default: `800`) ```typescript -{ type: 'Tilt3DMouse' } -{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } -{ type: 'Tilt3DMouse', angle: 85, perspective: 200 } +{ type: 'Tilt3DMouse', angle: 15, perspective: 500 } ``` +--- + ### Track3DMouse -Visual: Combined translation + 3D rotation following mouse. Complex, immersive. +Visual: Element translates and tilts in 3D following the cursor, combining movement with perspective rotation. Parameters: -- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) -- `angle`: number (default: 5) -- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') -- `perspective`: number (default: 800) +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 200, unit: 'px' }`) +- `angle`: number — max 3D rotation in degrees (default: `5`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) +- `perspective`: number — 3D perspective in px (default: `800`) ```typescript -{ type: 'Track3DMouse', distance: { value: 100, type: 'px' }, axis: 'both' } -{ type: 'Track3DMouse', distance: { value: 50, type: 'px' }, angle: 25, perspective: 1000 } +{ type: 'Track3DMouse', angle: 15, distance: { value: 100, type: 'px' } } ``` +--- + ### TrackMouse -Visual: Element follows cursor position. Floating, parallax-like. +Visual: Element follows the cursor with direct translation, no rotation. Parameters: -- `distance`: UnitLengthPercentage (default: { value: 200, type: 'px' }) -- `axis`: 'horizontal' | 'vertical' | 'both' (default: 'both') +- `inverted`: boolean (default: `false`) +- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 200, unit: 'px' }`) +- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) ```typescript -{ type: 'TrackMouse', distance: { value: 200, type: 'px' }, axis: 'both' } -{ type: 'TrackMouse', distance: { value: 50, type: 'px' }, axis: 'horizontal' } +{ type: 'TrackMouse', distance: { value: 100, type: 'px' }, axis: 'vertical' } ``` --- -## Intensity Values +## Intensity Value Guide Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. @@ -212,13 +257,3 @@ Tested values for different intensity levels. When a user asks for "soft", "subt | SwivelMouse | angle, perspective | 25°, 1000 | 50°, 700 | 85°, 300 | | Tilt3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 200 | | Track3DMouse | angle, perspective | 25°, 1000 | 50°, 500 | 85°, 333 | - ---- - -## Mobile Considerations - -Mouse effects may behave differently on touch devices. Options: - -1. Do nothing (static on mobile) -2. Use entrance animation instead -3. Use device orientation (advanced) diff --git a/packages/motion-presets/rules/presets/ongoing-presets.md b/packages/motion-presets/rules/presets/ongoing-presets.md index f76ccc79..bbfc8e27 100644 --- a/packages/motion-presets/rules/presets/ongoing-presets.md +++ b/packages/motion-presets/rules/presets/ongoing-presets.md @@ -1,69 +1,81 @@ --- -name: ongoing-presets-reference -description: Full parameter details, examples, and intensity guide for ongoing presets. Read when configuring specific ongoing preset parameters or choosing intensity levels for looping and continuous animations. -category: ongoing +name: ongoing-presets +description: Full parameter reference for ongoing motion presets. Read when configuring Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, or Wiggle continuous loop animations. --- # Ongoing Presets -All ongoing preset parameters and TypeScript examples. For category overview and selection guidance, see [presets-main.md](presets-main.md). +Ongoing presets run as continuous, looping animations. They repeat indefinitely until stopped, making them suitable for attention-drawing, idle-state, and ambient effects. ## Table of Contents -- [Preset Reference](#preset-reference) -- [Intensity Values](#intensity-values) +- [Bounce](#bounce) +- [Breathe](#breathe) +- [Cross](#cross) +- [DVD](#dvd) +- [Flash](#flash) +- [Flip](#flip) +- [Fold](#fold) +- [Jello](#jello) +- [Poke](#poke) +- [Pulse](#pulse) +- [Rubber](#rubber) +- [Spin](#spin) +- [Swing](#swing) +- [Wiggle](#wiggle) +- [Intensity Value Guide](#intensity-value-guide) --- -## Preset Reference - ### Bounce -Visual: Vertical bouncing motion. Playful, energetic. +Visual: Element bounces up and down with a natural multi-step curve, like a ball settling. Parameters: -- `intensity`: number 0-1 (default: 0) +- `intensity`: number — 0 to 1, maps to bounce height factor 1–3 (default: `0`) ```typescript -{ type: 'Bounce' } { type: 'Bounce', intensity: 0.5 } ``` +--- + ### Breathe -Visual: Slow scale in/out like breathing. Calm, organic, meditative. +Visual: Element gently moves back and forth along an axis, like a breathing motion. Parameters: -- `direction`: 'vertical' | 'horizontal' | 'center' (default: 'vertical') -- `distance`: UnitLengthPercentage (default: { value: 25, type: 'px' }) -- `perspective`: number (default: 800) +- `direction`: 'vertical' | 'horizontal' | 'center' (default: `'vertical'`) +- `distance`: UnitLengthPercentage — movement distance (default: `{ value: 25, unit: 'px' }`) +- `perspective`: number — 3D perspective for center direction (default: `800`) ```typescript -{ type: 'Breathe', direction: 'center' } -{ type: 'Breathe', direction: 'center', distance: { value: 10, type: 'percentage' } } +{ type: 'Breathe', direction: 'horizontal', distance: { value: 15, type: 'px' } } ``` +--- + ### Cross -Visual: X-pattern diagonal movement. Unique geometric motion. +Visual: Element moves in a cross-pattern to the edge of its container and back. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' (default: 'right') +- `direction`: EffectEightDirections — one of 'left', 'right', 'top', 'bottom', 'top-left', 'top-right', 'bottom-left', 'bottom-right' (default: `'right'`) ```typescript { type: 'Cross', direction: 'top-left' } ``` -### DVD +--- -Visual: Corner-to-corner bounce (DVD screensaver). Nostalgic, retro. +### DVD -Parameters: +Visual: Element bounces diagonally off its container edges like a DVD screensaver logo. No configurable parameters — uses container dimensions to calculate bounce paths. -- No preset-specific parameters +Parameters: None. ```typescript { @@ -71,13 +83,13 @@ Parameters: } ``` -### Flash +--- -Visual: Opacity pulsing/blinking. Attention, warning indicator. +### Flash -Parameters: +Visual: Element blinks by rapidly cycling opacity from visible to invisible and back. -- No preset-specific parameters +Parameters: None. ```typescript { @@ -85,128 +97,139 @@ Parameters: } ``` +--- + ### Flip -Visual: Periodic 180° flips. Card-like rotation showing front/back. +Visual: Element continuously flips with a full 360° 3D rotation. Parameters: -- `direction`: 'vertical' | 'horizontal' (default: 'horizontal') -- `perspective`: number (default: 800) +- `direction`: 'vertical' | 'horizontal' (default: `'horizontal'`) +- `perspective`: number — 3D perspective in px (default: `800`) ```typescript -{ type: 'Flip', direction: 'horizontal' } +{ type: 'Flip', direction: 'vertical' } ``` +--- + ### Fold -Visual: 3D folding motion. Paper-like folding and unfolding. +Visual: Element folds at an edge using 3D rotation, like a page turning back and forth. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'top') -- `angle`: number in degrees (default: 15) +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'top'`) +- `angle`: number — fold angle in degrees (default: `15`) ```typescript -{ type: 'Fold', direction: 'left' } -{ type: 'Fold', direction: 'top', angle: 45 } +{ type: 'Fold', direction: 'right', angle: 30 } ``` +--- + ### Jello -Visual: Wobbly elastic deformation. Jiggly, bouncy distortion. +Visual: Element wobbles with a skew-based jello-like deformation. Parameters: -- `intensity`: number 0-1 (default: 0.25) +- `intensity`: number — 0 to 1, maps to skew factor 1–4 (default: `0.25`) ```typescript -{ type: 'Jello' } -{ type: 'Jello', intensity: 1 } +{ type: 'Jello', intensity: 0.5 } ``` +--- + ### Poke -Visual: Quick scale bump like being tapped. Brief attention "boop". +Visual: Element makes a short, sharp translate in a direction, like being poked. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'right') -- `intensity`: number 0-1 (default: 0.5) +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'right'`) +- `intensity`: number — 0 to 1, maps to poke strength factor 1–4 (default: `0.5`) ```typescript -{ type: 'Poke', direction: 'top' } -{ type: 'Poke', direction: 'right', intensity: 1 } +{ type: 'Poke', direction: 'left', intensity: 0.8 } ``` +--- + ### Pulse -Visual: Gentle scale oscillation, heartbeat-like rhythm. Subtle, universal. +Visual: Element pulses by subtly scaling up and down, drawing attention. Parameters: -- `intensity`: number 0-1 (default: 0) +- `intensity`: number — 0 to 1, adjusts the scale range (default: `0`) ```typescript -{ type: 'Pulse' } { type: 'Pulse', intensity: 0.5 } ``` +--- + ### Rubber -Visual: Elastic stretch effect. Springy stretching and snapping. +Visual: Element stretches non-uniformly on X and Y axes, creating a rubber-band wobble. Parameters: -- `intensity`: number 0-1 (default: 0.5) +- `intensity`: number — 0 to 1, adjusts the stretch amplitude (default: `0.5`) ```typescript -{ type: 'Rubber' } -{ type: 'Rubber', intensity: 1 } +{ type: 'Rubber', intensity: 0.8 } ``` +--- + ### Spin -Visual: Continuous rotation around center. Mechanical, precise. +Visual: Element rotates continuously around its center. Parameters: -- `direction`: 'clockwise' | 'counter-clockwise' (default: 'clockwise') +- `direction`: 'clockwise' | 'counter-clockwise' (default: `'clockwise'`) ```typescript -{ type: 'Spin', direction: 'clockwise' } +{ type: 'Spin', direction: 'counter-clockwise' } ``` +--- + ### Swing -Visual: Rotation oscillation like a pendulum. Back and forth rhythmic. +Visual: Element swings like a pendulum from a pivot at one edge. Parameters: -- `swing`: number in degrees (default: 20) -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'top') +- `direction`: 'top' | 'right' | 'bottom' | 'left' — swing pivot edge (default: `'top'`) +- `swing`: number — maximum swing angle in degrees (default: `20`) ```typescript -{ type: 'Swing' } -{ type: 'Swing', swing: 60 } +{ type: 'Swing', swing: 40, direction: 'right' } ``` +--- + ### Wiggle -Visual: Horizontal shake/wiggle. Side-to-side for attention. +Visual: Element shakes with combined rotation and vertical translation. Parameters: -- `intensity`: number 0-1 (default: 0.5) +- `intensity`: number — 0 to 1, maps to wiggle strength factor 1–4 (default: `0.5`) ```typescript -{ type: 'Wiggle' } -{ type: 'Wiggle', intensity: 1 } +{ type: 'Wiggle', intensity: 0.8 } ``` --- -## Intensity Values +## Intensity Value Guide Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. diff --git a/packages/motion-presets/rules/presets/presets-main.md b/packages/motion-presets/rules/presets/presets-main.md index 475df038..6f082a32 100644 --- a/packages/motion-presets/rules/presets/presets-main.md +++ b/packages/motion-presets/rules/presets/presets-main.md @@ -1,6 +1,6 @@ --- -name: motion-presets-main-reference -description: Entry point for selecting and configuring Interact motion presets. Read when the user asks about motion animations, presets, effects, entrance/scroll/ongoing/mouse animations, or interaction design. +name: motion-presets +description: Reference for selecting and configuring Interact motion presets. Read when applying entrance, scroll, ongoing, or mouse animations to elements, choosing presets by tone or use case, combining effects, or handling accessibility and reduced motion. --- # Motion Presets Reference @@ -8,11 +8,14 @@ description: Entry point for selecting and configuring Interact motion presets. ## Table of Contents - [Terminology](#terminology) -- [Decision Flow](#decision-flow) - [Preset Categories](#preset-categories) -- [Parameter Standards](#parameter-standards) -- [Selection Tables](#selection-tables) +- [Trigger and Effect Binding](#trigger-and-effect-binding) - [Combining Effects](#combining-effects) +- [Parameter Standards](#parameter-standards) +- [Available Presets](#available-presets) +- [Selection by Tone](#selection-by-tone) +- [Selection by Use Case](#selection-by-use-case) +- [Cross-Category Parallels](#cross-category-parallels) - [Accessibility](#accessibility) ## Terminology @@ -25,112 +28,36 @@ description: Entry point for selecting and configuring Interact motion presets. A preset is a named effect. "Preset" is used when talking about selection and configuration; "effect" when talking about the Interact runtime; "animation" when referring to the visual motion or CSS/WAAPI mechanism. -## Decision Flow - -1. **Select Category** - What kind of effect? (entrance, scroll, ongoing, mouse) -2. **Select Preset** - Which visual effect matches the intent? -3. **Configure Parameters** - Customize direction, intensity, timing, etc. - -### Quick Category Lookup - -| User Intent | Category | Notes | -| -------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- | -| "animate when element enters viewport", "reveal on scroll into view" | entrance | Optimized for `viewEnter`; also works with hover, click, animationEnd | -| "animate based on scroll position", "parallax", "scroll-driven" | scroll | Animation progress tied to element's position in the viewport | -| "always moving", "pulsing", "loading spinner", "continuous loop" | ongoing | Runs indefinitely until stopped | -| "react to mouse", "follow cursor", "tilt on hover" | mouse | Real-time response to cursor position; may behave differently on mobile | - ---- - ## Preset Categories -### Entrance - -One-shot animations optimized for viewport entry, but can also be triggered by hover, click, animationEnd, and other triggers. - -**When to use:** Element reveals on viewport entry, first-time visibility animations, click/hover-triggered transitions - -**When NOT to use:** Scroll-driven reveals → use scroll | Continuous/looping → use ongoing | Mouse-reactive → use mouse - -**Available presets:** FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn - -| Tone | Presets | -| ------------------- | ---------------------------------------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | -| Playful/Energetic | BounceIn, SpinIn | -| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | - -For full parameter details and examples, see [entrance-presets.md](entrance-presets.md). - -### Scroll - -Animations whose progress is tied to a ViewTimeline -- the element's position in the viewport. - -**When to use:** Progressive content reveals on scroll, parallax depth effects, storytelling tied to scroll progress, de-emphasizing passed content - -**When NOT to use:** One-time entrance → use entrance (more performant) | Continuous loops → use ongoing - -**Available presets:** ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll +| Category | Optimized For | Implementation | Notes | +| -------- | -------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- | +| entrance | When an element enters the viewport | `viewEnter` (intersection observer) | Can also be triggered by hover, click, animationend, and other triggers | +| scroll | Scroll position of an element relative to document | ViewTimeline (scroll progress) | Animation progress tied to element's position in the viewport | +| ongoing | Continuous loop | infinite CSS/WAAPI animation | Runs indefinitely until stopped | +| mouse | Follow or Repel by Pointer position | transform values driven by pointer position | Real-time response to cursor position; may behave differently on mobile | -**Scroll range modes:** +For full parameter details per category, see the dedicated reference files: -- `'in'`: animation ends at the element's idle state (element animates in as it enters) -- `'out'`: animation starts from the element's idle state (element animates out as it exits) -- `'continuous'`: animation passes through the idle state (animates across the full scroll range) +- [Entrance Presets](./entrance-presets.md) +- [Scroll Presets](./scroll-presets.md) +- [Ongoing Presets](./ongoing-presets.md) +- [Mouse Presets](./mouse-presets.md) -| Effect Type | Presets | -| ----------- | -------------------------------------------------- | -| Opacity | FadeScroll, BlurScroll | -| Movement | ParallaxScroll, MoveScroll, PanScroll, SlideScroll | -| Scale | GrowScroll, ShrinkScroll | -| 3D Rotation | ArcScroll, FlipScroll, TiltScroll, TurnScroll | -| Reveal/Mask | RevealScroll, ShapeScroll, ShuttersScroll | +## Trigger and Effect Binding -For full parameter details and examples, see [scroll-presets.md](scroll-presets.md). - -### Ongoing - -Continuous looping animations that run indefinitely. - -**When to use:** Loading/processing indicators, status indicators (live, active, recording), attention-drawing elements (notifications, CTAs), decorative ambient motion - -**When NOT to use:** Multiple simultaneous effects (visual chaos) | Content that needs to be read | One-time reveals → use entrance - -**Available presets:** Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle - -| Tone | Presets | -| -------------------- | --------------------------------------- | -| Subtle/Professional | Pulse (subtle), Breathe, Flash (subtle) | -| Playful/Energetic | Bounce, Wiggle, Jello, DVD | -| Mechanical/Technical | Spin, Flip, Fold | -| Attention-grabbing | Flash, Bounce, Pulse (hard), Poke | - -For full parameter details and examples, see [ongoing-presets.md](ongoing-presets.md). - -### Mouse - -Effects that respond to cursor position. May behave differently on mobile. - -**When to use:** Interactive cards/products (tilt effect), parallax depth with cursor, hero section interactivity, playful/game-like interfaces - -**When NOT to use:** Accessibility-critical interfaces | Essential functionality (never rely on mouse for core features) - -**Available presets:** AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse - -| Tone | Presets | -| -------------------- | -------------------------------------------- | -| Professional/Premium | Tilt3DMouse (subtle), TrackMouse, ScaleMouse | -| Playful/Fun | BounceMouse, BlobMouse, AiryMouse | -| Game-like/Dynamic | SpinMouse, Track3DMouse, SkewMouse | +In the simplest case, a trigger and its effect are bound to the same element. However, an effect on one element can also be triggered by another element (e.g., hovering a button triggers a FadeIn on a sibling panel). -For full parameter details and examples, see [mouse-presets.md](mouse-presets.md). +## Combining Effects ---- +1. Avoid mixing multiple effects on the same element at the same time when possible +2. Never combine effects that affect the same CSS properties (e.g., two effects both using `transform`) +3. When combining is necessary, effect order matters — later effects may override earlier ones +4. If possible, use nested containers to separate effects that would conflict — place each effect on a separate wrapper element. Note: here also order matters ## Parameter Standards -### Effect Options (Not Preset Parameters) +### Animation Options (Not Preset Parameters) These are set on the effect configuration level, not on the preset itself: @@ -142,7 +69,7 @@ These are set on the effect configuration level, not on the preset itself: - `fill`: Animation fill mode - `reversed`: Reverse the animation -**Scroll-specific effect options:** +**Scroll-specific animation options:** - `rangeStart` / `rangeEnd`: `RangeOffset` controlling when the scroll animation starts/ends - `transitionDuration` / `transitionDelay` / `transitionEasing`: Transition smoothing @@ -162,16 +89,16 @@ The `direction` parameter accepts different values depending on the preset: Interact supports both a CSSUnitValue-style object (e.g., `distance: { value: 120, type: 'px' }`, mapped to the internal type `UnitLengthPercentage`) and flat string values (e.g., `distance: '120px'`). -Prefer the object notation. In any case, be consistent within a configuration -- use one format, not both. +Prefer the object notation. Be consistent within a configuration — use one format, not both. ### Coordinate System -For angle-based parameters: +**Standard:** 0° = right (east), angles increase counter-clockwise -- **0°** = right (east) -- **90°** = top (north) -- **180°** = left (west) -- **270°** = bottom (south) +- 0° = right (east) +- 90° = top (north) +- 180° = left (west) +- 270° = bottom (south) ### Distance Units @@ -189,15 +116,33 @@ The library uses these CSS custom properties for runtime control: - `--motion-rotate`: Element rotation (used by SpinIn and other rotation presets) -### Trigger and Effect Binding +## Available Presets -In the simplest case, a trigger and its effect are bound to the same element. However, an effect on one element can also be triggered by another element (e.g., hovering a button triggers a FadeIn on a sibling panel). +### Entrance (19 presets) ---- +FadeIn, ArcIn, BlurIn, BounceIn, CurveIn, DropIn, ExpandIn, FlipIn, FloatIn, FoldIn, GlideIn, RevealIn, ShapeIn, ShuttersIn, SlideIn, SpinIn, TiltIn, TurnIn, WinkIn + +→ [Full entrance preset reference](./entrance-presets.md) + +### Scroll (19 presets) + +ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, TurnScroll + +→ [Full scroll preset reference](./scroll-presets.md) + +### Ongoing (14 presets) + +Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin, Swing, Wiggle + +→ [Full ongoing preset reference](./ongoing-presets.md) + +### Mouse (12 presets) + +AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse -## Selection Tables +→ [Full mouse preset reference](./mouse-presets.md) -### By Tone +## Selection by Tone | Tone | Entrance | Scroll | Ongoing | Mouse | | ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | @@ -206,7 +151,7 @@ In the simplest case, a trigger and its effect are bound to the same element. Ho | Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | | Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | -### By Use Case +## Selection by Use Case | Use Case | Recommended Presets | | ---------------------- | ---------------------------------------------- | @@ -220,9 +165,7 @@ In the simplest case, a trigger and its effect are bound to the same element. Ho | Product images | Tilt3DMouse, ScaleMouse | | Background depth | ParallaxScroll, TrackMouse (layered) | -### Cross-Category Parallels - -Effects with similar visual results across categories: +## Cross-Category Parallels | Entrance | Scroll | Ongoing | Mouse | | -------- | -------------- | ------- | ----------- | @@ -238,61 +181,18 @@ Effects with similar visual results across categories: | RevealIn | RevealScroll | - | - | | - | ParallaxScroll | - | TrackMouse | ---- - -## Combining Effects - -1. Avoid mixing multiple effects on the same element at the same time when possible -2. Never combine effects that affect the same CSS properties (e.g., two effects both using `transform`) -3. When combining is necessary, effect order matters -- later effects may override earlier ones -4. If possible, use nested containers to separate effects that would conflict -- place each effect on a separate wrapper element. Note: here also order matters - -### Common Patterns - -**Card reveal on scroll:** - -```typescript -{ type: 'FadeScroll', range: 'in' } -``` - -**Interactive product card (nested containers):** - -```typescript -// Outer container - entrance -{ type: 'FadeIn' } -// Inner container - mouse interaction -{ type: 'Tilt3DMouse', angle: 25, perspective: 1000 } -``` - -**Notification badge:** - -```typescript -{ type: 'BounceIn', direction: 'top', distanceFactor: 1 } -{ type: 'Pulse', intensity: 0.5 } -``` - -**Loading indicator:** - -```typescript -{ type: 'Spin', direction: 'clockwise' } -``` - ---- - ## Accessibility ### Host vs Preset Responsibility -The presets generally provide animations; the host platform decides when/whether to apply them. +The presets provide animations; the host platform decides when/whether to apply them. Interact supports `conditions` in the config for handling reduced motion. Define a media condition for `(prefers-reduced-motion: reduce)` and use it to swap high-risk presets for safer alternatives (e.g., SpinIn → FadeIn, BounceIn → FadeIn). Conditions can be applied per-interaction or per-effect, and automatically re-evaluate when the user's preference changes. -If it is known that the host handles accessibility globally (e.g., disabling all animations on `(prefers-reduced-motion: reduce)`), presets don't need to address it separately. +If the host handles accessibility globally (e.g., disabling all animations on `(prefers-reduced-motion: reduce)`), presets don't need to address it separately. ### Preset Risk Levels -_Note:_ this section should be confirmed by an a11y expert - **High risk** (vestibular triggers, seizure risk if motion is fast and repetitive): - Spinning: SpinIn, Spin, SpinScroll, SpinMouse, Spin3dScroll @@ -325,8 +225,8 @@ _Note:_ this section should be confirmed by an a11y expert ### LLM Guidance Principles -1. **Do not limit creativity by default** -- generate what the user asks for -2. **Apply constraints only when explicitly requested** -- keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" -3. **High-risk presets are informational, not blockers** -- optionally note vestibular concerns in response -4. **Mouse presets may behave differently on mobile** -- note this as context, not a restriction -5. **Duration guidelines are suggestions** -- functional UI <500ms, decorative up to 1200ms, hero up to 2000ms +1. **Do not limit creativity by default** — generate what the user asks for +2. **Apply constraints only when explicitly requested** — keywords: "accessible", "a11y", "reduced motion safe", "subtle", "tone down" +3. **High-risk presets are informational, not blockers** — optionally note vestibular concerns in response +4. **Mouse presets may behave differently on mobile** — note this as context, not a restriction +5. **Duration guidelines are suggestions** — functional UI <500ms, decorative up to 1200ms, hero up to 2000ms diff --git a/packages/motion-presets/rules/presets/scroll-presets.md b/packages/motion-presets/rules/presets/scroll-presets.md index 0aa247d8..3b627398 100644 --- a/packages/motion-presets/rules/presets/scroll-presets.md +++ b/packages/motion-presets/rules/presets/scroll-presets.md @@ -1,319 +1,367 @@ --- -name: scroll-presets-reference -description: Full parameter details, examples, and intensity guide for scroll presets. Read when configuring specific scroll preset parameters or choosing intensity levels for scroll-driven animations. -category: scroll +name: scroll-presets +description: Full parameter reference for scroll motion presets. Read when configuring ArcScroll, BlurScroll, FadeScroll, FlipScroll, GrowScroll, MoveScroll, PanScroll, ParallaxScroll, RevealScroll, ShapeScroll, ShrinkScroll, ShuttersScroll, SkewPanScroll, SlideScroll, Spin3dScroll, SpinScroll, StretchScroll, TiltScroll, or TurnScroll scroll animations. --- # Scroll Presets -All scroll preset parameters and TypeScript examples. For category overview and selection guidance, see [presets-main.md](presets-main.md). +Scroll presets tie animation progress to an element's scroll position relative to the viewport. They use ViewTimeline (scroll-driven animations) so the effect advances as the user scrolls. ## Table of Contents -- [Preset Reference](#preset-reference) -- [Intensity Values](#intensity-values) +- [Scroll Range](#scroll-range) +- [ArcScroll](#arcscroll) +- [BlurScroll](#blurscroll) +- [FadeScroll](#fadescroll) +- [FlipScroll](#flipscroll) +- [GrowScroll](#growscroll) +- [MoveScroll](#movescroll) +- [PanScroll](#panscroll) +- [ParallaxScroll](#parallaxscroll) +- [RevealScroll](#revealscroll) +- [ShapeScroll](#shapescroll) +- [ShrinkScroll](#shrinkscroll) +- [ShuttersScroll](#shuttersscroll) +- [SkewPanScroll](#skewpanscroll) +- [SlideScroll](#slidescroll) +- [Spin3dScroll](#spin3dscroll) +- [SpinScroll](#spinscroll) +- [StretchScroll](#stretchscroll) +- [TiltScroll](#tiltscroll) +- [TurnScroll](#turnscroll) - [Optional Parameters](#optional-parameters) +- [Intensity Value Guide](#intensity-value-guide) -All scroll presets accept a `range` parameter: +--- -- `'in'`: animation ends at the element's idle state (element animates in as it enters) -- `'out'`: animation starts from the element's idle state (element animates out as it exits) -- `'continuous'`: animation passes through the idle state (animates across the full scroll range) +## Scroll Range ---- +Most scroll presets accept a `range` parameter: -## Preset Reference +- `'in'`: Animation ends at the element's idle state (element animates in as it enters) +- `'out'`: Animation starts from the element's idle state (element animates out as it exits) +- `'continuous'`: Animation passes through the idle state (animates across the full scroll range) + +--- ### ArcScroll -Visual: 3D arc rotation as user scrolls. Dramatic, cinematic. +Visual: Element rotates along a 3D arc as it scrolls into or out of view. Parameters: -- `direction`: 'vertical' | 'horizontal' (default: 'horizontal') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `perspective`: number (default: 500) +- `direction`: 'vertical' | 'horizontal' (default: `'horizontal'`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) +- `perspective`: number — 3D perspective in px (default: `500`) ```typescript -{ type: 'ArcScroll', direction: 'vertical' } -{ type: 'ArcScroll', direction: 'horizontal', range: 'in' } +{ type: 'ArcScroll', direction: 'vertical', range: 'continuous' } ``` +--- + ### BlurScroll -Visual: Blur/unblur effect controlled by scroll. Focus transitions. +Visual: Element blurs or unblurs as it scrolls through the viewport. Parameters: -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `blur`: number in px (default: 6) +- `blur`: number — maximum blur amount in px (default: `6`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'BlurScroll', range: 'in' } -{ type: 'BlurScroll', range: 'out', blur: 50 } +{ type: 'BlurScroll', blur: 25, range: 'out' } ``` +--- + ### FadeScroll -Visual: Opacity transition tied to scroll. Fade in on enter, out on exit. +Visual: Element fades in or out based on scroll position. Parameters: -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `opacity`: number 0-1 (default: 0) +- `opacity`: number — target opacity at the animated end (default: `0`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'FadeScroll', range: 'in' } -{ type: 'FadeScroll', range: 'out' } +{ type: 'FadeScroll', range: 'continuous' } ``` +--- + ### FlipScroll -Visual: Full 3D card flip driven by scroll. Dramatic rotation. +Visual: Element performs a 3D flip rotation as it scrolls. Parameters: -- `direction`: 'vertical' | 'horizontal' (default: 'horizontal') -- `range`: 'in' | 'out' | 'continuous' (default: 'continuous') -- `rotate`: number in degrees (default: 240) -- `perspective`: number (default: 800) +- `direction`: 'vertical' | 'horizontal' (default: `'horizontal'`) +- `rotate`: number — rotation amount in degrees (default: `240`) +- `range`: 'in' | 'out' | 'continuous' (default: `'continuous'`) +- `perspective`: number — 3D perspective in px (default: `800`) ```typescript -{ type: 'FlipScroll', direction: 'horizontal' } -{ type: 'FlipScroll', direction: 'vertical', range: 'in', rotate: 420 } +{ type: 'FlipScroll', rotate: 360, direction: 'vertical' } ``` +--- + ### GrowScroll -Visual: Scale up as element enters viewport. +Visual: Element scales up from a direction as it scrolls into view. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' (default: 'center') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `scale`: number (default: varies by range) -- `speed`: number (default: 0) +- `direction`: EffectNineDirections — origin point for scaling (default: `'center'`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) +- `scale`: number — starting/ending scale (default: `0` for 'in', `4` for 'out') +- `speed`: number — vertical movement factor (default: `0`) ```typescript -{ type: 'GrowScroll', direction: 'center' } -{ type: 'GrowScroll', direction: 'center', range: 'in', scale: 4 } +{ type: 'GrowScroll', direction: 'top-left', scale: 0.5 } ``` +--- + ### MoveScroll -Visual: Translation movement on scroll in any direction. +Visual: Element translates along an angle for a given distance as it scrolls. Parameters: -- `angle`: 0-360 degrees (default: 120). 0° = right, 90° = top, 180° = left, 270° = bottom -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `distance`: UnitLengthPercentage (default: { value: 400, type: 'px' }) +- `angle`: number — movement angle in degrees, 0° = right (default: `120`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) +- `distance`: UnitLengthPercentage — travel distance (default: `{ value: 400, unit: 'px' }`) ```typescript -{ type: 'MoveScroll', angle: 90, distance: { value: 100, type: 'px' } } -{ type: 'MoveScroll', angle: 0, distance: { value: 800, type: 'px' } } +{ type: 'MoveScroll', angle: 90, distance: { value: 200, type: 'px' } } ``` +--- + ### PanScroll -Visual: Horizontal panning tied to scroll. +Visual: Element pans horizontally across the viewport as it scrolls. Parameters: -- `direction`: 'left' | 'right' (default: 'left') -- `distance`: UnitLengthPercentage (default: { value: 400, type: 'px' }) -- `startFromOffScreen`: boolean (default: true) -- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `direction`: 'left' | 'right' (default: `'left'`) +- `distance`: UnitLengthPercentage — pan distance (default: `{ value: 400, unit: 'px' }`) +- `startFromOffScreen`: boolean — whether to start from off-screen (default: `true`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'PanScroll', direction: 'left', distance: { value: 200, type: 'px' } } +{ type: 'PanScroll', direction: 'right', startFromOffScreen: false } ``` +--- + ### ParallaxScroll -Visual: Element moves slower/faster than scroll, creating depth illusion. +Visual: Element moves at a different speed than the scroll, creating a depth illusion. Parameters: -- `parallaxFactor`: number (default: 0.5) - movement speed relative to scroll +- `parallaxFactor`: number — speed multiplier relative to scroll (default: `0.5`) - `range`: 'in' | 'out' | 'continuous' ```typescript -{ type: 'ParallaxScroll' } -{ type: 'ParallaxScroll', parallaxFactor: 0.3 } +{ type: 'ParallaxScroll', parallaxFactor: 0.8 } ``` +--- + ### RevealScroll -Visual: Clip-based directional reveal on scroll. +Visual: Element is progressively revealed from an edge via clip-path as it scrolls. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'bottom') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'bottom'`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'RevealScroll', direction: 'left' } -{ type: 'RevealScroll', direction: 'bottom', range: 'in' } +{ type: 'RevealScroll', direction: 'left', range: 'continuous' } ``` +--- + ### ShapeScroll -Visual: Shape mask reveal controlled by scroll. +Visual: Element is revealed through an expanding geometric clip-path shape on scroll. Parameters: -- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' (default: 'circle') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `intensity`: number 0-1 (default: 0.5) +- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' (default: `'circle'`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) +- `intensity`: number — shape size factor (default: `0.5`) ```typescript -{ type: 'ShapeScroll', shape: 'circle' } -{ type: 'ShapeScroll', shape: 'diamond', intensity: 0.8 } +{ type: 'ShapeScroll', shape: 'diamond', range: 'out' } ``` +--- + ### ShrinkScroll -Visual: Scale down as element exits viewport. +Visual: Element shrinks toward a direction as it scrolls, the inverse of GrowScroll. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' (default: 'center') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `scale`: number (default: varies by range) -- `speed`: number (default: 0) +- `direction`: EffectNineDirections — shrink origin (default: `'center'`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) +- `scale`: number — target scale (default: `1.2` for 'in', `0.8` for 'out') +- `speed`: number — vertical movement factor (default: `0`) ```typescript -{ type: 'ShrinkScroll', direction: 'center', range: 'out' } -{ type: 'ShrinkScroll', direction: 'center', scale: 0 } +{ type: 'ShrinkScroll', direction: 'bottom', scale: 0.5 } ``` +--- + ### ShuttersScroll -Visual: Venetian blind strips revealing on scroll. +Visual: Element is revealed through shutter-like strips that open on scroll. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'right') -- `shutters`: number of strips (default: 12) -- `staggered`: boolean (default: true) -- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'right'`) +- `shutters`: number — number of shutter segments (default: `12`) +- `staggered`: boolean — whether shutters open in a staggered pattern (default: `true`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'ShuttersScroll', direction: 'left', shutters: 5, staggered: true } +{ type: 'ShuttersScroll', shutters: 6, range: 'continuous' } ``` +--- + ### SkewPanScroll -Visual: Panning with skew distortion effect. +Visual: Element pans horizontally with a skew distortion as it scrolls. Parameters: -- `direction`: 'left' | 'right' (default: 'right') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `skew`: number in degrees (default: 10) +- `direction`: 'left' | 'right' (default: `'right'`) +- `skew`: number — skew angle in degrees (default: `10`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'SkewPanScroll', direction: 'left' } -{ type: 'SkewPanScroll', direction: 'right', skew: 24 } +{ type: 'SkewPanScroll', skew: 20, direction: 'left' } ``` +--- + ### SlideScroll -Visual: Slide movement tied to scroll position. +Visual: Element slides in from an edge with a clip-path reveal as it scrolls. Parameters: -- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: 'bottom') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') +- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'bottom'`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'SlideScroll', direction: 'bottom' } -{ type: 'SlideScroll', direction: 'left', range: 'in' } +{ type: 'SlideScroll', direction: 'left', range: 'out' } ``` +--- + ### Spin3dScroll -Visual: 3D rotation around axis on scroll. +Visual: Element performs a 3D spin with rotation on multiple axes as it scrolls. Parameters: -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `rotate`: number in degrees (default: -100) -- `speed`: number (default: 0) -- `perspective`: number (default: 1000) +- `rotate`: number — rotation amount in degrees (default: `-100`) +- `speed`: number — vertical movement factor (default: `0`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) +- `perspective`: number — 3D perspective in px (default: `1000`) ```typescript -{ type: 'Spin3dScroll' } -{ type: 'Spin3dScroll', range: 'continuous', rotate: 200 } +{ type: 'Spin3dScroll', rotate: 200, perspective: 600 } ``` +--- + ### SpinScroll -Visual: 2D rotation driven by scroll. +Visual: Element spins (2D rotation) with optional scale change as it scrolls. Parameters: -- `direction`: 'clockwise' | 'counter-clockwise' (default: 'clockwise') -- `spins`: number of rotations (default: 0.15) -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `scale`: number (default: 1) +- `direction`: 'clockwise' | 'counter-clockwise' (default: `'clockwise'`) +- `spins`: number — number of full rotations (default: `0.15`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) +- `scale`: number — scale during spin (default: `1`) ```typescript -{ type: 'SpinScroll', direction: 'clockwise', spins: 1 } -{ type: 'SpinScroll', direction: 'counter-clockwise', spins: 2, scale: 0.4 } +{ type: 'SpinScroll', spins: 0.5, direction: 'counter-clockwise' } ``` +--- + ### StretchScroll -Visual: Stretch/squeeze deformation on scroll. +Visual: Element stretches vertically with scaleY increasing while scaleX decreases, with an opacity transition. Parameters: -- `range`: 'in' | 'out' | 'continuous' (default: 'out') -- `stretch`: number (default: 0.6) +- `stretch`: number — stretch factor (default: `0.6`) +- `range`: 'in' | 'out' | 'continuous' (default: `'out'`) ```typescript -{ type: 'StretchScroll' } -{ type: 'StretchScroll', stretch: 2 } +{ type: 'StretchScroll', stretch: 1.2, range: 'continuous' } ``` +--- + ### TiltScroll -Visual: 3D tilt effect as user scrolls. Subtle perspective. +Visual: Element tilts in 3D with optional parallax vertical movement as it scrolls. Parameters: -- `direction`: 'left' | 'right' (default: 'right') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `parallaxFactor`: number (default: 0) - tilt distance factor -- `perspective`: number (default: 400) +- `direction`: 'left' | 'right' (default: `'right'`) +- `parallaxFactor`: number — vertical movement factor (default: `0`) +- `perspective`: number — 3D perspective in px (default: `400`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'TiltScroll', direction: 'left' } -{ type: 'TiltScroll', direction: 'right', parallaxFactor: 1 } +{ type: 'TiltScroll', direction: 'left', parallaxFactor: 0.5 } ``` +--- + ### TurnScroll -Visual: Corner-pivot 3D rotation on scroll. +Visual: Element pans in from off-screen while turning (rotating) as it scrolls. Parameters: -- `direction`: 'left' | 'right' (default: 'right') -- `spin`: 'clockwise' | 'counter-clockwise' (default: 'clockwise') -- `range`: 'in' | 'out' | 'continuous' (default: 'in') -- `scale`: number (default: 1) -- `rotation`: number +- `direction`: 'left' | 'right' (default: `'right'`) +- `spin`: 'clockwise' | 'counter-clockwise' (default: `'clockwise'`) +- `scale`: number — scale during turn (default: `1`) +- `range`: 'in' | 'out' | 'continuous' (default: `'in'`) ```typescript -{ type: 'TurnScroll', direction: 'left', spin: 'clockwise' } -{ type: 'TurnScroll', direction: 'right', spin: 'counter-clockwise', scale: 1.6 } +{ type: 'TurnScroll', direction: 'left', spin: 'counter-clockwise' } ``` --- -## Intensity Values +## Optional Parameters + +### 3D Perspective + +| Preset | Parameter | Default | Range | +| ------------ | ------------- | ------- | -------- | +| FlipScroll | `perspective` | 800 | 200-2000 | +| TiltScroll | `perspective` | 400 | 200-2000 | +| Spin3dScroll | `perspective` | 1000 | 200-2000 | + +## Intensity Value Guide Tested values for different intensity levels. When a user asks for "soft", "subtle", "medium", or "hard"/"dramatic" motion, use these as guidelines. @@ -330,17 +378,3 @@ Tested values for different intensity levels. When a user asks for "soft", "subt | StretchScroll | stretch | 1.2 | 1.5 | 2 | | TiltScroll | distance | 0 | 0.5 | 1 | | TurnScroll | scale | 1 | 1.3 | 1.6 | - ---- - -## Optional Parameters - -These parameters are exposed but their defaults have been tuned for good visual results and rarely need adjustment. - -### 3D Perspective - -| Preset | Parameter | Default | Range | -| ------------ | ------------- | ------- | -------- | -| FlipScroll | `perspective` | 800 | 200-2000 | -| TiltScroll | `perspective` | 400 | 200-2000 | -| Spin3dScroll | `perspective` | 1000 | 200-2000 | From d96a85946d8a4eeaf1c64bb423a1dc473daadbc9 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Wed, 18 Feb 2026 21:02:04 +0200 Subject: [PATCH 18/20] moved presets plan to .cursor/plans --- .../plans/motion_presets_llm_rules.plan.md | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) rename packages/motion-presets/rules/presets/PLAN.md => .cursor/plans/motion_presets_llm_rules.plan.md (96%) diff --git a/packages/motion-presets/rules/presets/PLAN.md b/.cursor/plans/motion_presets_llm_rules.plan.md similarity index 96% rename from packages/motion-presets/rules/presets/PLAN.md rename to .cursor/plans/motion_presets_llm_rules.plan.md index 754b250c..d6ab3773 100644 --- a/packages/motion-presets/rules/presets/PLAN.md +++ b/.cursor/plans/motion_presets_llm_rules.plan.md @@ -1,9 +1,8 @@ --- name: LLM Preset Rules overview: Single source of truth for generating and maintaining all preset reference files. -status: in-progress -version: 3.0 -last-updated: 2026-02-18 +todos: [] +isProject: false --- # LLM Rules for Motion Presets @@ -28,8 +27,7 @@ This file is the **single source of truth** for generating all preset reference ## Generated Files ```text -rules/presets/ -├── PLAN.md # THIS FILE — source of truth, not read by LLM at runtime +packages/motion-presets/rules/presets/ ├── presets-main.md # Generated: entry point (<500 lines) — decision flow, categories, standards, selection, a11y ├── entrance-presets.md # Generated: full entrance preset params, examples, optional params, intensity ├── scroll-presets.md # Generated: full scroll preset params, examples, optional params, intensity @@ -107,9 +105,9 @@ A preset is a named effect. "Preset" is used when talking about selection and co ## Preset Registry -A list of the presets present in the project. Before continuing, make sure this list is aligned with `../src/library` and update accordingly. +A list of the presets present in the project. Before continuing, make sure this list is aligned with `packages/motion-presets/src/library` and update accordingly. -_Note:_ the descriptions should be verified by a designer +*Note:* the descriptions should be verified by a designer ### Entrance Presets @@ -337,7 +335,7 @@ If it is known that the host handles accessibility globally (e.g., disabling all ### Preset Risk Levels -_Note:_ this section should be confirmed by an a11y expert +*Note:* this section should be confirmed by an a11y expert **High risk** (vestibular triggers, seizure risk if motion is fast and repetitive): @@ -383,7 +381,7 @@ _Note:_ this section should be confirmed by an a11y expert ### Preset Selection By Tone -_Note:_ the descriptions should be verified by a designer +*Note:* the descriptions should be verified by a designer | Tone | Entrance | Scroll | Ongoing | Mouse | | ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | @@ -527,7 +525,7 @@ To regenerate the preset reference files: ### Step 1: Verify Registry -Ensure the Preset Registry (above) is aligned with actual preset files in `motion-presets/src/library/{category}/` (exclude index.ts and test files). +Ensure the Preset Registry (above) is aligned with actual preset files in `packages/motion-presets/src/library/{category}/` (exclude index.ts and test files). ### Step 2: Generate `presets-main.md` @@ -546,8 +544,8 @@ Build from these sections of this file: For each category (entrance, scroll, ongoing, mouse): -1. Read preset type definitions from `motion-presets/src/types.ts` -2. For each preset in that category, get params from `motion-presets/src/library/{category}/{Preset}.ts` +1. Read preset type definitions from `packages/motion-presets/src/types.ts` +2. For each preset in that category, get params from `packages/motion-presets/src/library/{category}/{Preset}.ts` 3. Write each preset entry using the **Preset Entry Format** above 4. Append the **Optional Parameters** tables relevant to that category 5. Append the **Intensity Value** table for that category from the Intensity Value Guide above @@ -560,4 +558,5 @@ For each category (entrance, scroll, ongoing, mouse): 3. Every file has a table of contents after the title 4. Every file has YAML frontmatter with `name` and `description` (see [Skills Compatibility](#skills-compatibility)) 5. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks -6. Verify no content duplication between PLAN.md and generated files (generated files should stand alone; PLAN.md is the source, not a supplement) +6. Verify no content duplication between this plan and generated files (generated files should stand alone; this plan is the source, not a supplement) + From 9ace0a8249f29b683723e1ce1b2c627508a100bb Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Wed, 18 Feb 2026 23:56:06 +0200 Subject: [PATCH 19/20] fixed lint --- .cursor/plans/motion_presets_llm_rules.plan.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.cursor/plans/motion_presets_llm_rules.plan.md b/.cursor/plans/motion_presets_llm_rules.plan.md index d6ab3773..0c896fc9 100644 --- a/.cursor/plans/motion_presets_llm_rules.plan.md +++ b/.cursor/plans/motion_presets_llm_rules.plan.md @@ -559,4 +559,3 @@ For each category (entrance, scroll, ongoing, mouse): 4. Every file has YAML frontmatter with `name` and `description` (see [Skills Compatibility](#skills-compatibility)) 5. Run `yarn format` on all generated markdown files to ensure they pass CI formatting checks 6. Verify no content duplication between this plan and generated files (generated files should stand alone; this plan is the source, not a supplement) - From fe091a9e1ff55e54bc65f8064e697b71cb5a88c2 Mon Sep 17 00:00:00 2001 From: Tom Bigelajzen Date: Thu, 26 Feb 2026 17:07:54 +0200 Subject: [PATCH 20/20] update preset rules: designer descriptions, atmosphere selection, code fixes - Add designer-approved descriptions as single source of truth in plan - Replace tone selection table with 8 atmosphere groups (designer content) - Replace use-case table with placement recommendations - Fix discrepancies from source: GlideIn angle, ArcScroll perspective, direction table - Expand cross-category parallels and overloaded direction table - Exclude CustomMouse, SpinMouse, BounceMouse from generated rules - Fix intensity values: ArcIn easing, FlipIn initialRotate - Regenerate all 5 files from cleaned plan Made-with: Cursor --- .../plans/motion_presets_llm_rules.plan.md | 414 ++++++++++++------ .../rules/presets/entrance-presets.md | 18 +- .../rules/presets/mouse-presets.md | 60 +-- .../rules/presets/ongoing-presets.md | 8 +- .../rules/presets/presets-main.md | 257 +++++++++-- .../rules/presets/scroll-presets.md | 11 +- 6 files changed, 524 insertions(+), 244 deletions(-) diff --git a/.cursor/plans/motion_presets_llm_rules.plan.md b/.cursor/plans/motion_presets_llm_rules.plan.md index 0c896fc9..6ed17606 100644 --- a/.cursor/plans/motion_presets_llm_rules.plan.md +++ b/.cursor/plans/motion_presets_llm_rules.plan.md @@ -107,91 +107,99 @@ A preset is a named effect. "Preset" is used when talking about selection and co A list of the presets present in the project. Before continuing, make sure this list is aligned with `packages/motion-presets/src/library` and update accordingly. -*Note:* the descriptions should be verified by a designer +Descriptions marked with **(designer)** are approved by design and should be used as-is in generated files. All other descriptions are derived and should follow the same style. + +### Excluded Presets + +The following presets exist in the library but should **not** be documented in the generated rules: + +- `CustomMouse` — fully custom callback, not a configurable preset +- `SpinMouse` — excluded by design +- `BounceMouse` — excluded by design ### Entrance Presets -| Preset | Notes | -| ---------- | -------------------------------------------------------- | -| FadeIn | Simple opacity transition | -| ArcIn | 3D arc rotation entry | -| BlurIn | Blur-to-clear transition | -| BounceIn | Bouncy entrance with overshoot | -| CurveIn | Curved path entry | -| DropIn | Drop from above with scale | -| ExpandIn | Scale + translate entry from edge | -| FlipIn | 3D flip rotation | -| FloatIn | Gentle floating entry | -| FoldIn | 3D fold unfold | -| GlideIn | Smooth directional slide (default: from left, angle 270) | -| RevealIn | Directional clip-path reveal | -| ShapeIn | Geometric shape clip-path reveal | -| ShuttersIn | Multi-segment reveal | -| SlideIn | Directional slide with clip | -| SpinIn | Rotation entry | -| TiltIn | 3D tilt entry | -| TurnIn | Corner-pivot rotation | -| WinkIn | Axis-based scale reveal | +| Preset | Description | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| FadeIn | Element fades in smoothly from fully transparent to fully opaque. | +| ArcIn | **(designer)** Element enters along a 3D arc path, rotating into view with depth motion. | +| BlurIn | **(designer)** Element transitions from blurred to sharp while fading in. | +| BounceIn | Element bounces into place from a direction with an elastic multi-step curve. | +| CurveIn | **(designer)** Element curves in with a 180° rotation and depth motion in a 3D space, creating a swinging arc entrance. | +| DropIn | **(designer)** Element shrinks down from a larger size to its final scale. | +| ExpandIn | Element expands from a point in a given direction, scaling from small to full size with a fade-in. | +| FlipIn | Element flips into view with a 3D rotation around the X or Y axis. | +| FloatIn | Element drifts gently into place from a direction with a fade-in. | +| FoldIn | Element unfolds from an edge, rotating around an axis at the edge as if hinged. | +| GlideIn | **(designer)** Element glides in smoothly from off-screen along a direction. | +| RevealIn | Element is progressively revealed by an expanding clip-path from one edge. | +| ShapeIn | Element appears through an expanding geometric clip-path shape. | +| ShuttersIn | Element is revealed through multiple shutter-like strips that open in sequence. | +| SlideIn | Element slides in from one side while being revealed with a clip-path mask. | +| SpinIn | Element spins into view while scaling from small to full size. | +| TiltIn | Element tilts in from the side with 3D rotation and a clip-path reveal. | +| TurnIn | Element rotates into view around a corner pivot point. | +| WinkIn | **(designer)** Element winks into view by expanding from its horizontal or vertical center, while being revealed with a clip-path. | ### Scroll Presets -| Preset | Notes | -| -------------- | ----------------------------- | -| ArcScroll | 3D arc on scroll | -| BlurScroll | Blur based on scroll | -| FadeScroll | Opacity on scroll | -| FlipScroll | 3D flip on scroll | -| GrowScroll | Scale up on scroll | -| MoveScroll | Translate on scroll | -| PanScroll | Horizontal pan on scroll | -| ParallaxScroll | Depth-based parallax | -| RevealScroll | Clip-path reveal on scroll | -| ShapeScroll | Shape clip-path on scroll | -| ShrinkScroll | Scale down on scroll | -| ShuttersScroll | Multi-segment on scroll | -| SkewPanScroll | Skew + pan on scroll | -| SlideScroll | Slide on scroll | -| Spin3dScroll | 3D spin on scroll | -| SpinScroll | 2D spin on scroll | -| StretchScroll | Stretch deformation on scroll | -| TiltScroll | 3D tilt on scroll | -| TurnScroll | Turn rotation on scroll | +| Preset | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ArcScroll | Element rotates along a 3D arc as it scrolls into or out of view. | +| BlurScroll | Element blurs or unblurs as it scrolls through the viewport. | +| FadeScroll | Element fades in or out based on scroll position. | +| FlipScroll | Element performs a 3D flip rotation as it scrolls. | +| GrowScroll | **(designer)** Element scales up from a direction as it scrolls into or out of view. | +| MoveScroll | Element translates along an angle for a given distance as it scrolls. | +| PanScroll | **(designer)** Horizontal panning tied to scroll. | +| ParallaxScroll | Element moves at a different speed than the scroll, creating a depth illusion. | +| RevealScroll | Element is progressively revealed from an edge via clip-path as it scrolls. | +| ShapeScroll | Element is revealed through an expanding geometric clip-path shape on scroll. | +| ShrinkScroll | **(designer)** Element shrinks toward a direction as it scrolls into or out of view, the inverse of GrowScroll. | +| ShuttersScroll | **(designer)** Element is revealed through staggered shutter-like strips that open on scroll in. When scrolling out, the element disappears with the same animation in reverse. | +| SkewPanScroll | Element pans horizontally with a skew distortion as it scrolls. | +| SlideScroll | Element slides in from an edge with a clip-path reveal as it scrolls. | +| Spin3dScroll | Element performs a 3D spin with rotation on multiple axes as it scrolls. | +| SpinScroll | Element spins (2D rotation) with optional scale change as it scrolls. | +| StretchScroll | Element stretches vertically with scaleY increasing while scaleX decreases, with an opacity transition. | +| TiltScroll | **(designer)** Element tilts in 3D and perspective, with optional parallax vertical movement as it scrolls into or out of view. | +| TurnScroll | Element pans in from off-screen while turning (rotating) as it scrolls. | ### Ongoing Presets -| Preset | Notes | -| ------- | ---------------------- | -| Bounce | Continuous bounce | -| Breathe | Gentle scale pulse | -| Cross | Cross-pattern movement | -| DVD | DVD screensaver bounce | -| Flash | Opacity flash | -| Flip | Continuous flip | -| Fold | Continuous fold | -| Jello | Jello wobble | -| Poke | Directional poke | -| Pulse | Scale pulse | -| Rubber | Rubber stretch | -| Spin | Continuous rotation | -| Swing | Pendulum swing | -| Wiggle | Shake wiggle | +| Preset | Description | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Bounce | Element bounces up and down with a natural multi-step curve, like a ball settling. | +| Breathe | Element gently moves back and forth along an axis, like a breathing motion. | +| Cross | **(designer)** Element moves across the screen from side to side, horizontally or vertically, until reaching the edge of the view and repeats. | +| DVD | **(designer)** Element bounces diagonally off the viewport edges like a DVD screensaver logo. No configurable parameters — uses viewport dimensions to calculate bounce paths. | +| Flash | Element blinks by rapidly cycling opacity from visible to invisible and back. | +| Flip | Element continuously flips with a full 360° 3D rotation. | +| Fold | Element folds at an edge using 3D rotation, like a page turning back and forth. | +| Jello | Element wobbles with a skew-based jello-like deformation. | +| Poke | **(designer)** Element makes two short, sharp translates in a direction back and forth, like being poked. | +| Pulse | **(designer)** Element pulses by subtly scaling up and down. | +| Rubber | Element stretches non-uniformly on X and Y axes, creating a rubber-band wobble. | +| Spin | Element rotates continuously around its center. | +| Swing | Element swings like a pendulum from a pivot at one edge. | +| Wiggle | Element shakes with combined rotation and vertical translation. | ### Mouse Presets -| Preset | Notes | -| ------------ | ------------------------ | -| AiryMouse | Light floating follow | -| BlobMouse | Blob-like scale response | -| BlurMouse | Blur on distance | -| BounceMouse | Bouncy follow | -| CustomMouse | Custom mouse effect | -| ScaleMouse | Scale on mouse | -| SkewMouse | Skew on mouse | -| SpinMouse | Spin on mouse | -| SwivelMouse | 3D swivel on mouse | -| Tilt3DMouse | 3D tilt on mouse | -| Track3DMouse | 3D tracking on mouse | -| TrackMouse | Direct mouse tracking | +| Preset | Description | +| ------------ | -------------------------------------------------------------------------------------------------------------------------- | +| AiryMouse | Element floats and rotates gently following the cursor, creating an airy, weightless feel. | +| BlobMouse | **(designer)** Element translates and scales non-uniformly following the cursor, creating a heavy liquid-like deformation. | +| BlurMouse | Element translates, tilts in 3D, scales, and blurs based on distance from the cursor. | +| BounceMouse | *(excluded from generated rules)* Element follows the cursor with an elastic, bouncy motion. | +| CustomMouse | *(excluded from generated rules)* Fully custom callback effect. | +| ScaleMouse | Element translates and scales uniformly following the cursor. | +| SkewMouse | Element translates and skews following the cursor, creating a directional distortion. | +| SpinMouse | *(excluded from generated rules)* Element rotates toward the cursor position. | +| SwivelMouse | Element tilts in 3D around a chosen pivot axis following the cursor. | +| Tilt3DMouse | Element tilts in 3D based on cursor position, rotating on X and Y axes from center. | +| Track3DMouse | Element translates and tilts in 3D following the cursor, combining movement with perspective rotation. | +| TrackMouse | Element follows the cursor with direct translation, no rotation. | --- @@ -253,12 +261,19 @@ These are set on the effect configuration level, not on the preset itself: The `direction` parameter accepts different values depending on the preset: -| Meaning | Accepted Values | Presets | -| ------------------ | ------------------------------------------------------ | -------------------------------- | -| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | -| Cardinal + center | 'top', 'right', 'bottom', 'left', 'center' | BounceIn | -| Corner direction | 'top-left', 'top-right', 'bottom-left', 'bottom-right' | TurnIn | -| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | +| Meaning | Accepted Values | Presets | +| ------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| Cardinal | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn, RevealIn, ShuttersIn, Poke, Swing, Fold, RevealScroll, ShuttersScroll, SlideScroll | +| Cardinal + center | 'top', 'right', 'bottom', 'left', 'center' | BounceIn | +| Two sides | 'left', 'right' | TiltIn, PanScroll, SkewPanScroll, TiltScroll, TurnScroll | +| Two sides + pseudo | 'left', 'right', 'pseudoLeft', 'pseudoRight' | CurveIn | +| Corner | 'top-left', 'top-right', 'bottom-left', 'bottom-right' | TurnIn | +| Eight directions | 4 cardinal + 4 diagonal | Cross | +| Nine directions | 4 cardinal + 4 diagonal + 'center' | GrowScroll, ShrinkScroll | +| Axis | 'horizontal', 'vertical' | WinkIn, ArcScroll, FlipScroll, Flip | +| Axis + center | 'horizontal', 'vertical', 'center' | Breathe | +| Rotation | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | +| Angle (number) | 0–360 (0° = right, 90° = top, 180° = left, 270° = bottom) | GlideIn, ExpandIn, MoveScroll | ### Using Units @@ -307,6 +322,7 @@ Some preset parameters are exposed, but their defaults have been tuned for good | FlipIn | `perspective` | 800 | 200-2000 | | CurveIn | `perspective` | 200 | 100-1000 | | BounceIn (center) | `perspective` | 800 | 200-2000 | +| ArcScroll | `perspective` | 500 | 200-2000 | | FlipScroll | `perspective` | 800 | 200-2000 | | TiltScroll | `perspective` | 400 | 200-2000 | | Spin3dScroll | `perspective` | 1000 | 200-2000 | @@ -339,8 +355,8 @@ If it is known that the host handles accessibility globally (e.g., disabling all **High risk** (vestibular triggers, seizure risk if motion is fast and repetitive): -- Spinning: SpinIn, Spin, SpinScroll, SpinMouse, Spin3dScroll -- Bouncing: BounceIn, Bounce, BounceMouse +- Spinning: SpinIn, Spin, SpinScroll, Spin3dScroll +- Bouncing: BounceIn, Bounce - 3D rotations: ArcIn, FlipIn, ArcScroll, FlipScroll, Tilt3DMouse - Continuous motion: Flash, DVD, Jello, Wiggle @@ -379,46 +395,198 @@ If it is known that the host handles accessibility globally (e.g., disabling all ## Selection Tables -### Preset Selection By Tone - -*Note:* the descriptions should be verified by a designer - -| Tone | Entrance | Scroll | Ongoing | Mouse | -| ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | -| Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | -| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | - -### Preset Selection By Use Case - -| Use Case | Recommended Presets | -| ---------------------- | ---------------------------------------------- | -| Hero sections | ArcIn, FloatIn, RevealIn | -| Modals/Popups | FadeIn, DropIn, ExpandIn, SlideIn | -| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | -| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | -| Notifications/Badges | BounceIn, DropIn + Pulse | -| CTAs/Buttons | BounceIn, ExpandIn + Pulse | -| Loading indicators | Spin, Pulse | -| Product images | Tilt3DMouse, ScaleMouse | -| Background depth | ParallaxScroll, TrackMouse (layered) | +### Selection by Atmosphere + +#### Playful / Fun / Whimsical + +Keywords: playful, fun, quirky, whimsical, lighthearted, bouncy, cheerful, cute, charming, goofy, jiggly, cheeky, springy, joyful, upbeat, poppy, friendly, casual, funky, groovy, surprising + +| Effect | Trigger | Preset | +| ------ | -------- | ----------- | +| Wink | entrance | WinkIn | +| Wiggle | loop | Wiggle | +| Jello | loop | Jello | +| Poke | loop | Poke | +| DVD | loop | DVD | +| Cross | loop | Cross | +| Spin | entrance | SpinIn | +| Spin | scroll | SpinScroll | +| Spin | loop | Spin | +| Flip | entrance | FlipIn | +| Flip | scroll | FlipScroll | +| Flip | loop | Flip | +| Bounce | entrance | BounceIn | +| Bounce | loop | Bounce | +| Swing | loop | Swing | +| Blob | mouse | BlobMouse | +| Rubber | loop | Rubber | +| Track | mouse | TrackMouse | +| Swivel | mouse | SwivelMouse | + +#### Smooth / Elegant / Refined + +Keywords: smooth, elegant, graceful, flowing, refined, sophisticated, polished, seamless, effortless, silky, controlled, classic, curved, rhythmic, continuous, circular, pendular, mesmerizing + +| Effect | Trigger | Preset | +| ------ | -------- | ------------ | +| Glide | entrance | GlideIn | +| Swivel | mouse | SwivelMouse | +| Turn | entrance | TurnIn | +| Turn | scroll | TurnScroll | +| Arc | entrance | ArcIn | +| Arc | scroll | ArcScroll | +| Slide | entrance | SlideIn | +| Slide | scroll | SlideScroll | +| Move | scroll | MoveScroll | +| Fold | entrance | FoldIn | +| Fold | loop | Fold | +| Shape | entrance | ShapeIn | +| Shape | scroll | ShapeScroll | +| Fade | entrance | FadeIn | +| Fade | scroll | FadeScroll | +| Blur | entrance | BlurIn | +| Blur | scroll | BlurScroll | +| Blur | mouse | BlurMouse | +| Float | entrance | FloatIn | +| Airy | mouse | AiryMouse | +| Pulse | loop | Pulse | +| Swing | loop | Swing | +| Shrink | entrance | DropIn | +| Shrink | scroll | ShrinkScroll | + +#### Bold / Energetic / Dynamic + +Keywords: bold, dynamic, energetic, fast, impactful, attention-grabbing, eye-catching, striking, lively, electric, bright, sharp, snappy, quick, welcoming, opening, confident, blooming, emerging + +| Effect | Trigger | Preset | +| -------- | -------- | -------------- | +| 3D spin | scroll | Spin3dScroll | +| Tilt | entrance | TiltIn | +| Tilt | scroll | TiltScroll | +| Resize | mouse | ScaleMouse | +| Spin | entrance | SpinIn | +| Spin | scroll | SpinScroll | +| Spin | loop | Spin | +| Flip | entrance | FlipIn | +| Flip | scroll | FlipScroll | +| Flip | loop | Flip | +| Shutters | entrance | ShuttersIn | +| Shutters | scroll | ShuttersScroll | +| Bounce | entrance | BounceIn | +| Bounce | loop | Bounce | +| Grow | scroll | GrowScroll | +| Flash | loop | Flash | +| Expand | entrance | ExpandIn | +| Stretch | scroll | StretchScroll | + +#### Soft / Gentle / Organic + +Keywords: soft, gentle, delicate, light, airy, breezy, wispy, floating, ethereal, dreamy, cloudy, hazy, atmospheric, gradual, subtle, calm, soothing, natural, zen, meditative, serene, relaxed, breathing, alive, organic + +| Effect | Trigger | Preset | +| ------- | -------- | ------------ | +| Breathe | loop | Breathe | +| Float | entrance | FloatIn | +| Airy | mouse | AiryMouse | +| Blur | entrance | BlurIn | +| Blur | scroll | BlurScroll | +| Blur | mouse | BlurMouse | +| Fade | entrance | FadeIn | +| Fade | scroll | FadeScroll | +| Pulse | loop | Pulse | +| Shrink | entrance | DropIn | +| Shrink | scroll | ShrinkScroll | +| Expand | entrance | ExpandIn | + +#### Dramatic / Cinematic / Theatrical + +Keywords: dramatic, cinematic, theatrical, staged, sweeping, intimate, focused, detailed, revealing + +| Effect | Trigger | Preset | +| -------- | -------- | -------------- | +| Shutters | entrance | ShuttersIn | +| Shutters | scroll | ShuttersScroll | +| Parallax | scroll | ParallaxScroll | +| Expand | entrance | ExpandIn | +| Reveal | entrance | RevealIn | +| Reveal | scroll | RevealScroll | + +#### Modern / Tech / Immersive + +Keywords: modern, tech, immersive, dimensional, spatial, 3d, depth, layered, innovative, interactive, responsive, engaging, following + +| Effect | Trigger | Preset | +| -------- | -------- | -------------- | +| Tilt 3D | mouse | Tilt3DMouse | +| Track3D | mouse | Track3DMouse | +| Track | mouse | TrackMouse | +| Skew | mouse | SkewMouse | +| 3D spin | scroll | Spin3dScroll | +| Parallax | scroll | ParallaxScroll | +| Resize | mouse | ScaleMouse | +| Blur | entrance | BlurIn | +| Blur | scroll | BlurScroll | +| Blur | mouse | BlurMouse | +| Fold | entrance | FoldIn | +| Fold | loop | Fold | + +#### Creative / Experimental / Edgy + +Keywords: creative, artistic, experimental, unconventional, edgy, distorted, unique, expressive, graphic, transformative, fluid, liquid, elastic, flexible, stretchy + +| Effect | Trigger | Preset | +| ------- | -------- | ------------- | +| Skew | mouse | SkewMouse | +| Tilt | entrance | TiltIn | +| Tilt | scroll | TiltScroll | +| Shape | entrance | ShapeIn | +| Shape | scroll | ShapeScroll | +| Blob | mouse | BlobMouse | +| Cross | loop | Cross | +| Stretch | scroll | StretchScroll | +| Rubber | loop | Rubber | + +#### Clean / Professional / Minimal + +Keywords: clean, structured, organized, directional, purposeful, direct, simple, straightforward, progressive, minimalist, precise, understated, professional + +| Effect | Trigger | Preset | +| ------ | -------- | ------------ | +| Slide | entrance | SlideIn | +| Slide | scroll | SlideScroll | +| Move | scroll | MoveScroll | +| Fold | entrance | FoldIn | +| Fold | loop | Fold | +| Reveal | entrance | RevealIn | +| Reveal | scroll | RevealScroll | +| Shrink | entrance | DropIn | +| Shrink | scroll | ShrinkScroll | + +### Preset Selection Recommendations + +1. Do not add entrance presets (or any animation that starts with opacity 0) to `

` elements in the first fold +2. Do not add scroll-in animations in the first fold +3. Do not add scroll-out animations in the last fold ### Cross-Category Parallels -| Entrance | Scroll | Ongoing | Mouse | -| -------- | -------------- | ------- | ----------- | -| FadeIn | FadeScroll | Flash | - | -| ArcIn | ArcScroll | - | - | -| SpinIn | SpinScroll | Spin | SpinMouse | -| BounceIn | - | Bounce | BounceMouse | -| TiltIn | TiltScroll | - | Tilt3DMouse | -| FlipIn | FlipScroll | Flip | - | -| ExpandIn | GrowScroll | Pulse | ScaleMouse | -| SlideIn | SlideScroll | - | TrackMouse | -| BlurIn | BlurScroll | - | BlurMouse | -| RevealIn | RevealScroll | - | - | -| - | ParallaxScroll | - | TrackMouse | +| Entrance | Scroll | Ongoing | Mouse | +| ---------- | -------------- | ------- | ----------- | +| FadeIn | FadeScroll | Flash | - | +| ArcIn | ArcScroll | - | - | +| SpinIn | SpinScroll | Spin | - | +| BounceIn | - | Bounce | - | +| TiltIn | TiltScroll | - | Tilt3DMouse | +| FlipIn | FlipScroll | Flip | - | +| FoldIn | - | Fold | - | +| ExpandIn | GrowScroll | Pulse | ScaleMouse | +| SlideIn | SlideScroll | - | TrackMouse | +| BlurIn | BlurScroll | - | BlurMouse | +| RevealIn | RevealScroll | - | - | +| ShapeIn | ShapeScroll | - | - | +| ShuttersIn | ShuttersScroll | - | - | +| TurnIn | TurnScroll | - | - | +| - | ParallaxScroll | - | TrackMouse | --- @@ -430,11 +598,11 @@ Tested values for different intensity levels of effects. When a user asks for "s | Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | | -------- | ---------------- | ----------- | ---------- | ------------- | -| ArcIn | easing | cubicInOut | quintInOut | backOut | +| ArcIn | easing | sineOut | cubicInOut | quintInOut | | BlurIn | blur | 6px | 25px | 50px | | BounceIn | distanceFactor | 1 | 2 | 3 | | DropIn | initialScale | 1.2 | 1.6 | 2 | -| FlipIn | initialRotate | 45° | 90° | 270° | +| FlipIn | initialRotate | 35° | 60° | 90° | | FoldIn | initialRotate | 35° | 60° | 90° | | ExpandIn | initialScale | 0.8 | 0.6 | 0 | | SlideIn | initialTranslate | 0.2 | 0.8 | 1 | @@ -487,7 +655,7 @@ Tested values for different intensity levels of effects. When a user asks for "s When a user asks: "I want a subtle flip entrance" -Suggest: `{ type: 'FlipIn', initialRotate: 45 }` +Suggest: `{ type: 'FlipIn', initialRotate: 35 }` --- @@ -498,7 +666,7 @@ For each preset in the per-category reference files (`{category}-presets.md`): ```markdown ### PresetName -Visual: [1-2 sentences describing what user SEES, (should later be verified by a designer)] +Visual: [Use the description from the Preset Registry. Designer-approved descriptions must be used as-is.] Parameters: @@ -534,7 +702,7 @@ Build from these sections of this file: - **Terminology** → Terminology section - **Key Constraints** (categories table, trigger binding, combining effects) → Categories + Decision Flow + Combining Effects - **Parameter Standards** (all subsections) → Parameter Standards section -- **Selection Tables** (by tone, by use case, cross-category parallels) → Selection Tables section +- **Selection Tables** (by atmosphere, recommendations, cross-category parallels) → Selection Tables section - **Accessibility** (all subsections) → Accessibility section - **Preset Registry** → Available preset lists per category - Add progressive disclosure links to each `{category}-presets.md` diff --git a/packages/motion-presets/rules/presets/entrance-presets.md b/packages/motion-presets/rules/presets/entrance-presets.md index c6eb9fa9..49517cf1 100644 --- a/packages/motion-presets/rules/presets/entrance-presets.md +++ b/packages/motion-presets/rules/presets/entrance-presets.md @@ -49,7 +49,7 @@ Parameters: None — this preset has no configurable parameters. ### ArcIn -Visual: Element enters along a 3D arc path, rotating into view with depth motion and a fade-in. +Visual: Element enters along a 3D arc path, rotating into view with depth motion. Parameters: @@ -65,7 +65,7 @@ Parameters: ### BlurIn -Visual: Element transitions from blurred to clear while fading in. +Visual: Element transitions from blurred to sharp while fading in. Parameters: @@ -95,7 +95,7 @@ Parameters: ### CurveIn -Visual: Element curves in with a 180° rotation and depth motion, creating a swinging arc entrance. +Visual: Element curves in with a 180° rotation and depth motion in a 3D space, creating a swinging arc entrance. Parameters: @@ -111,7 +111,7 @@ Parameters: ### DropIn -Visual: Element drops in from above, scaling down from a larger size to its final scale. +Visual: Element shrinks down from a larger size to its final scale. Parameters: @@ -187,7 +187,7 @@ Parameters: ### GlideIn -Visual: Element glides in smoothly from off-screen along a direction with a fade-in. +Visual: Element glides in smoothly from off-screen along a direction. Parameters: @@ -307,7 +307,7 @@ Parameters: ### WinkIn -Visual: Element winks into view by scaling along one axis while being revealed with a clip-path. +Visual: Element winks into view by expanding from its horizontal or vertical center, while being revealed with a clip-path. Parameters: @@ -348,11 +348,11 @@ Tested values for different intensity levels. When a user asks for "soft", "subt | Preset | Parameter | Subtle/Soft | Medium | Dramatic/Hard | | -------- | ---------------- | ----------- | ---------- | ------------- | -| ArcIn | easing | cubicInOut | quintInOut | backOut | +| ArcIn | easing | sineOut | cubicInOut | quintInOut | | BlurIn | blur | 6px | 25px | 50px | | BounceIn | distanceFactor | 1 | 2 | 3 | | DropIn | initialScale | 1.2 | 1.6 | 2 | -| FlipIn | initialRotate | 45° | 90° | 270° | +| FlipIn | initialRotate | 35° | 60° | 90° | | FoldIn | initialRotate | 35° | 60° | 90° | | ExpandIn | initialScale | 0.8 | 0.6 | 0 | | SlideIn | initialTranslate | 0.2 | 0.8 | 1 | @@ -362,4 +362,4 @@ Tested values for different intensity levels. When a user asks for "soft", "subt When a user asks: "I want a subtle flip entrance" -Suggest: `{ type: 'FlipIn', initialRotate: 45 }` +Suggest: `{ type: 'FlipIn', initialRotate: 35 }` diff --git a/packages/motion-presets/rules/presets/mouse-presets.md b/packages/motion-presets/rules/presets/mouse-presets.md index 22e4f42c..865b40de 100644 --- a/packages/motion-presets/rules/presets/mouse-presets.md +++ b/packages/motion-presets/rules/presets/mouse-presets.md @@ -1,11 +1,11 @@ --- name: mouse-presets -description: Full parameter reference for mouse motion presets. Read when configuring AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, or TrackMouse pointer-driven animations. +description: Full parameter reference for mouse motion presets. Read when configuring AiryMouse, BlobMouse, BlurMouse, ScaleMouse, SkewMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, or TrackMouse pointer-driven animations. --- # Mouse Presets -Mouse presets drive element transforms in real-time based on pointer position. The element responds to cursor movement with translation, rotation, scale, or other effects. All mouse presets (except CustomMouse) share the `inverted` base parameter. +Mouse presets drive element transforms in real-time based on pointer position. The element responds to cursor movement with translation, rotation, scale, or other effects. All mouse presets share the `inverted` base parameter. **Mobile note:** Mouse presets respond to pointer events. On touch devices, behavior may differ — the element responds to touch position rather than a persistent cursor, so effects may only activate during active touch. Consider this when designing for cross-device experiences. @@ -15,11 +15,8 @@ Mouse presets drive element transforms in real-time based on pointer position. T - [AiryMouse](#airymouse) - [BlobMouse](#blobmouse) - [BlurMouse](#blurmouse) -- [BounceMouse](#bouncemouse) -- [CustomMouse](#custommouse) - [ScaleMouse](#scalemouse) - [SkewMouse](#skewmouse) -- [SpinMouse](#spinmouse) - [SwivelMouse](#swivelmouse) - [Tilt3DMouse](#tilt3dmouse) - [Track3DMouse](#track3dmouse) @@ -30,7 +27,7 @@ Mouse presets drive element transforms in real-time based on pointer position. T ## Shared Parameters -These parameters are available on all mouse presets (except CustomMouse): +These parameters are available on all mouse presets: - `inverted`: boolean — reverses the movement/effect direction (default: `false`) @@ -61,7 +58,7 @@ Parameters: ### BlobMouse -Visual: Element translates and scales non-uniformly following the cursor, creating a blob-like deformation. +Visual: Element translates and scales non-uniformly following the cursor, creating a heavy liquid-like deformation. Parameters: @@ -77,7 +74,7 @@ Parameters: ### BlurMouse -Visual: Element translates, tilts in 3D, scales, and blurs based on distance from the cursor — the farther away, the stronger the blur and tilt. +Visual: Element translates, tilts in 3D, scales, and blurs based on distance from the cursor. Parameters: @@ -94,38 +91,6 @@ Parameters: --- -### BounceMouse - -Visual: Element follows the cursor with an elastic, bouncy motion. - -Parameters: - -- `inverted`: boolean (default: `false`) -- `distance`: UnitLengthPercentage — max translate distance (default: `{ value: 80, unit: 'px' }`) -- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) - -```typescript -{ type: 'BounceMouse', distance: { value: 120, type: 'px' } } -``` - ---- - -### CustomMouse - -Visual: Fully custom effect — behavior is defined by a provided callback function. - -Parameters: - -- `customEffect`: (target: HTMLElement, progress: Progress) => void — custom function receiving the target element and normalized cursor progress `{ x, y, v: { x, y }, active }` - -```typescript -{ - type: 'CustomMouse'; -} -``` - ---- - ### ScaleMouse Visual: Element translates and scales uniformly following the cursor. @@ -160,21 +125,6 @@ Parameters: --- -### SpinMouse - -Visual: Element rotates toward the cursor position. - -Parameters: - -- `inverted`: boolean (default: `false`) -- `axis`: 'both' | 'horizontal' | 'vertical' (default: `'both'`) - -```typescript -{ type: 'SpinMouse', axis: 'horizontal' } -``` - ---- - ### SwivelMouse Visual: Element tilts in 3D around a chosen pivot axis following the cursor. diff --git a/packages/motion-presets/rules/presets/ongoing-presets.md b/packages/motion-presets/rules/presets/ongoing-presets.md index bbfc8e27..1032a671 100644 --- a/packages/motion-presets/rules/presets/ongoing-presets.md +++ b/packages/motion-presets/rules/presets/ongoing-presets.md @@ -59,7 +59,7 @@ Parameters: ### Cross -Visual: Element moves in a cross-pattern to the edge of its container and back. +Visual: Element moves across the screen from side to side, horizontally or vertically, until reaching the edge of the view and repeats. Parameters: @@ -73,7 +73,7 @@ Parameters: ### DVD -Visual: Element bounces diagonally off its container edges like a DVD screensaver logo. No configurable parameters — uses container dimensions to calculate bounce paths. +Visual: Element bounces diagonally off the viewport edges like a DVD screensaver logo. No configurable parameters — uses viewport dimensions to calculate bounce paths. Parameters: None. @@ -145,7 +145,7 @@ Parameters: ### Poke -Visual: Element makes a short, sharp translate in a direction, like being poked. +Visual: Element makes two short, sharp translates in a direction back and forth, like being poked. Parameters: @@ -160,7 +160,7 @@ Parameters: ### Pulse -Visual: Element pulses by subtly scaling up and down, drawing attention. +Visual: Element pulses by subtly scaling up and down. Parameters: diff --git a/packages/motion-presets/rules/presets/presets-main.md b/packages/motion-presets/rules/presets/presets-main.md index 6f082a32..696dd4c3 100644 --- a/packages/motion-presets/rules/presets/presets-main.md +++ b/packages/motion-presets/rules/presets/presets-main.md @@ -1,6 +1,6 @@ --- name: motion-presets -description: Reference for selecting and configuring Interact motion presets. Read when applying entrance, scroll, ongoing, or mouse animations to elements, choosing presets by tone or use case, combining effects, or handling accessibility and reduced motion. +description: Reference for selecting and configuring Interact motion presets. Read when applying entrance, scroll, ongoing, or mouse animations to elements, choosing presets by atmosphere or tone, combining effects, or handling accessibility and reduced motion. --- # Motion Presets Reference @@ -13,8 +13,8 @@ description: Reference for selecting and configuring Interact motion presets. Re - [Combining Effects](#combining-effects) - [Parameter Standards](#parameter-standards) - [Available Presets](#available-presets) -- [Selection by Tone](#selection-by-tone) -- [Selection by Use Case](#selection-by-use-case) +- [Selection by Atmosphere](#selection-by-atmosphere) +- [Selection Recommendations](#selection-recommendations) - [Cross-Category Parallels](#cross-category-parallels) - [Accessibility](#accessibility) @@ -78,12 +78,19 @@ These are set on the effect configuration level, not on the preset itself: The `direction` parameter accepts different values depending on the preset: -| Meaning | Accepted Values | Presets | -| ------------------ | ------------------------------------------------------ | -------------------------------- | -| Cardinal direction | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn | -| Cardinal + center | 'top', 'right', 'bottom', 'left', 'center' | BounceIn | -| Corner direction | 'top-left', 'top-right', 'bottom-left', 'bottom-right' | TurnIn | -| Rotation direction | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | +| Meaning | Accepted Values | Presets | +| ------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| Cardinal | 'top', 'right', 'bottom', 'left' | FlipIn, FoldIn, SlideIn, FloatIn, RevealIn, ShuttersIn, Poke, Swing, Fold, RevealScroll, ShuttersScroll, SlideScroll | +| Cardinal + center | 'top', 'right', 'bottom', 'left', 'center' | BounceIn | +| Two sides | 'left', 'right' | TiltIn, PanScroll, SkewPanScroll, TiltScroll, TurnScroll | +| Two sides + pseudo | 'left', 'right', 'pseudoLeft', 'pseudoRight' | CurveIn | +| Corner | 'top-left', 'top-right', 'bottom-left', 'bottom-right' | TurnIn | +| Eight directions | 4 cardinal + 4 diagonal | Cross | +| Nine directions | 4 cardinal + 4 diagonal + 'center' | GrowScroll, ShrinkScroll | +| Axis | 'horizontal', 'vertical' | WinkIn, ArcScroll, FlipScroll, Flip | +| Axis + center | 'horizontal', 'vertical', 'center' | Breathe | +| Rotation | 'clockwise', 'counter-clockwise' | SpinIn, SpinScroll, Spin | +| Angle (number) | 0–360 (0° = right, 90° = top, 180° = left, 270° = bottom) | GlideIn, ExpandIn, MoveScroll | ### Using Units @@ -136,50 +143,204 @@ Bounce, Breathe, Cross, DVD, Flash, Flip, Fold, Jello, Poke, Pulse, Rubber, Spin → [Full ongoing preset reference](./ongoing-presets.md) -### Mouse (12 presets) +### Mouse (9 presets) -AiryMouse, BlobMouse, BlurMouse, BounceMouse, CustomMouse, ScaleMouse, SkewMouse, SpinMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse +AiryMouse, BlobMouse, BlurMouse, ScaleMouse, SkewMouse, SwivelMouse, Tilt3DMouse, Track3DMouse, TrackMouse → [Full mouse preset reference](./mouse-presets.md) -## Selection by Tone - -| Tone | Entrance | Scroll | Ongoing | Mouse | -| ------------------- | ---------------------------------------- | ----------------------------------------- | -------------------------- | -------------------------------- | -| Subtle/Professional | FadeIn, BlurIn, SlideIn, GlideIn, TiltIn | FadeScroll, BlurScroll | Pulse (subtle), Breathe | Tilt3DMouse (subtle), TrackMouse | -| Dramatic/Cinematic | ArcIn, FlipIn, TurnIn, FoldIn | ArcScroll, FlipScroll, TiltScroll | Flip, Fold | Track3DMouse | -| Playful/Energetic | BounceIn, SpinIn | SpinScroll, Spin3dScroll | Bounce, Wiggle, Jello, DVD | BounceMouse, BlobMouse | -| Geometric/Modern | ShapeIn, RevealIn, ShuttersIn, WinkIn | ShapeScroll, RevealScroll, ShuttersScroll | Cross | - | - -## Selection by Use Case - -| Use Case | Recommended Presets | -| ---------------------- | ---------------------------------------------- | -| Hero sections | ArcIn, FloatIn, RevealIn | -| Modals/Popups | FadeIn, DropIn, ExpandIn, SlideIn | -| List items (staggered) | FadeIn, SlideIn, GlideIn with increasing delay | -| Cards | FlipIn, ArcIn, TiltIn + FadeScroll (in/out) | -| Notifications/Badges | BounceIn, DropIn + Pulse | -| CTAs/Buttons | BounceIn, ExpandIn + Pulse | -| Loading indicators | Spin, Pulse | -| Product images | Tilt3DMouse, ScaleMouse | -| Background depth | ParallaxScroll, TrackMouse (layered) | +## Selection by Atmosphere + +### Playful / Fun / Whimsical + +Keywords: playful, fun, quirky, whimsical, lighthearted, bouncy, cheerful, cute, charming, goofy, jiggly, cheeky, springy, joyful, upbeat, poppy, friendly, casual, funky, groovy, surprising + +| Effect | Trigger | Preset | +| ------ | -------- | ----------- | +| Wink | entrance | WinkIn | +| Wiggle | loop | Wiggle | +| Jello | loop | Jello | +| Poke | loop | Poke | +| DVD | loop | DVD | +| Cross | loop | Cross | +| Spin | entrance | SpinIn | +| Spin | scroll | SpinScroll | +| Spin | loop | Spin | +| Flip | entrance | FlipIn | +| Flip | scroll | FlipScroll | +| Flip | loop | Flip | +| Bounce | entrance | BounceIn | +| Bounce | loop | Bounce | +| Swing | loop | Swing | +| Blob | mouse | BlobMouse | +| Rubber | loop | Rubber | +| Track | mouse | TrackMouse | +| Swivel | mouse | SwivelMouse | + +### Smooth / Elegant / Refined + +Keywords: smooth, elegant, graceful, flowing, refined, sophisticated, polished, seamless, effortless, silky, controlled, classic, curved, rhythmic, continuous, circular, pendular, mesmerizing + +| Effect | Trigger | Preset | +| ------ | -------- | ------------ | +| Glide | entrance | GlideIn | +| Swivel | mouse | SwivelMouse | +| Turn | entrance | TurnIn | +| Turn | scroll | TurnScroll | +| Arc | entrance | ArcIn | +| Arc | scroll | ArcScroll | +| Slide | entrance | SlideIn | +| Slide | scroll | SlideScroll | +| Move | scroll | MoveScroll | +| Fold | entrance | FoldIn | +| Fold | loop | Fold | +| Shape | entrance | ShapeIn | +| Shape | scroll | ShapeScroll | +| Fade | entrance | FadeIn | +| Fade | scroll | FadeScroll | +| Blur | entrance | BlurIn | +| Blur | scroll | BlurScroll | +| Blur | mouse | BlurMouse | +| Float | entrance | FloatIn | +| Airy | mouse | AiryMouse | +| Pulse | loop | Pulse | +| Swing | loop | Swing | +| Shrink | entrance | DropIn | +| Shrink | scroll | ShrinkScroll | + +### Bold / Energetic / Dynamic + +Keywords: bold, dynamic, energetic, fast, impactful, attention-grabbing, eye-catching, striking, lively, electric, bright, sharp, snappy, quick, welcoming, opening, confident, blooming, emerging + +| Effect | Trigger | Preset | +| -------- | -------- | -------------- | +| 3D spin | scroll | Spin3dScroll | +| Tilt | entrance | TiltIn | +| Tilt | scroll | TiltScroll | +| Resize | mouse | ScaleMouse | +| Spin | entrance | SpinIn | +| Spin | scroll | SpinScroll | +| Spin | loop | Spin | +| Flip | entrance | FlipIn | +| Flip | scroll | FlipScroll | +| Flip | loop | Flip | +| Shutters | entrance | ShuttersIn | +| Shutters | scroll | ShuttersScroll | +| Bounce | entrance | BounceIn | +| Bounce | loop | Bounce | +| Grow | scroll | GrowScroll | +| Flash | loop | Flash | +| Expand | entrance | ExpandIn | +| Stretch | scroll | StretchScroll | + +### Soft / Gentle / Organic + +Keywords: soft, gentle, delicate, light, airy, breezy, wispy, floating, ethereal, dreamy, cloudy, hazy, atmospheric, gradual, subtle, calm, soothing, natural, zen, meditative, serene, relaxed, breathing, alive, organic + +| Effect | Trigger | Preset | +| ------- | -------- | ------------ | +| Breathe | loop | Breathe | +| Float | entrance | FloatIn | +| Airy | mouse | AiryMouse | +| Blur | entrance | BlurIn | +| Blur | scroll | BlurScroll | +| Blur | mouse | BlurMouse | +| Fade | entrance | FadeIn | +| Fade | scroll | FadeScroll | +| Pulse | loop | Pulse | +| Shrink | entrance | DropIn | +| Shrink | scroll | ShrinkScroll | +| Expand | entrance | ExpandIn | + +### Dramatic / Cinematic / Theatrical + +Keywords: dramatic, cinematic, theatrical, staged, sweeping, intimate, focused, detailed, revealing + +| Effect | Trigger | Preset | +| -------- | -------- | -------------- | +| Shutters | entrance | ShuttersIn | +| Shutters | scroll | ShuttersScroll | +| Parallax | scroll | ParallaxScroll | +| Expand | entrance | ExpandIn | +| Reveal | entrance | RevealIn | +| Reveal | scroll | RevealScroll | + +### Modern / Tech / Immersive + +Keywords: modern, tech, immersive, dimensional, spatial, 3d, depth, layered, innovative, interactive, responsive, engaging, following + +| Effect | Trigger | Preset | +| -------- | -------- | -------------- | +| Tilt 3D | mouse | Tilt3DMouse | +| Track 3D | mouse | Track3DMouse | +| Track | mouse | TrackMouse | +| Skew | mouse | SkewMouse | +| 3D spin | scroll | Spin3dScroll | +| Parallax | scroll | ParallaxScroll | +| Resize | mouse | ScaleMouse | +| Blur | entrance | BlurIn | +| Blur | scroll | BlurScroll | +| Blur | mouse | BlurMouse | +| Fold | entrance | FoldIn | +| Fold | loop | Fold | + +### Creative / Experimental / Edgy + +Keywords: creative, artistic, experimental, unconventional, edgy, distorted, unique, expressive, graphic, transformative, fluid, liquid, elastic, flexible, stretchy + +| Effect | Trigger | Preset | +| ------- | -------- | ------------- | +| Skew | mouse | SkewMouse | +| Tilt | entrance | TiltIn | +| Tilt | scroll | TiltScroll | +| Shape | entrance | ShapeIn | +| Shape | scroll | ShapeScroll | +| Blob | mouse | BlobMouse | +| Cross | loop | Cross | +| Stretch | scroll | StretchScroll | +| Rubber | loop | Rubber | + +### Clean / Professional / Minimal + +Keywords: clean, structured, organized, directional, purposeful, direct, simple, straightforward, progressive, minimalist, precise, understated, professional + +| Effect | Trigger | Preset | +| ------ | -------- | ------------ | +| Slide | entrance | SlideIn | +| Slide | scroll | SlideScroll | +| Move | scroll | MoveScroll | +| Fold | entrance | FoldIn | +| Fold | loop | Fold | +| Reveal | entrance | RevealIn | +| Reveal | scroll | RevealScroll | +| Shrink | entrance | DropIn | +| Shrink | scroll | ShrinkScroll | + +## Selection Recommendations + +1. Do not add entrance presets (or any animation that starts with opacity 0) to `

` elements in the first fold +2. Do not add scroll-in animations in the first fold +3. Do not add scroll-out animations in the last fold ## Cross-Category Parallels -| Entrance | Scroll | Ongoing | Mouse | -| -------- | -------------- | ------- | ----------- | -| FadeIn | FadeScroll | Flash | - | -| ArcIn | ArcScroll | - | - | -| SpinIn | SpinScroll | Spin | SpinMouse | -| BounceIn | - | Bounce | BounceMouse | -| TiltIn | TiltScroll | - | Tilt3DMouse | -| FlipIn | FlipScroll | Flip | - | -| ExpandIn | GrowScroll | Pulse | ScaleMouse | -| SlideIn | SlideScroll | - | TrackMouse | -| BlurIn | BlurScroll | - | BlurMouse | -| RevealIn | RevealScroll | - | - | -| - | ParallaxScroll | - | TrackMouse | +| Entrance | Scroll | Ongoing | Mouse | +| ---------- | -------------- | ------- | ----------- | +| FadeIn | FadeScroll | Flash | - | +| ArcIn | ArcScroll | - | - | +| SpinIn | SpinScroll | Spin | - | +| BounceIn | - | Bounce | - | +| TiltIn | TiltScroll | - | Tilt3DMouse | +| FlipIn | FlipScroll | Flip | - | +| FoldIn | - | Fold | - | +| ExpandIn | GrowScroll | Pulse | ScaleMouse | +| SlideIn | SlideScroll | - | TrackMouse | +| BlurIn | BlurScroll | - | BlurMouse | +| RevealIn | RevealScroll | - | - | +| ShapeIn | ShapeScroll | - | - | +| ShuttersIn | ShuttersScroll | - | - | +| TurnIn | TurnScroll | - | - | +| - | ParallaxScroll | - | TrackMouse | ## Accessibility @@ -195,8 +356,8 @@ If the host handles accessibility globally (e.g., disabling all animations on `( **High risk** (vestibular triggers, seizure risk if motion is fast and repetitive): -- Spinning: SpinIn, Spin, SpinScroll, SpinMouse, Spin3dScroll -- Bouncing: BounceIn, Bounce, BounceMouse +- Spinning: SpinIn, Spin, SpinScroll, Spin3dScroll +- Bouncing: BounceIn, Bounce - 3D rotations: ArcIn, FlipIn, ArcScroll, FlipScroll, Tilt3DMouse - Continuous motion: Flash, DVD, Jello, Wiggle diff --git a/packages/motion-presets/rules/presets/scroll-presets.md b/packages/motion-presets/rules/presets/scroll-presets.md index 3b627398..17c133ca 100644 --- a/packages/motion-presets/rules/presets/scroll-presets.md +++ b/packages/motion-presets/rules/presets/scroll-presets.md @@ -109,7 +109,7 @@ Parameters: ### GrowScroll -Visual: Element scales up from a direction as it scrolls into view. +Visual: Element scales up from a direction as it scrolls into or out of view. Parameters: @@ -142,7 +142,7 @@ Parameters: ### PanScroll -Visual: Element pans horizontally across the viewport as it scrolls. +Visual: Horizontal panning tied to scroll. Parameters: @@ -205,7 +205,7 @@ Parameters: ### ShrinkScroll -Visual: Element shrinks toward a direction as it scrolls, the inverse of GrowScroll. +Visual: Element shrinks toward a direction as it scrolls into or out of view, the inverse of GrowScroll. Parameters: @@ -222,7 +222,7 @@ Parameters: ### ShuttersScroll -Visual: Element is revealed through shutter-like strips that open on scroll. +Visual: Element is revealed through staggered shutter-like strips that open on scroll in. When scrolling out, the element disappears with the same animation in reverse. Parameters: @@ -319,7 +319,7 @@ Parameters: ### TiltScroll -Visual: Element tilts in 3D with optional parallax vertical movement as it scrolls. +Visual: Element tilts in 3D and perspective, with optional parallax vertical movement as it scrolls into or out of view. Parameters: @@ -357,6 +357,7 @@ Parameters: | Preset | Parameter | Default | Range | | ------------ | ------------- | ------- | -------- | +| ArcScroll | `perspective` | 500 | 200-2000 | | FlipScroll | `perspective` | 800 | 200-2000 | | TiltScroll | `perspective` | 400 | 200-2000 | | Spin3dScroll | `perspective` | 1000 | 200-2000 |