agent-skill-kit 3.9.135

package/.agent/skills/design-system/rules/motion-graphics.md

@@ -0,0 +1,330 @@
+---
+name: motion-graphics
+description: Advanced motion — Lottie, GSAP, SVG animation, 3D CSS, particles, scroll-driven animations
+title: "Motion Graphics Reference"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: motion, graphics
+---
+
+# Motion Graphics Reference
+
+> Advanced animation techniques for premium web experiences - Lottie, GSAP, SVG, 3D, Particles.
+> **Learn the principles, create WOW effects.**
+
+---
+
+## 1. Lottie Animations
+
+### What is Lottie?
+
+```
+JSON-based vector animations:
+├── Exported from After Effects via Bodymovin
+├── Lightweight (smaller than GIF/video)
+├── Scalable (vector-based, no pixelation)
+├── Interactive (control playback, segments)
+└── Cross-platform (web, iOS, Android, React Native)
+```
+
+### When to Use Lottie
+
+| Use Case | Why Lottie? |
+|----------|-------------|
+| **Loading animations** | Branded, smooth, lightweight |
+| **Empty states** | Engaging illustrations |
+| **Onboarding flows** | Complex multi-step animations |
+| **Success/Error feedback** | Delightful micro-interactions |
+| **Animated icons** | Consistent cross-platform |
+
+### Principles
+
+- Keep file size under 100KB for performance
+- Use loop sparingly (avoid distraction)
+- Provide static fallback for reduced-motion
+- Lazy load animation files when possible
+
+### Sources
+
+- LottieFiles.com (free library)
+- After Effects + Bodymovin (custom)
+- Figma plugins (export from design)
+
+---
+
+## 2. GSAP (GreenSock)
+
+### What Makes GSAP Different
+
+```
+Professional timeline-based animation:
+├── Precise control over sequences
+├── ScrollTrigger for scroll-driven animations
+├── MorphSVG for shape transitions
+├── Physics-based easing
+└── Works with any DOM element
+```
+
+### Core Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| **Tween** | Single A→B animation |
+| **Timeline** | Sequenced/overlapping animations |
+| **ScrollTrigger** | Scroll position controls playback |
+| **Stagger** | Cascade effect across elements |
+
+### When to Use GSAP
+
+- ✅ Complex sequenced animations
+- ✅ Scroll-triggered reveals
+- ✅ Precise timing control needed
+- ✅ SVG morphing effects
+- ❌ Simple hover/focus effects (use CSS)
+- ❌ Performance-critical mobile (heavier)
+
+### Principles
+
+- Use timeline for orchestration (not individual tweens)
+- Stagger delay: 0.05-0.15s between items
+- ScrollTrigger: start at 70-80% viewport entry
+- Kill animations on unmount (prevent memory leaks)
+
+---
+
+## 3. SVG Animations
+
+### Types of SVG Animation
+
+| Type | Technique | Use Case |
+|------|-----------|----------|
+| **Line Drawing** | stroke-dashoffset | Logo reveals, signatures |
+| **Morph** | Path interpolation | Icon transitions |
+| **Transform** | rotate, scale, translate | Interactive icons |
+| **Color** | fill/stroke transition | State changes |
+
+### Line Drawing Principles
+
+```
+How stroke-dashoffset drawing works:
+├── Set dasharray to path length
+├── Set dashoffset equal to dasharray (hidden)
+├── Animate dashoffset to 0 (revealed)
+└── Create "drawing" effect
+```
+
+### When to Use SVG Animations
+
+- ✅ Logo reveals, brand moments
+- ✅ Icon state transitions (hamburger ↔ X)
+- ✅ Infographics, data visualization
+- ✅ Interactive illustrations
+- ❌ Photo-realistic content (use video)
+- ❌ Very complex scenes (performance)
+
+### Principles
+
+- Get path length dynamically for accuracy
+- Duration: 1-3s for full drawings
+- Easing: ease-out for natural feel
+- Simple fills complement, don't compete
+
+---
+
+## 4. 3D CSS Transforms
+
+### Core Properties
+
+```
+CSS 3D Space:
+├── perspective: depth of 3D field (500-1500px typical)
+├── transform-style: preserve-3d (enable children 3D)
+├── rotateX/Y/Z: rotation per axis
+├── translateZ: move toward/away from viewer
+└── backface-visibility: show/hide back side
+```
+
+### Common 3D Patterns
+
+| Pattern | Use Case |
+|---------|----------|
+| **Card flip** | Reveals, flashcards, product views |
+| **Tilt on hover** | Interactive cards, 3D depth |
+| **Parallax layers** | Hero sections, immersive scrolling |
+| **3D carousel** | Image galleries, sliders |
+
+### Principles
+
+- Perspective: 800-1200px for subtle, 400-600px for dramatic
+- Keep transforms simple (rotate + translate)
+- Ensure backface-visibility: hidden for flips
+- Test on Safari (different rendering)
+
+---
+
+## 5. Particle Effects
+
+### Types of Particle Systems
+
+| Type | Feel | Use Case |
+|------|------|----------|
+| **Geometric** | Tech, network | SaaS, tech sites |
+| **Confetti** | Celebration | Success moments |
+| **Snow/Rain** | Atmospheric | Seasonal, mood |
+| **Dust/Bokeh** | Dreamy | Photography, luxury |
+| **Fireflies** | Magical | Games, fantasy |
+
+### Libraries
+
+| Library | Best For |
+|---------|----------|
+| **tsParticles** | Configurable, lightweight |
+| **particles.js** | Simple backgrounds |
+| **Canvas API** | Custom, maximum control |
+| **Three.js** | Complex 3D particles |
+
+### Principles
+
+- Default: 30-50 particles (not overwhelming)
+- Movement: slow, organic (speed 0.5-2)
+- Opacity: 0.3-0.6 (don't compete with content)
+- Connections: subtle lines for "network" feel
+- ⚠️ Disable or reduce on mobile
+
+### When to Use
+
+- ✅ Hero backgrounds (atmospheric)
+- ✅ Success celebrations (confetti burst)
+- ✅ Tech visualization (connected nodes)
+- ❌ Content-heavy pages (distraction)
+- ❌ Low-powered devices (battery drain)
+
+---
+
+## 6. Scroll-Driven Animations
+
+### Native CSS (Modern)
+
+```
+CSS Scroll Timelines:
+├── animation-timeline: scroll() - document scroll
+├── animation-timeline: view() - element in viewport
+├── animation-range: entry/exit thresholds
+└── No JavaScript required
+```
+
+### Principles
+
+| Trigger Point | Use Case |
+|---------------|----------|
+| **Entry 0%** | When element starts entering |
+| **Entry 50%** | When half visible |
+| **Cover 50%** | When centered in viewport |
+| **Exit 100%** | When fully exited |
+
+### Best Practices
+
+- Reveal animations: start at ~25% entry
+- Parallax: continuous scroll progress
+- Sticky elements: use cover range
+- Always test scroll performance
+
+---
+
+## 7. Performance Principles
+
+### GPU vs CPU Animation
+
+```
+CHEAP (GPU-accelerated):
+├── transform (translate, scale, rotate)
+├── opacity
+└── filter (use sparingly)
+
+EXPENSIVE (triggers reflow):
+├── width, height
+├── top, left, right, bottom
+├── padding, margin
+└── complex box-shadow
+```
+
+### Optimization Checklist
+
+- [ ] Animate only transform/opacity
+- [ ] Use `will-change` before heavy animations (remove after)
+- [ ] Test on low-end devices
+- [ ] Implement `prefers-reduced-motion`
+- [ ] Lazy load animation libraries
+- [ ] Throttle scroll-based calculations
+
+---
+
+## 8. Motion Graphics Decision Tree
+
+```
+What animation do you need?
+│
+├── Complex branded animation?
+│   └── Lottie (After Effects export)
+│
+├── Sequenced scroll-triggered?
+│   └── GSAP + ScrollTrigger
+│
+├── Logo/icon animation?
+│   └── SVG animation (stroke or morph)
+│
+├── Interactive 3D effect?
+│   └── CSS 3D Transforms (simple) or Three.js (complex)
+│
+├── Atmospheric background?
+│   └── tsParticles or Canvas
+│
+└── Simple entrance/hover?
+    └── CSS @keyframes or Framer Motion
+```
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Animate everything at once | Stagger and sequence |
+| Use heavy libraries for simple effects | Start with CSS |
+| Ignore reduced-motion | Always provide fallback |
+| Block main thread | Optimize for 60fps |
+| Same particles every project | Match brand/context |
+| Complex effects on mobile | Feature detection |
+
+---
+
+## 10. Quick Reference
+
+| Effect | Tool | Performance |
+|--------|------|-------------|
+| Loading spinner | CSS/Lottie | Light |
+| Staggered reveal | GSAP/Framer | Medium |
+| SVG path draw | CSS stroke | Light |
+| 3D card flip | CSS transforms | Light |
+| Particle background | tsParticles | Heavy |
+| Scroll parallax | GSAP ScrollTrigger | Medium |
+| Shape morphing | GSAP MorphSVG | Medium |
+
+---
+
+> **Remember**: Motion graphics should enhance, not distract. Every animation must serve a PURPOSE—feedback, guidance, delight, or storytelling.
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [animation-guide.md](animation-guide.md) | Core animation timing and easing principles |
+| [visual-effects.md](visual-effects.md) | CSS glassmorphism, gradients, shadows |
+| [ux-psychology.md](ux-psychology.md) | Emotional design and feedback psychology |
+| [../SKILL.md](../SKILL.md) | Animation categories quick reference |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/design-system/rules/spatial-composition.md

@@ -0,0 +1,184 @@
+---
+name: spatial-composition
+description: Layout innovation — asymmetric grids, overlapping elements, diagonal flow, negative space
+title: "Break the grid. Create unexpected layouts."
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: spatial, composition
+---
+
+# Spatial Composition
+
+> Break the grid. Create unexpected layouts.
+
+---
+
+## Principle: Break Expectations
+
+Don't default to centered, symmetrical layouts. Create visual tension:
+
+- **Asymmetric arrangements**
+- **Overlapping elements**
+- **Diagonal flow**
+- **Generous negative space OR controlled density**
+
+---
+
+## Grid Breaking Techniques
+
+### Asymmetric Grid
+```css
+.layout {
+  display: grid;
+  grid-template-columns: 2fr 1fr; /* Unequal columns */
+  gap: 48px;
+}
+
+/* Or magazine-style */
+.layout-magazine {
+  display: grid;
+  grid-template-columns: 1fr 2fr 1fr;
+  grid-template-rows: auto auto;
+}
+
+.featured {
+  grid-column: 2 / 3;
+  grid-row: 1 / 3;
+}
+```
+
+### Overlapping Elements
+```css
+.card-overlap {
+  position: relative;
+}
+
+.card-image {
+  position: relative;
+  z-index: 1;
+}
+
+.card-content {
+  position: relative;
+  z-index: 2;
+  margin-top: -60px;
+  margin-left: 40px;
+  background: white;
+  padding: 32px;
+}
+```
+
+### Diagonal Flow
+```css
+.diagonal-section {
+  clip-path: polygon(0 0, 100% 5%, 100% 100%, 0 95%);
+  padding: 120px 0;
+}
+
+/* Or with transform */
+.diagonal-bg {
+  transform: skewY(-3deg);
+}
+
+.diagonal-content {
+  transform: skewY(3deg); /* Counter-rotate content */
+}
+```
+
+---
+
+## Negative Space
+
+### Generous Whitespace
+```css
+.hero {
+  padding: 160px 0;
+  min-height: 100vh;
+}
+
+.section {
+  padding: 120px 0;
+}
+
+.content {
+  max-width: 720px; /* Narrow reading width */
+  margin: 0 auto;
+}
+```
+
+### Controlled Density
+```css
+.dense-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: 8px; /* Tight gap */
+}
+
+.dense-card {
+  padding: 16px;
+  aspect-ratio: 1;
+}
+```
+
+---
+
+## Position Breaking
+
+### Off-center Hero
+```css
+.hero {
+  display: grid;
+  grid-template-columns: 1fr 1.5fr;
+  gap: 80px;
+  align-items: center;
+}
+
+.hero-content {
+  padding-left: 10%; /* Offset from edge */
+}
+
+.hero-image {
+  margin-right: -80px; /* Bleed off edge */
+}
+```
+
+### Sticky Sidebar
+```css
+.layout-sticky {
+  display: grid;
+  grid-template-columns: 300px 1fr;
+  gap: 48px;
+}
+
+.sidebar {
+  position: sticky;
+  top: 24px;
+  height: fit-content;
+}
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Generic | ✅ Distinctive |
+|-----------|---------------|
+| Everything centered | Intentional asymmetry |
+| Equal padding everywhere | Varied spacing with purpose |
+| Straight edges only | Occasional diagonals, curves |
+| No overlap | Strategic layering |
+| Predictable grid | Broken expectations |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [motion-design.md](motion-design.md) | Animate layout transitions |
+| [typography.md](typography.md) | Typography scale for layout hierarchy |
+| [../SKILL.md](../SKILL.md) | Aesthetic directions and constraints |
+
+---
+
+⚡ PikaKit v3.9.134