Files

Sebastian Krüger 8729e37a66 feat: docs.pivoine.art

2025-10-09 20:15:18 +02:00

11 KiB

Raw Blame History

🌸 Pivoine Docs Icon - Complete Documentation

The official branding icon for the Pivoine Documentation Hub, featuring a beautiful peony flower with integrated documentation elements.

🎨 Design Concept

The icon combines two powerful visual metaphors:

Peony Flower (Pivoine) - Represents the brand identity
- Multiple layers of petals in purple and pink gradients
- Symbolizes beauty, elegance, and growth
- Reflects the "Pivoine" brand name
Documentation Pages - Represents the hub's purpose
- Stacked pages in the center of the flower
- Blue text lines suggesting content
- Golden center representing knowledge/enlightenment

Color Palette

/* Primary Petals */
Purple 1:  #a855f7 → #ec4899  /* Violet to pink */
Purple 2:  #9333ea → #db2777  /* Deep purple to rose */
Purple 3:  #c026d3 → #f472b6  /* Fuchsia to pink */

/* Center & Accents */
Golden:    #fbbf24 → #f59e0b → #d97706  /* Warm gold gradient */
Pages:     #f3f4f6 → #e5e7eb  /* Light gray */
Text:      #6366f1, #a855f7  /* Indigo and purple */
Background: #1e293b  /* Dark slate */

📦 Available Formats

React Component (Animated)

File: components/icons/PivoineDocsIcon.tsx

Full animations (hover, click, orbiting particles)
Interactive and responsive
Customizable size and behavior
For hero sections and prominent displays

Static SVG Icons

Files:

public/icon.svg (256x256) - Full detail, all platforms
public/favicon.svg (32x32 optimized) - Browser tabs

PNG Icons (Generated)

Generate with: ./scripts/generate-icons.sh

icon-192.png - PWA icon (Android)
icon-512.png - PWA icon (Android HD)
apple-touch-icon.png - iOS home screen
favicon-32x32.png - Standard favicon
favicon-16x16.png - Small favicon

🎭 React Component Usage

Basic Usage (Hero Area)

import { PivoineDocsIcon } from '@/components/icons'

<PivoineDocsIcon size="200px" />

Props

interface PivoineDocsIconProps {
  size?: string          // Default: '256px'
  interactive?: boolean  // Default: true
  className?: string     // Additional classes
  showLabel?: boolean    // Default: false - Shows "Pivoine Docs" text
}

Examples

// Large hero icon with full interactivity
<PivoineDocsIcon size="256px" showLabel={true} />

// Medium size, interactive
<PivoineDocsIcon size="128px" />

// Small, non-interactive (for cards/lists)
<PivoineDocsIcon size="64px" interactive={false} />

// Custom styling
<PivoineDocsIcon 
  size="180px" 
  className="my-custom-class"
  showLabel={false}
/>

✨ Animations & Effects

Default State

Flower starts CLOSED as a tight bud 🌷
- Outer petals: 30% size, 50% opacity
- Middle petals: 40% size, 60% opacity
- Inner petals: 50% size, 70% opacity
Subtle pulsing background circle
Twinkling sparkles at corners
Orbiting particles around the flower
Gentle floating of document pages
Text lines appear with staggered animation

Hover State (when `interactive={true}`)

Icon scales up and lifts (transform 3D)
PETALS BLOOM OPEN to full size! 🌸
- Smooth 0.8s transition
- Staggered timing for natural bloom:
  - Outer petals bloom first (0s delay)
  - Middle petals follow (0.05s delay)
  - Inner petals last (0.1s delay)
- All reach 100% size and full opacity
Enhanced shadow and glow effects
Center golden circle glows intensely
Sparkles burst and expand
Pages fan out slightly with rotation
Particles accelerate

Click/Tap State

3D bounce with rotation (0-180-360°)
Petals explode outward briefly
Center bursts with glow
Ripple effect emanates from center
Duration: ~800ms
Smooth cubic-bezier easing

Continuous Animations

Even when not hovered:

Background pulse (4s cycle)
Sparkle twinkle (2s cycle, staggered)
Particle orbit (8s rotation, staggered)
Center pulse (3s cycle)
Page float (3s gentle movement)
Text lines draw in on mount

📱 Responsive & Accessible

Responsive Behavior

/* Desktop: Full effects */
@media (min-width: 769px) {
  hover: scale(1.08) translateY(-8px)
}

/* Tablet/Mobile: Reduced scale */
@media (max-width: 768px) {
  hover: scale(1.05) translateY(-4px)
}

/* Touch devices: Active state */
@media (hover: none) and (pointer: coarse) {
  active: scale(0.95)
}

Accessibility

✅ Reduced Motion: All animations disabled when prefers-reduced-motion: reduce
✅ Touch Optimized: Larger hit areas, optimized tap response
✅ Keyboard Navigation: Focusable when interactive
✅ Screen Readers: Appropriate ARIA labels (add as needed)

🎯 Integration Points

1. Hero Section (Landing Page)

Location: app/page.tsx

<div className="flex justify-center mb-8">
  <PivoineDocsIcon size="200px" showLabel={false} />
</div>

2. Favicon (Browser Tab)

Location: app/layout.tsx

icons: {
  icon: [
    { url: '/favicon.svg', type: 'image/svg+xml' },
    { url: '/icon.svg', type: 'image/svg+xml', sizes: 'any' },
  ],
}

3. PWA Manifest

Location: public/manifest.json

