434 lines
11 KiB
Markdown
434 lines
11 KiB
Markdown
# 🌸 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
|
|
- **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
|
|
```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
|
|
|
|
```
|
|
|
|
### 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* 🌸📚
|