home/Projects/docs.pivoine.art/components/icons/VISUAL_GUIDE.md

# 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`