feat: docs.pivoine.art

2025-10-09 19:52:28 +02:00
parent b818e85e77
commit ae8910aa31
13 changed files with 1672 additions and 5 deletions
--- a/Projects/docs.pivoine.art/components/icons/PIVOINE_DOCS_ICON.md
+++ b/Projects/docs.pivoine.art/components/icons/PIVOINE_DOCS_ICON.md
@@ -0,0 +1,426 @@
+# 🌸 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:
+
+1. **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
+
+2. **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
+
+```css
+/* 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)
+```tsx
+import { PivoineDocsIcon } from '@/components/icons'
+
+<PivoineDocsIcon size="200px" />
+```
+
+### Props
+
+```typescript
+interface PivoineDocsIconProps {
+  size?: string          // Default: '256px'
+  interactive?: boolean  // Default: true
+  className?: string     // Additional classes
+  showLabel?: boolean    // Default: false - Shows "Pivoine Docs" text
+}
+```
+
+### Examples
+
+```tsx
+// 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
+- **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)
+- Enhanced **shadow and glow** effects
+- Petals **bloom** outward in sequence
+  - Outer petals bloom first
+  - Middle petals follow (0.1s delay)
+  - Inner petals last (0.2s delay)
+- 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
+```css
+/* 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`
+```tsx
+<div className="flex justify-center mb-8">
+  <PivoineDocsIcon size="200px" showLabel={false} />
+</div>
+```
+
+### 2. Favicon (Browser Tab)
+**Location**: `app/layout.tsx`
+```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`
+```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`
+```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`:
+
+```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:
+
+```css
+@keyframes your-custom-animation {
+  0% { /* start state */ }
+  100% { /* end state */ }
+}
+```
+
+### Adding New Effects
+
+1. Add new SVG elements to the component
+2. Define animations in CSS
+3. Apply animations to elements
+4. Test hover/click states
+
+## 🚀 Generating PNG Icons
+
+### Prerequisites
+Install `librsvg`:
+```bash
+# macOS
+brew install librsvg
+
+# Ubuntu/Debian
+sudo apt-get install librsvg2-bin
+```
+
+### Generate All Icons
+```bash
+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
+```bash
+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
+```markdown
+![Pivoine Docs Logo](/icon.svg)
+```
+
+### HTML
+```html
+<img src="/icon.svg" alt="Pivoine Docs" width="64" height="64">
+```
+
+### React
+```tsx
+import { PivoineDocsIcon } from '@/components/icons'
+<PivoineDocsIcon size="64px" />
+```
+
+## 🎯 Design Philosophy
+
+### Why This Design?
+
+1. **Brand Recognition**: The peony (pivoine) directly represents the brand
+2. **Purpose Clarity**: Document pages in center clearly indicate "documentation"
+3. **Visual Hierarchy**: Flower draws eye to center (docs)
+4. **Modern Aesthetic**: Gradients and effects feel contemporary
+5. **Memorable**: Unique design stands out from generic doc icons
+6. **Scalable**: Works at all sizes (16px to 512px+)
+7. **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
+```bash
+# 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
+```bash
+# 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)
+
+## 📚 Related Documentation
+
+- [components/README.md](../README.md) - Component usage guide
+- [components/icons/SHOWCASE.md](./SHOWCASE.md) - KomposeIcon example
+- [README.md](../../README.md) - Main project documentation
+
+---
+
+**Created with care for Valknar** | [pivoine.art](http://pivoine.art)
+
+*A peony in full bloom, with knowledge at its heart* 🌸📚