@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/references/motion-graphics.md

@@ -0,0 +1,306 @@
+# 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.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/frontend-design/references/typography-system.md

@@ -0,0 +1,345 @@
+# Typography System Reference
+
+> Typography principles and decision-making - learn to think, not memorize.
+> **No fixed font names or sizes - understand the system.**
+
+---
+
+## 1. Modular Scale Principles
+
+### What is a Modular Scale?
+
+```
+A mathematical relationship between font sizes:
+├── Pick a BASE size (usually body text)
+├── Pick a RATIO (multiplier)
+└── Generate all sizes using: base × ratio^n
+```
+
+### Common Ratios and When to Use
+
+| Ratio | Value | Feeling | Best For |
+|-------|-------|---------|----------|
+| Minor Second | 1.067 | Very subtle | Dense UI, small screens |
+| Major Second | 1.125 | Subtle | Compact interfaces |
+| Minor Third | 1.2 | Comfortable | Mobile apps, cards |
+| Major Third | 1.25 | Balanced | General web (most common) |
+| Perfect Fourth | 1.333 | Noticeable | Editorial, blogs |
+| Perfect Fifth | 1.5 | Dramatic | Headlines, marketing |
+| Golden Ratio | 1.618 | Maximum impact | Hero sections, display |
+
+### Generate Your Scale
+
+```
+Given: base = YOUR_BASE_SIZE, ratio = YOUR_RATIO
+
+Scale:
+├── xs:  base ÷ ratio²
+├── sm:  base ÷ ratio
+├── base: YOUR_BASE_SIZE
+├── lg:  base × ratio
+├── xl:  base × ratio²
+├── 2xl: base × ratio³
+├── 3xl: base × ratio⁴
+└── ... continue as needed
+```
+
+### Choosing Base Size
+
+| Context | Base Size Range | Why |
+|---------|-----------------|-----|
+| Mobile-first | 16-18px | Readability on small screens |
+| Desktop app | 14-16px | Information density |
+| Editorial | 18-21px | Long-form reading comfort |
+| Accessibility focus | 18px+ | Easier to read |
+
+---
+
+## 2. Font Pairing Principles
+
+### What Makes Fonts Work Together
+
+```
+Contrast + Harmony:
+├── Different ENOUGH to create hierarchy
+├── Similar ENOUGH to feel cohesive
+└── Usually: serif + sans, or display + neutral
+```
+
+### Pairing Strategies
+
+| Strategy | How | Result |
+|----------|-----|--------|
+| **Contrast** | Serif heading + Sans body | Classic, editorial feel |
+| **Same Family** | One variable font, different weights | Cohesive, modern |
+| **Same Designer** | Fonts by same foundry | Often harmonious proportions |
+| **Era Match** | Fonts from same time period | Historical consistency |
+
+### What to Look For
+
+```
+When pairing, compare:
+├── x-height (height of lowercase letters)
+├── Letter width (narrow vs wide)
+├── Stroke contrast (thin/thick variation)
+└── Overall mood (formal vs casual)
+```
+
+### Safe Pairing Patterns
+
+| Heading Style | Body Style | Mood |
+|---------------|------------|------|
+| Geometric sans | Humanist sans | Modern, friendly |
+| Display serif | Clean sans | Editorial, sophisticated |
+| Neutral sans | Same sans | Minimal, tech |
+| Bold geometric | Light geometric | Contemporary |
+
+### Avoid
+
+- ❌ Two decorative fonts together
+- ❌ Similar fonts that conflict
+- ❌ More than 2-3 font families
+- ❌ Fonts with very different x-heights
+
+---
+
+## 3. Line Height Principles
+
+### The Relationship
+
+```
+Line height depends on:
+├── Font size (larger text = less line height needed)
+├── Line length (longer lines = more line height)
+├── Font design (some fonts need more space)
+└── Content type (headings vs body)
+```
+
+### Guidelines by Context
+
+| Content Type | Line Height Range | Why |
+|--------------|-------------------|-----|
+| **Headings** | 1.1 - 1.3 | Short lines, want compact |
+| **Body text** | 1.4 - 1.6 | Comfortable reading |
+| **Long-form** | 1.6 - 1.8 | Maximum readability |
+| **UI elements** | 1.2 - 1.4 | Space efficiency |
+
+### Adjustment Factors
+
+- **Longer line length** → Increase line height
+- **Larger font size** → Decrease line height ratio
+- **All caps** → May need more line height
+- **Tight tracking** → May need more line height
+
+---
+
+## 4. Line Length Principles
+
+### Optimal Reading Width
+
+```
+The sweet spot: 45-75 characters per line
+├── < 45: Too choppy, breaks flow
+├── 45-75: Comfortable reading
+├── > 75: Eye tracking strain
+```
+
+### How to Measure
+
+```css
+/* Character-based (recommended) */
+max-width: 65ch; /* ch = width of "0" character */
+
+/* This adapts to font size automatically */
+```
+
+### Context Adjustments
+
+| Context | Character Range |
+|---------|-----------------|
+| Desktop article | 60-75 characters |
+| Mobile | 35-50 characters |
+| Sidebar text | 30-45 characters |
+| Wide monitors | Still cap at ~75ch |
+
+---
+
+## 5. Responsive Typography Principles
+
+### The Problem
+
+```
+Fixed sizes don't scale well:
+├── Desktop size too big on mobile
+├── Mobile size too small on desktop
+└── Breakpoint jumps feel jarring
+```
+
+### Fluid Typography (clamp)
+
+```css
+/* Syntax: clamp(MIN, PREFERRED, MAX) */
+font-size: clamp(
+  MINIMUM_SIZE,
+  FLUID_CALCULATION,
+  MAXIMUM_SIZE
+);
+
+/* FLUID_CALCULATION typically: 
+   base + viewport-relative-unit */
+```
+
+### Scaling Strategy
+
+| Element | Scaling Behavior |
+|---------|-----------------|
+| Body text | Slight scaling (1rem → 1.125rem) |
+| Subheadings | Moderate scaling |
+| Headings | More dramatic scaling |
+| Display text | Most dramatic scaling |
+
+---
+
+## 6. Weight and Emphasis Principles
+
+### Semantic Weight Usage
+
+| Weight Range | Name | Use For |
+|--------------|------|---------|
+| 300-400 | Light/Normal | Body text, paragraphs |
+| 500 | Medium | Subtle emphasis |
+| 600 | Semibold | Subheadings, labels |
+| 700 | Bold | Headings, strong emphasis |
+| 800-900 | Heavy/Black | Display, hero text |
+
+### Creating Contrast
+
+```
+Good contrast = skip at least 2 weight levels
+├── 400 body + 700 heading = good
+├── 400 body + 500 emphasis = subtle
+├── 600 heading + 700 subheading = too similar
+```
+
+### Avoid
+
+- ❌ Too many weights (max 3-4 per page)
+- ❌ Adjacent weights for hierarchy (400/500)
+- ❌ Heavy weights for long text
+
+---
+
+## 7. Letter Spacing (Tracking)
+
+### Principles
+
+```
+Large text (headings): tighter tracking
+├── Letters are big, gaps feel larger
+└── Slight negative tracking looks better
+
+Small text (body): normal or slightly wider
+├── Improves readability at small sizes
+└── Never negative for body text
+
+ALL CAPS: always wider tracking
+├── Uppercase lacks ascenders/descenders
+└── Needs more space to feel right
+```
+
+### Adjustment Guidelines
+
+| Context | Tracking Adjustment |
+|---------|---------------------|
+| Display/Hero | -2% to -4% |
+| Headings | -1% to -2% |
+| Body text | 0% (normal) |
+| Small text | +1% to +2% |
+| ALL CAPS | +5% to +10% |
+
+---
+
+## 8. Hierarchy Principles
+
+### Visual Hierarchy Through Type
+
+```
+Ways to create hierarchy:
+├── SIZE (most obvious)
+├── WEIGHT (bold stands out)
+├── COLOR (contrast levels)
+├── SPACING (margins separate sections)
+└── POSITION (top = important)
+```
+
+### Typical Hierarchy
+
+| Level | Characteristics |
+|-------|-----------------|
+| Primary (H1) | Largest, boldest, most distinct |
+| Secondary (H2) | Noticeably smaller but still bold |
+| Tertiary (H3) | Medium size, may use weight only |
+| Body | Standard size and weight |
+| Caption/Meta | Smaller, often lighter color |
+
+### Testing Hierarchy
+
+Ask: "Can I tell what's most important at a glance?"
+
+If squinting at the page, the hierarchy should still be clear.
+
+---
+
+## 9. Readability Psychology
+
+### F-Pattern Reading
+
+```
+Users scan in F-pattern:
+├── Across the top (first line)
+├── Down the left side
+├── Across again (subheading)
+└── Continue down left
+```
+
+**Implication**: Key info on left and in headings
+
+### Chunking for Comprehension
+
+- Short paragraphs (3-4 lines max)
+- Clear subheadings
+- Bullet points for lists
+- White space between sections
+
+### Cognitive Ease
+
+- Familiar fonts = easier reading
+- High contrast = less strain
+- Consistent patterns = predictable
+
+---
+
+## 10. Typography Selection Checklist
+
+Before finalizing typography:
+
+- [ ] **Asked user for font preferences?**
+- [ ] **Considered brand/context?**
+- [ ] **Selected appropriate scale ratio?**
+- [ ] **Limited to 2-3 font families?**
+- [ ] **Tested readability at all sizes?**
+- [ ] **Checked line length (45-75ch)?**
+- [ ] **Verified contrast for accessibility?**
+- [ ] **Different from your last project?**
+
+### Anti-Patterns
+
+- ❌ Same fonts every project
+- ❌ Too many font families
+- ❌ Ignoring readability for style
+- ❌ Fixed sizes without responsiveness
+- ❌ Decorative fonts for body text
+
+---
+
+> **Remember**: Typography is about communication clarity. Choose based on content needs and audience, not personal preference.