Tombigel/llm preset rules (#78)

* 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.

* 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.

* Update PLAN.md for motion presets:  fix lint issues

* 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

* Run prettier --fix on packages/motion-presets/rules

* 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.

* 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

* 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

* fix md lint

* fixed lint issues - ran 'yarn format' on all md files

* made better a11y rules

* 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.

* Apply suggestion from @ydaniv

Co-authored-by: Yehonatan Daniv <maggotfish@gmail.com>

* 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 <cursoragent@cursor.com>

* Regenerate preset docs: GrowIn→ExpandIn, add registry alignment step

- 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 <cursoragent@cursor.com>

* refactored rules to the structure of skills for future coimpatibility.
editd some of the descriptions to be more accurate

* regeneratwd all files from scratch

* moved presets plan to .cursor/plans

* fixed lint

* 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

* Fixed format

---------

Co-authored-by: Yehonatan Daniv <maggotfish@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

.cursor/plans/motion_presets_llm_rules.plan.md

@@ -0,0 +1,365 @@
+---
+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
+
+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
+
+- [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)
+
+---
+
+### FadeIn
+
+Visual: Element fades in smoothly from fully transparent to fully opaque.
+
+Parameters: None — this preset has no configurable parameters.
+
+```typescript
+{
+  type: 'FadeIn';
+}
+```
+
+---
+
+### ArcIn
+
+Visual: Element enters along a 3D arc path, rotating into view with depth motion.
+
+Parameters:
+
+- `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' }
+```
+
+---
+
+### BlurIn
+
+Visual: Element transitions from blurred to sharp while fading in.
+
+Parameters:
+
+- `blur`: number — initial blur amount in px (default: `6`)
+
+```typescript
+{ type: 'BlurIn', blur: 25 }
+```
+
+---
+
+### BounceIn
+
+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 — bounce distance multiplier (default: `1`)
+- `perspective`: number — 3D perspective for center direction (default: `800`)
+
+```typescript
+{ type: 'BounceIn', direction: 'left', distanceFactor: 2 }
+```
+
+---
+
+### CurveIn
+
+Visual: Element curves in with a 180° rotation and depth motion in a 3D space, creating a swinging arc entrance.
+
+Parameters:
+
+- `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: Element shrinks down from a larger size to its final scale.
+
+Parameters:
+
+- `initialScale`: number — starting scale before settling to 1 (default: `1.6`)
+
+```typescript
+{ type: 'DropIn', initialScale: 2 }
+```
+
+---
+
+### ExpandIn
+
+Visual: Element expands from a point in a given direction, scaling from small to full size with a fade-in.
+
+Parameters:
+
+- `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', direction: 'bottom', initialScale: 0.5 }
+```
+
+---
+
+### FlipIn
+
+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 — starting rotation in degrees (default: `90`)
+- `perspective`: number — 3D perspective in px (default: `800`)
+
+```typescript
+{ type: 'FlipIn', direction: 'right', initialRotate: 180 }
+```
+
+---
+
+### FloatIn
+
+Visual: Element drifts gently into place from a direction with a fade-in.
+
+Parameters:
+
+- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'left'`)
+
+```typescript
+{ type: 'FloatIn', direction: 'bottom' }
+```
+
+---
+
+### FoldIn
+
+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 — starting fold angle in degrees (default: `90`)
+- `perspective`: number — 3D perspective in px (default: `800`)
+
+```typescript
+{ type: 'FoldIn', direction: 'left', initialRotate: 60 }
+```
+
+---
+
+### GlideIn
+
+Visual: Element glides in smoothly from off-screen along a direction.
+
+Parameters:
+
+- `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', direction: 270, distance: { value: 200, type: 'px' } }
+```
+
+---
+
+### RevealIn
+
+Visual: Element is progressively revealed by an expanding clip-path from one edge.
+
+Parameters:
+
+- `direction`: 'top' | 'right' | 'bottom' | 'left' (default: `'left'`)
+
+```typescript
+{ type: 'RevealIn', direction: 'bottom' }
+```
+
+---
+
+### ShapeIn
+
+Visual: Element appears through an expanding geometric clip-path shape.
+
+Parameters:
+
+- `shape`: 'circle' | 'ellipse' | 'rectangle' | 'diamond' | 'window' (default: `'rectangle'`)
+
+```typescript
+{ type: 'ShapeIn', shape: 'circle' }
+```
+
+---
+
+### ShuttersIn
+
+Visual: Element is revealed through multiple shutter-like strips that open in sequence.
+
+Parameters:
+
+- `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: 'top', shutters: 8 }
+```
+
+---
+
+### SlideIn
+
+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 to 1, how far off-screen the element starts (default: `1`)
+
+```typescript
+{ type: 'SlideIn', direction: 'right', initialTranslate: 0.5 }
+```
+
+---
+
+### SpinIn
+
+Visual: Element spins into view while scaling from small to full size.
+
+Parameters:
+
+- `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', spins: 1, direction: 'counter-clockwise' }
+```
+
+---
+
+### TiltIn
+
+Visual: Element tilts in from the side with 3D rotation and a clip-path reveal.
+
+Parameters:
+
+- `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: 'right' }
+```
+
+---
+
+### TurnIn
+
+Visual: Element rotates into view around a corner pivot point.
+
+Parameters:
+
+- `direction`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' (default: `'top-left'`)
+
+```typescript
+{ type: 'TurnIn', direction: 'bottom-right' }
+```
+
+---
+
+### WinkIn
+
+Visual: Element winks into view by expanding from its horizontal or vertical center, while being revealed with a clip-path.
+
+Parameters:
+
+- `direction`: 'horizontal' | 'vertical' (default: `'horizontal'`)
+
+```typescript
+{ type: 'WinkIn', direction: 'vertical' }
+```
+
+---
+
+## Optional Parameters
+
+Some preset 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 |
+
+## 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           | sineOut     | cubicInOut | quintInOut    |
+| BlurIn   | blur             | 6px         | 25px       | 50px          |
+| BounceIn | distanceFactor   | 1           | 2          | 3             |
+| DropIn   | initialScale     | 1.2         | 1.6        | 2             |
+| FlipIn   | initialRotate    | 35°         | 60°        | 90°           |
+| 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: 35 }`