{
  "icons": [
    {
      "src": "/icon.svg",
      "sizes": "any",
      "type": "image/svg+xml"
    },
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

4. Apple Touch Icon

Location: app/layout.tsx

icons: {
  apple: [
    { url: '/apple-touch-icon.png', sizes: '180x180' },
  ],
}

🛠️ Technical Details

Performance

GPU Accelerated: All animations use CSS transforms
Optimized: Minimal JavaScript, mostly CSS
60 FPS: Smooth on modern devices
No External Assets: Inline SVG, no image loading
File Size: ~10KB component + ~3KB SVG

Browser Support

✅ Chrome/Edge 90+
✅ Firefox 88+
✅ Safari 14+
✅ iOS Safari 14+
✅ Chrome Mobile
✅ Samsung Internet

SVG Filters Used

feGaussianBlur - Glow effects
feMerge - Combining blur with original
feDropShadow - Page shadows

Gradients

8 unique gradients total
Linear gradients for petals
Radial gradients for ripple
Golden gradient for center
Page gradients for documents

📐 Size Guidelines

Context	Recommended Size	Interactive
Hero section	200-256px	Yes
Page header	64-96px	Optional
Sidebar	48-64px	No
Favicon	Auto (SVG)	N/A
PWA Icon	Auto (PNG)	N/A
Avatar/Profile	40-48px	No

🎨 Customization

Changing Colors

Edit the gradient definitions in PivoineDocsIcon.tsx:

<linearGradient id="petal-gradient-1">
  <stop offset="0%" style={{ stopColor: '#YOUR_COLOR' }} />
  <stop offset="100%" style={{ stopColor: '#YOUR_COLOR' }} />
</linearGradient>

Adjusting Animations

Modify keyframes in the <style jsx> section:

@keyframes your-custom-animation {
  0% { /* start state */ }
  100% { /* end state */ }
}

Adding New Effects

Add new SVG elements to the component
Define animations in CSS
Apply animations to elements
Test hover/click states

🚀 Generating PNG Icons

Prerequisites

Install librsvg:

# macOS
brew install librsvg

# Ubuntu/Debian
sudo apt-get install librsvg2-bin

Generate All Icons

chmod +x scripts/generate-icons.sh
./scripts/generate-icons.sh

This creates:

icon-192.png (192x192)
icon-512.png (512x512)
apple-touch-icon.png (180x180)
favicon-32x32.png (32x32)
favicon-16x16.png (16x16)

Manual Generation

cd public
rsvg-convert -w 192 -h 192 icon.svg -o icon-192.png
rsvg-convert -w 512 -h 512 icon.svg -o icon-512.png
rsvg-convert -w 180 -h 180 icon.svg -o apple-touch-icon.png

📝 Usage in Documentation

Markdown

![Pivoine Docs Logo](/icon.svg)

HTML

<img src="/icon.svg" alt="Pivoine Docs" width="64" height="64">

React

import { PivoineDocsIcon } from '@/components/icons'
<PivoineDocsIcon size="64px" />

🎯 Design Philosophy

Why This Design?

Brand Recognition: The peony (pivoine) directly represents the brand
Purpose Clarity: Document pages in center clearly indicate "documentation"
Visual Hierarchy: Flower draws eye to center (docs)
Modern Aesthetic: Gradients and effects feel contemporary
Memorable: Unique design stands out from generic doc icons
Scalable: Works at all sizes (16px to 512px+)
Thematic: Matches the purple/pink theme of the landing page

Symbolism

Petals: Multiple layers represent comprehensive documentation
Colors: Purple/pink for creativity and accessibility
Golden Center: Knowledge and enlightenment
Pages: Clear representation of documentation
Bloom Animation: Growth and expanding knowledge
Particles: Dynamic, always-evolving content

🐛 Troubleshooting

Icon Not Showing

# Clear Next.js cache
rm -rf .next
pnpm dev

Animations Not Working

Check browser support for SVG filters
Verify no conflicting CSS
Check prefers-reduced-motion setting

PNG Icons Not Generating

# Check if rsvg-convert is installed
which rsvg-convert

# If not, install librsvg
brew install librsvg  # macOS

Performance Issues

Use interactive={false} for multiple icons
Reduce size for better performance
Consider static SVG for lists/grids

📊 File Structure

docs.pivoine.art/
├── components/
│   └── icons/
│       ├── PivoineDocsIcon.tsx  # React component
│       ├── KomposeIcon.tsx      # Other icons
│       └── index.ts             # Exports
├── public/
│   ├── icon.svg                 # Full detail SVG
│   ├── favicon.svg              # Simplified for small sizes
│   ├── manifest.json            # PWA manifest
│   ├── icon-192.png             # Generated
│   ├── icon-512.png             # Generated
│   └── apple-touch-icon.png     # Generated
├── scripts/
│   └── generate-icons.sh        # PNG generation script
└── app/
    ├── layout.tsx               # Icon metadata
    └── page.tsx                 # Icon usage

🎉 Credits

Design: Custom peony + documentation hybrid
Colors: Tailwind CSS palette (purple, pink, gold)
Animations: CSS keyframes + React hooks
Inspiration: Nature (peony flower) + technology (docs)

components/README.md - Component usage guide
components/icons/SHOWCASE.md - KomposeIcon example
README.md - Main project documentation

Created with care for Valknar | pivoine.art

A peony in full bloom, with knowledge at its heart 🌸📚

11 KiB Raw Blame History