# Pivoine Docs Icon - Visual Animation Guide ## ๐ŸŽฌ Animation State Visualization ### State 1: NORMAL (Idle Breathing) ``` โœจ ๐ŸŒธ ยท ๐ŸŒธ ๐ŸŒธ ๐Ÿ“„ ๐ŸŒธ โ† Petals in semi-closed bud ๐ŸŒธ โญ ๐ŸŒธ Gentle breathing motion ๐ŸŒธ Soft sparkle twinkling โœจ โœจ Rotating stamens in center ``` **Characteristics:** - Petals: `scale(0.3-0.35)` - small, closed - Center: Gentle pulsing (1.0x โ†’ 1.08x) - Animation: 6-second loop - Effect: Peaceful, living blossom --- ### State 2: HOVER (Full Bloom) ``` โœจ ยท * ยท โœจ *๐ŸŒธ * ๐ŸŒธ* ๐ŸŒธ * โญ๐Ÿ“„โญ * ๐ŸŒธ โ† Petals fully opened *๐ŸŒธ * * ๐ŸŒธ* Bloom particles flying ๐ŸŒธ * * * ๐ŸŒธ Enhanced center glow *๐ŸŒธ * ๐ŸŒธ* Sparkles bursting ๐ŸŒธ * ๐ŸŒธ โœจ * โœจ ``` **Characteristics:** - Petals: `scale(1.0-1.1)` - fully extended - Center: `scale(1.3-1.5)` - enlarged with intense glow - Particles: 12 bloom particles orbiting - Effect: Majestic, fully bloomed flower **Animation Flow:** ``` T=0.0s: Mouse enters T=0.1s: Outer petals start opening T=0.2s: Middle petals follow T=0.3s: Inner petals open + particles appear T=0.5s: Center begins growing T=0.8s: Full bloom achieved T=1.0s+: Continuous pulsing animation ``` --- ### State 3: CLICK (Closing) ``` T=0.0s (Start): T=0.6s (Mid): T=1.2s (End): ๐ŸŒธ ๐ŸŒธ ๐ŸŒธ ๐ŸŒธ ๐ŸŒธ ๐ŸŒธ ๐ŸŒธ โญ ๐ŸŒธ โ†’ ๐ŸŒธ โญ ๐ŸŒธ โ†’ โœจ ๐ŸŒธ ๐ŸŒธ ๐ŸŒธ ๐ŸŒธ โญ ๐ŸŒธ ๐ŸŒธ โญ ๐ŸŒธ โœจ โœจ Full bloom Closing Closed bud Particles burst Particles fade Normal state ``` **Characteristics:** - Duration: 1.2 seconds - Petals: Smoothly scale down and translate inward - Particles: Burst outward then disappear - Center: Contracts with elastic bounce - Effect: Elegant closing with satisfying feedback **Animation Curve:** ``` cubic-bezier(0.68, -0.55, 0.27, 1.55) Scale ^ 1.0 | โ•ฑโ€พโ€พโ•ฒ | โ•ฑ โ•ฒ___ | โ•ฑ โ•ฒ 0.3 | โ•ฑ โ•ฒ___ |โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ†’ Time 0s 0.6s 1.2s Elastic bounce-back effect ``` --- ## ๐ŸŽจ Layer Structure (Z-Index) ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ Layer 8: Bloom Particles (hover) โ”‚ opacity: 0 โ†’ 0.7 โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ Layer 7: Sparkles โ”‚ Fixed positions, twinkling โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ Layer 6: Center Inner (light) โ”‚ r=18, light gradient โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ Layer 5: Center Outer (golden) โ”‚ r=26, main center โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ Layer 4: Center Stamens โ”‚ 8 small dots, rotating โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ Layer 3: Document Pages โ”‚ 3 stacked rectangles โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ Layer 2: Petals (3 sub-layers) โ”‚ โ”‚ - Inner (10 petals) โ”‚ โ”‚ - Middle (8 petals) โ”‚ โ”‚ - Outer (8 petals) โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ Layer 1: Background Glow โ”‚ Subtle radial gradient โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` --- ## ๐Ÿ’ซ Particle Movement Patterns ### Normal State: No Particles ### Hover State: 12 Particles Flying ``` Particle positions at different angles: P1 (0ยฐ) โ†‘ | P4 โ†--( โ€ข )--โ†’ P2 Center | โ†“ P3 (180ยฐ) Each particle: - Starts at center (opacity: 0) - Moves outward along its angle - Reaches max distance (80-100px) - Fades out at edges - Duration: 3s loop ``` **Particle Pattern:** ``` Angular distribution (12 particles): 0ยฐ, 30ยฐ, 60ยฐ, 90ยฐ, 120ยฐ, 150ยฐ, 180ยฐ, 210ยฐ, 240ยฐ, 270ยฐ, 300ยฐ, 330ยฐ Staggered delays: Each particle offset by 0.08s Creates smooth orbital effect ``` ### Click State: Burst Pattern ``` โ–ช โ† P1 (fast) โ–ช โ–ช โ–ช ( โ€ข ) โ–ช โ† Particles explode โ–ช โ–ช outward 2x speed โ–ช โ† then fade Burst sequence: 0.0s: Particles at normal hover positions 0.3s: Particles shoot outward (2x distance) 0.6s: Particles start fading 1.2s: Particles invisible ``` --- ## ๐ŸŽฏ Center Animation Detail ### Normal State: ``` โ•ญโ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ โญโญ โ”‚ โ† Stamens rotating โ”‚ โญ๐Ÿ“„โญ โ”‚ โ† Golden outer ring โ”‚ โญโญ โ”‚ โ† Light inner core โ•ฐโ”€โ”€โ”€โ”€โ”€โ•ฏ Outer: r=26, breathing 1.0x โ†’ 1.08x Inner: r=18, breathing 1.0x โ†’ 1.12x Stamens: 20s continuous rotation ``` ### Hover State: ``` โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ โญ โญ โ”‚ โ”‚ โญ ๐Ÿ“„ โญ โ”‚ โ† Center expands โ”‚ โญ โญ โ”‚ โ† Enhanced glow โ”‚ โœจ โœจ โœจโ”‚ โ† Intense lighting โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ Outer: r=26 โ†’ r=39 (1.5x scale) Inner: r=18 โ†’ r=28.8 (1.6x scale) Stamens: Dance up and down Glow: intense-glow filter applied ``` ### Click State: ``` โ•ญโ”€โ”€โ”€โ”€โ”€โ•ฎ โ†’ โ•ญโ”€โ”€โ”€โ•ฎ โ†’ โ•ญโ”€โ”€โ”€โ”€โ”€โ•ฎ โ”‚ โญ๐Ÿ“„โญโ”‚ โ”‚โญ๐Ÿ“„โญโ”‚ โ”‚ โญ๐Ÿ“„โญโ”‚ โ•ฐโ”€โ”€โ”€โ”€โ”€โ•ฏ โ•ฐโ”€โ”€โ”€โ•ฏ โ•ฐโ”€โ”€โ”€โ”€โ”€โ•ฏ 1.3x โ†’ 0.8x โ†’ 1.0x (hover) (contract) (normal) Elastic bounce-back animation ``` --- ## ๐ŸŒˆ Color Transition Map ### Petal Gradients (Radial): ``` Gradient 1 (Pink): #fce7f3 (light pink) โ†’ #fbcfe8 โ†’ #f9a8d4 โ†’ #ec4899 (hot pink) โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–’โ–’โ–’โ–’โ–’โ–’โ–‘โ–‘โ–‘โ–‘ Gradient 2 (Purple): #fae8ff (lavender) โ†’ #f3e8ff โ†’ #e9d5ff โ†’ #c084fc (purple) โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–’โ–’โ–’โ–’โ–’โ–’โ–‘โ–‘โ–‘โ–‘ Gradient 3 (Magenta): #fdf4ff (near white) โ†’ #fae8ff โ†’ #f0abfc โ†’ #d946ef (magenta) โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–’โ–’โ–’โ–’โ–’โ–’โ–‘โ–‘โ–‘โ–‘ Gradient 4 (Rose): #fce7f3 (light pink) โ†’ #fda4af โ†’ #fb7185 โ†’ #f43f5e (rose) โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–’โ–’โ–’โ–’โ–’โ–’โ–‘โ–‘โ–‘โ–‘ ``` ### Center Gradients (Radial): ``` Golden Outer: #fef3c7 (cream) โ†’ #fde68a โ†’ #fbbf24 โ†’ #f59e0b (amber) โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–“โ–“โ–“โ–“โ–’โ–’โ–’โ–’โ–‘โ–‘โ–‘โ–‘ Light Inner: #fffbeb (pale yellow) โ†’ #fef3c7 โ†’ #fde68a (golden) โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘ Stamens: #d97706 (dark amber) - solid color โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ ``` --- ## โšก Performance Characteristics ### Frame Rate Target: 60 FPS ``` Animation Layer CPU Cost GPU Cost โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Background Glow โ–ˆโ–‘โ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–‘โ–‘โ–‘ Outer Petals (8) โ–ˆโ–ˆโ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–ˆโ–ˆโ–‘ Middle Petals (8) โ–ˆโ–ˆโ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–ˆโ–ˆโ–‘ Inner Petals (10) โ–ˆโ–ˆโ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–ˆโ–ˆโ–‘ Center (2 circles) โ–ˆโ–‘โ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–ˆโ–‘โ–‘ Stamens (8) โ–ˆโ–‘โ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–‘โ–‘โ–‘ Sparkles (8) โ–ˆโ–‘โ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–‘โ–‘โ–‘ Particles (12) โ–ˆโ–ˆโ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–ˆโ–ˆโ–‘ Glow Filters โ–ˆโ–‘โ–‘โ–‘โ–‘ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Total (Hover) โ–ˆโ–ˆโ–ˆโ–‘โ–‘ โ–ˆโ–ˆโ–ˆโ–ˆโ–‘ โ–ˆ = 20% utilization ``` ### Optimization Strategies: 1. **Transform & Opacity Only** - No layout-triggering properties - Hardware accelerated 2. **Will-Change Applied** - `will-change: transform, opacity` - GPU layer creation 3. **Staggered Animation** - Spreads CPU load over time - Smoother visual perception --- ## ๐Ÿ“ Geometric Calculations ### Petal Position Formula: ```javascript For petal at angle ฮธ: x = centerX + cos(ฮธ) * distance y = centerY + sin(ฮธ) * distance Outer petals: distance = 38px (hover) Middle petals: distance = 26px (hover) Inner petals: distance = 16px (hover) ``` ### Particle Trajectory: ```javascript // Hover animation translate( cos(angle) * maxDistance, sin(angle) * maxDistance ) // Click burst translate( cos(angle) * maxDistance * 2, sin(angle) * maxDistance * 2 ) ``` --- ## ๐ŸŽญ State Transition Diagram ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ NORMAL โ”‚ โ”‚ (Breathing) โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ Mouse Enter โ”‚ Mouse Leave โ”‚ โ†“ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ HOVER โ”‚ โ”Œโ”€โ”€โ”€โ”€โ–ถโ”‚ (Full Bloom) โ”‚โ—€โ”€โ”€โ”€โ”€โ” โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ”‚ โ”‚ Click endsโ”‚ Clickโ”‚ โ”‚ Hover maintains โ”‚ โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”‚ CLICK โ”‚โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ (Closing) โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ After 1.2s โ”‚ โ–ผ Return to NORMAL ``` --- ## ๐Ÿ’ก Design Philosophy ### Visual Hierarchy: 1. **Center (Focal Point)**: Documentation pages = purpose 2. **Petals (Beauty)**: Organic, natural flower form 3. **Particles (Magic)**: Dynamic, alive feeling 4. **Sparkles (Polish)**: Finishing touch of elegance ### Animation Principles: - **Anticipation**: Slight scale-down before bloom - **Follow-through**: Elastic bounce on close - **Staging**: Staggered petal animation - **Timing**: Slower start, faster middle, slower end - **Secondary Motion**: Particles enhance main animation ### Color Psychology: - **Pink/Purple**: Creative, artistic, documentation - **Golden Center**: Knowledge, enlightenment - **Gradient Flow**: Natural, organic, alive --- **Visual Guide Version**: 1.0 **Last Updated**: October 2025 For implementation details, see `REFACTORING_SUMMARY.md` For usage examples, see `README.md`