@its-thepoe/design-motion-principles 1.0.0

package/references/jakub-krehel.md

@@ -0,0 +1,317 @@
+# Jakub Krehel's Animation Principles
+
+Jakub Krehel is a design engineer known for his work at jakub.kr. His approach emphasizes **subtle production polish**—animations that enhance the experience invisibly, designed for real client work where users will interact repeatedly.
+
+---
+
+## Core Philosophy: Invisible Enhancement
+
+> "The best animation is that which goes unnoticed."
+
+Jakub's work embodies **refinement for production use**. His animations are:
+
+- **Barely noticeable** — If users consciously notice the animation, it's probably too much
+- **Production-ready** — Designed for real client work, not demos
+- **Contextually appropriate** — Adapts to light mode, varied backgrounds, real content
+- **Subtle over flashy** — The goal is to make interfaces feel smooth and responsive, not impressive
+
+**The best compliment**: "This feels really nice" — not "cool animation!"
+
+**The test**: If you remove the animation, do users feel something is missing? Good. If users comment "nice animation!" every time they see it? Too prominent.
+
+---
+
+## When to Apply Jakub's Mindset
+
+- Production applications and client work
+- Professional/enterprise interfaces
+- When users will interact repeatedly (animations must not get tiresome)
+- When accessibility and performance are critical
+- When you need polish without distraction
+
+---
+
+## Enter Animation Recipe
+
+A standard enter animation combines three properties:
+
+```jsx
+initial={{ opacity: 0, translateY: 8, filter: "blur(4px)" }}
+animate={{ opacity: 1, translateY: 0, filter: "blur(0px)" }}
+transition={{ type: "spring", duration: 0.45, bounce: 0 }}
+```
+
+| Property | From | To | Purpose |
+|----------|------|-----|---------|
+| Opacity | 0 | 1 | Fade in |
+| TranslateY | 8px | 0 | Subtle upward movement |
+| Blur | 4px | 0px | "Materializing" effect |
+
+**Why blur?** It creates a "materializing" effect that feels more physical than opacity alone. The element appears to come into focus, not just fade in.
+
+For full container slides, use `translateY: "calc(-100% - 4px)"` instead of fixed pixels.
+
+---
+
+## Exit Animation Subtlety
+
+**Key Insight**: Exit animations should be subtler than enter animations.
+
+When a component exits, it doesn't need the same amount of movement or attention as when entering. The user's focus is moving to what comes next, not what's leaving.
+
+```jsx
+// Instead of full exit movement:
+exit={{ translateY: "calc(-100% - 4px)" }}
+
+// Use a subtle fixed value:
+exit={{ translateY: "-12px", opacity: 0, filter: "blur(4px)" }}
+```
+
+**Why this works**: Exits become softer, less jarring, and don't compete for attention.
+
+**When NOT to use subtle exits**:
+- When the exit itself is meaningful (user-initiated dismissal)
+- When you need to emphasize something leaving (error clearing, item deletion)
+- Full-page transitions where directional continuity matters
+
+---
+
+## Spring Animations
+
+Prefer spring animations over linear/ease for more natural-feeling motion:
+
+```jsx
+transition={{ type: "spring", duration: 0.45, bounce: 0 }}
+transition={{ type: "spring", duration: 0.55, bounce: 0.1 }}
+```
+
+**Why `bounce: 0`?** It gives smooth deceleration without overshoot—professional and refined.
+
+**Reserve bounce > 0** for playful contexts only.
+
+---
+
+## Shadows Instead of Borders
+
+In light mode, prefer subtle multi-layer box-shadows over solid borders:
+
+```css
+.card {
+  box-shadow:
+    0px 0px 0px 1px rgba(0, 0, 0, 0.06),
+    0px 1px 2px -1px rgba(0, 0, 0, 0.06),
+    0px 2px 4px 0px rgba(0, 0, 0, 0.04);
+}
+
+/* Slightly darker on hover */
+.card:hover {
+  box-shadow:
+    0px 0px 0px 1px rgba(0, 0, 0, 0.08),
+    0px 1px 2px -1px rgba(0, 0, 0, 0.08),
+    0px 2px 4px 0px rgba(0, 0, 0, 0.06);
+}
+```
+
+**Why shadows over borders?**
+- Shadows adapt to any background (images, gradients, varied colors) via transparency
+- Borders are solid colors that may clash with dynamic backgrounds
+- Multi-layer shadows create depth; single borders feel flat
+- Shadows can be transitioned smoothly
+
+**When borders are fine**:
+- Dark mode (shadows less visible anyway)
+- When you need hard edges intentionally
+- Simple interfaces where depth isn't needed
+
+---
+
+## Gradients & Color Spaces
+
+Use `oklch` for gradients to avoid muddy midpoints:
+
+```css
+.element {
+  background: linear-gradient(in oklch, blue, red);
+}
+```
+
+**Why oklch?** It interpolates through perceptually uniform color space, avoiding the gray/muddy zone that sRGB hits when blending complementary colors.
+
+**Color hints** control where the blend midpoint appears (different from color stops).
+
+Layer gradients with `background-blend-mode` for unique effects.
+
+---
+
+## Blur as a Signal
+
+Blur (via `filter: blur()`) combined with opacity and translate creates a "materializing" effect. Use blur to signal:
+
+- **Entering focus**: blur → sharp
+- **Losing relevance**: sharp → blur
+- **State transitions**: blur during, sharp after
+
+---
+
+## Optical Alignment
+
+> "Sometimes it's necessary to break out of geometric alignment to make things feel visually balanced."
+
+### Buttons with Icons
+Reduce padding on the icon side so content appears centered:
+```
+[  Icon Text  ] ← Geometric (mathematically centered, feels off)
+[ Icon Text   ] ← Optical (visually centered, feels right)
+```
+
+### Play Button Icons
+The triangle points right, creating visual weight on the left. Shift it slightly right to appear centered.
+
+### The Rule
+If it looks wrong despite being mathematically correct, trust your eyes and adjust.
+
+---
+
+## Icon & State Animations
+
+When icons change contextually (copy → check, loading → done), animate:
+- Opacity
+- Scale
+- Blur
+
+```jsx
+<AnimatePresence mode="wait">
+  {isCopied ? (
+    <motion.div
+      initial={{ opacity: 0, scale: 0.8, filter: "blur(4px)" }}
+      animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+      exit={{ opacity: 0, scale: 0.8, filter: "blur(4px)" }}
+    >
+      <CheckIcon />
+    </motion.div>
+  ) : (
+    <motion.div ...>
+      <CopyIcon />
+    </motion.div>
+  )}
+</AnimatePresence>
+```
+
+**Why animate icon swaps?** Instant swaps feel jarring and can be missed. Animated transitions:
+- Draw attention to the state change
+- Feel responsive and polished
+- Give the user confidence their action registered
+
+---
+
+## Shared Layout Animations
+
+### FLIP Technique via layoutId
+
+Motion's `layoutId` prop enables smooth transitions between completely different components:
+
+```jsx
+// In one location:
+<motion.div layoutId="card" className="small-card" />
+
+// In another location:
+<motion.div layoutId="card" className="large-card" />
+```
+
+Motion automatically animates between them using the FLIP technique (First, Last, Inverse, Play).
+
+### Best Practices
+- Keep elements with `layoutId` **outside** of `AnimatePresence` to avoid conflicts
+- If inside `AnimatePresence`, initial/exit animations trigger during layout animation (looks bad)
+- Multiple elements can animate if each has a unique `layoutId`
+- Works for different heights, widths, positions, and component types
+
+---
+
+## will-change Performance
+
+A hint to the browser: "I'm about to animate these properties, please prepare."
+
+```css
+/* Good - specific properties that will animate */
+.animated-button {
+  will-change: transform, opacity;
+}
+
+/* Bad - too broad, wastes resources */
+* { will-change: auto; }
+.element { will-change: all; }
+```
+
+**Properties that benefit from will-change**:
+- transform
+- opacity
+- filter (blur, brightness)
+- clip-path
+- mask
+
+**Why it matters**: Without the hint, the browser promotes elements to GPU layers only when animation starts, causing first-frame stutter.
+
+**When NOT to use**:
+- On elements that won't animate
+- On too many elements (each GPU layer uses memory)
+- As a "fix" for janky animations (find the real cause)
+
+---
+
+## Gradient Animation Performance
+
+**Cheap to animate (GPU-accelerated)**:
+- background-position
+- background-size
+- opacity
+
+**Expensive to animate**:
+- Color stops
+- Adding/removing gradient layers
+- Switching gradient types
+
+**Tip**: Animate a pseudo-element overlay or use CSS variables that transition indirectly.
+
+---
+
+## Common Mistakes (Jakub's Perspective)
+
+- **Making enter and exit animations equally prominent** — Exits should be subtler
+- **Using solid borders when shadows would adapt better** — Especially on varied backgrounds
+- **Forgetting optical alignment** — Buttons with icons, play buttons, asymmetric shapes
+- **Over-animating** — If users notice the animation itself, it's too much
+- **Using the same animation everywhere** — Context should drive timing and easing choices
+- **Ignoring hover state transitions** — Even small transitions (150-200ms) feel more polished than instant changes
+
+---
+
+## Jakub's Technique Index
+
+From jakub.kr:
+
+| Technique | Key Insight |
+|-----------|-------------|
+| Enter Animation | Opacity + translateY + blur creates "materializing" effect |
+| Exit Animations | Subtler than enters, don't compete for attention |
+| Shadows vs Borders | Shadows adapt to varied backgrounds via transparency |
+| Gradients | Use oklch color space for smooth blending |
+| Optical Alignment | Trust your eyes over mathematical centering |
+| Shared Layout | layoutId enables FLIP-based smooth transitions |
+| will-change | Specific properties only, not everywhere |
+| Icon Animations | Animate swaps with opacity + scale + blur |
+| Spring Animations | bounce: 0 for professional, bounce > 0 for playful |
+| Motion Gestures | Micro-interactions for tactile feedback |
+
+---
+
+## Jakub vs. Emil vs. Jhey
+
+| Aspect | Jakub | Emil | Jhey |
+|--------|-------|------|------|
+| **Focus** | Subtle polish | Restraint & speed | Playful experimentation |
+| **Key question** | "Is this subtle enough?" | "Should this animate?" | "What could this become?" |
+| **Signature technique** | Blur + opacity + translateY | Frequency-based decisions | CSS custom properties |
+| **Ideal context** | Production polish | High-frequency tools | Learning & exploration |
+
+**When to use Jakub**: You've decided something should animate (passed Emil's gate) and need to make it production-ready and polished.

package/references/jhey-tompkins.md

@@ -0,0 +1,367 @@
+# Jhey Tompkins' Animation Principles
+
+Jhey Tompkins (@jh3yy) is a design engineer known for pushing the boundaries of CSS and creative coding. His approach emphasizes **playful experimentation**—learning through building whimsical projects where the joy of creation drives skill development.
+
+---
+
+## Core Philosophy: Learn Through Play
+
+> "I went from 'I want to learn X, so how do I fit it into Y' to 'I want to make Y, can I learn X to do it?'"
+
+**The motivation should be making something cool—learning is a happy side effect.**
+
+### Core Beliefs
+
+- **No idea is a bad idea** — Document every spark, however weird (toadstools, Peter Griffin blinds, bread array slice/splice cartoon)
+- **Don't ask "Why?" or "Is this practical?"** — Make what brings you joy first
+- **"Useless" demos teach real skills** — CSS art teaches clip-path mastery, border-radius tricks, stacking contexts
+- **Lateral learning** — Building diverse demos trains you to switch contexts and rise to challenges
+- **You'll never have time to make everything** — And that's okay. The act of documenting ideas matters.
+
+### The Playfulness Philosophy
+
+Playfulness in code supercharges learning. The fact you're learning new skills is a bonus, not the goal. Work on ideas that spark joy for you.
+
+**Keep notebooks everywhere** — including by your bed. Creative sparks happen at random times.
+
+---
+
+## When to Apply Jhey's Mindset
+
+- Learning new techniques
+- Personal projects and experiments
+- When you're stuck in a creative rut
+- Building your portfolio or demos
+- Exploring what's possible with new CSS features
+- When tutorials aren't clicking—try building something weird instead
+
+---
+
+## The Golden Rule
+
+> "The best animation is that which goes unnoticed."
+
+Jhey references this as a saying that has always stuck with him. Even in playful contexts, effective motion:
+- Enhances the experience without demanding attention
+- Feels natural and expected
+- Serves a functional purpose
+- Doesn't fatigue users on repeated interactions
+
+---
+
+## Easing & Timing
+
+### Duration Impacts Naturalness
+
+> "Duration is all about timing, and timing has a big impact on the movement's naturalness."
+
+### Easing Selection Guidelines
+
+Each easing curve communicates something to the viewer. **Context matters more than rules.**
+
+| Easing | Feel | Good For |
+|--------|------|----------|
+| `ease-out` | Fast start, gentle stop | Elements entering view (arriving) |
+| `ease-in` | Gentle start, fast exit | Elements leaving view (departing) |
+| `ease-in-out` | Gentle both ends | Elements changing state while visible |
+| `linear` | Constant speed | Continuous loops, progress indicators |
+| `spring` | Natural deceleration | Interactive elements, professional UI |
+
+### The Context Rule
+
+> "You wouldn't use 'Elastic' for a bank's website, but it might work perfectly for an energetic site for children."
+
+Brand personality should drive easing choices:
+- Playful brand → bouncy, elastic easing
+- Professional brand → subtle springs or ease-out
+
+**When NOT to use bouncy/elastic easing**:
+- Professional/enterprise applications
+- Frequently repeated interactions (gets tiresome)
+- Error states or serious UI
+- When users need to complete tasks quickly
+
+---
+
+## The linear() Function
+
+CSS `linear()` enables bounce, elastic, and spring effects in pure CSS:
+
+```css
+:root {
+  --bounce-easing: linear(
+    0, 0.004, 0.016, 0.035, 0.063, 0.098, 0.141 13.6%, 0.25, 0.391, 0.563, 0.765,
+    1, 0.891 40.9%, 0.848, 0.813, 0.785, 0.766, 0.754, 0.75, 0.754, 0.766, 0.785,
+    0.813, 0.848, 0.891 68.2%, 1 72.7%, 0.973, 0.953, 0.941, 0.938, 0.941, 0.953,
+    0.973, 1, 0.988, 0.984, 0.988, 1
+  );
+}
+```
+
+**Tool**: Use Jake Archibald's linear() generator: https://linear-easing-generator.netlify.app/
+
+---
+
+## Animation Fill Mode
+
+Use `animation-fill-mode` to prevent jarring visual resets:
+
+| Mode | Behavior |
+|------|----------|
+| `forwards` | Retains animation styling after completion |
+| `backwards` | Retains style from first keyframe before animation starts |
+| `both` | Retains styling in both directions |
+
+**Critical for**: Fade-in sequences with delays. Without `backwards`, elements flash at full opacity before their delayed animation starts, then pop to invisible, then fade in.
+
+---
+
+## Stagger Techniques
+
+`animation-delay` only applies once (not per iteration). Approaches:
+
+### 1. Different delays with finite iterations
+Works for one-time sequences.
+
+### 2. Pad keyframes to create stagger
+```css
+@keyframes spin {
+  0%, 50% { transform: rotate(0deg); }
+  100% { transform: rotate(360deg); }
+}
+```
+
+### 3. Negative delays for "already in progress" effects
+```css
+.element {
+  animation-delay: calc(var(--index) * -0.2s);
+}
+```
+
+This makes animations appear mid-flight from the start—useful for staggered continuous animations.
+
+---
+
+## CSS Custom Properties & @property
+
+### Type Specification Unlocks Animation
+
+The `@property` rule lets you declare types for CSS variables, enabling smooth interpolation:
+
+```css
+@property --hue {
+  initial-value: 0;
+  inherits: false;
+  syntax: '<number>';
+}
+
+@keyframes rainbow {
+  to { --hue: 360; }
+}
+```
+
+**Available types**: length, number, percentage, color, angle, time, integer, transform-list
+
+**Why this matters**: Without `@property`, CSS sees custom properties as strings. Strings can't interpolate—they just swap. With a declared type, the browser knows how to smoothly transition between values.
+
+### Decompose Complex Transforms
+
+Instead of animating a monolithic transform, split into typed properties for curved paths:
+
+```css
+@property --x { syntax: '<percentage>'; initial-value: 0%; inherits: false; }
+@property --y { syntax: '<percentage>'; initial-value: 0%; inherits: false; }
+
+.ball {
+  transform: translateX(var(--x)) translateY(var(--y));
+  animation: throw 1s;
+}
+
+@keyframes throw {
+  0% { --x: -500%; }
+  50% { --y: -250%; }
+  100% { --x: 500%; }
+}
+```
+
+This creates curved motion paths impossible with standard transform animation—the ball arcs through space rather than moving in straight lines.
+
+### Scoped Variables for Dynamic Behavior
+
+CSS custom properties respect scope:
+
+```css
+.item { --delay: 0; animation-delay: calc(var(--delay) * 100ms); }
+.item:nth-child(1) { --delay: 0; }
+.item:nth-child(2) { --delay: 1; }
+.item:nth-child(3) { --delay: 2; }
+```
+
+Use scoped variables to create varied behavior from a single animation definition.
+
+---
+
+## 3D CSS
+
+### Think in Cuboids
+
+> "Think in cubes instead of boxes"
+
+Complex 3D scenes are assemblies of cube-shaped elements (like LEGO). Decompose any 3D object into cuboids.
+
+### Essential Setup
+
+```css
+.scene {
+  transform-style: preserve-3d;
+  perspective: 1000px;
+}
+```
+
+### Responsive 3D
+
+Use CSS variables for dimensions and `vmin` units:
+
+```css
+.cube {
+  --size: 10vmin;
+  width: var(--size);
+  height: var(--size);
+}
+```
+
+---
+
+## Scroll-Driven Animations
+
+### The Core Problem
+
+Scroll-driven animations are tied to scroll **speed**. If users scroll slowly, animations play slowly. This feels wrong for most UI—you want animations to trigger at a scroll position, not be controlled by scroll speed.
+
+### Duration Control Pattern
+
+Use two coordinated animations:
+
+1. **Trigger animation**: Scroll-driven, toggles a custom property when element enters view
+2. **Main animation**: Traditional duration-based, activated via Style Query
+
+This severs the connection between scroll speed and animation timing—the animation runs over a fixed duration once triggered.
+
+### Progressive Enhancement
+
+Always provide fallbacks:
+
+```javascript
+if (!CSS.supports('animation-timeline', 'scroll()')) {
+  // Use IntersectionObserver instead
+}
+```
+
+---
+
+## CSS Art & Illustrations
+
+### Why CSS Art Matters
+
+CSS art teaches real skills that transfer to production work:
+- clip-path mastery
+- Border-radius tricks
+- Stacking contexts
+- Complex gradients
+- Pseudo-element layering
+
+### Advice for Complex Illustrations
+
+- Break down into simple shapes
+- Use pseudo-elements liberally (`:before`, `:after`)
+- Layer with z-index carefully
+- Use CSS variables for repeated values
+- Don't be afraid to use many elements
+
+---
+
+## Motion Paths
+
+### Responsive Motion Paths
+
+```css
+.element {
+  offset-path: path('M 0 0 Q 50 100 100 0');
+  animation: move 2s ease-in-out infinite alternate;
+}
+
+@keyframes move {
+  to { offset-distance: 100%; }
+}
+```
+
+For responsive paths, calculate path coordinates based on container size using CSS variables or JavaScript.
+
+---
+
+## Common Mistakes (Jhey's Perspective)
+
+- **Filtering ideas based on "usefulness" too early** — Make first, judge later
+- **Not documenting random creative sparks** — Keep notebooks everywhere, including by your bed
+- **Thinking CSS art is useless** — It teaches real skills (clip-path, layering, complex shapes)
+- **Focusing on "How do I learn X?" instead of "How do I make Y?"** — Let ideas drive learning
+- **Following tutorials without experimenting** — Tutorials teach techniques; experimentation teaches problem-solving
+- **Giving up when something doesn't work** — The struggle is where learning happens
+
+---
+
+## When to Experiment vs. Ship
+
+| Situation | Approach |
+|-----------|----------|
+| Learning new CSS feature | Build something weird and fun |
+| Portfolio piece | Push boundaries, show creativity |
+| Personal project | Follow your joy |
+| Client work | Apply Jakub's production polish instead |
+| High-frequency tool | Apply Emil's restraint instead |
+
+The playful approach is for **learning and exploration**. For production, switch to Jakub or Emil's mindset.
+
+---
+
+## Jhey's Technique Index
+
+| Technique | Key Insight |
+|-----------|-------------|
+| linear() function | Pure CSS bounce/elastic/spring effects |
+| @property | Type specification enables CSS variable animation |
+| animation-fill-mode | Prevent flash before delayed animations |
+| Negative delays | "Already in progress" stagger effects |
+| 3D CSS | Think in cubes, use preserve-3d |
+| Scroll-driven | Decouple scroll speed from animation duration |
+| CSS art | "Useless" demos teach real skills |
+| Scoped variables | Varied behavior from single animation |
+
+---
+
+## Jhey's Article Index
+
+From Smashing Magazine, CSS-Tricks, and more:
+
+| Article | Topic |
+|---------|-------|
+| Playfulness In Code | Philosophy of learning through fun |
+| The Path To Awesome CSS Easing With linear() | Custom easing in pure CSS |
+| Exploring @property | Animating CSS custom properties |
+| CSS in 3D: Thinking in Cubes | 3D CSS fundamentals |
+| Advice for Complex CSS Illustrations | CSS art techniques |
+| Scroll-Driven Animation with Duration | Decoupling scroll from timing |
+| The Power of Scope with CSS Custom Properties | Dynamic behavior patterns |
+
+---
+
+## Jhey vs. Emil vs. Jakub
+
+| Aspect | Jhey | Emil | Jakub |
+|--------|------|------|-------|
+| **Focus** | Playful experimentation | Restraint & speed | Subtle polish |
+| **Key question** | "What could this become?" | "Should this animate?" | "Is this subtle enough?" |
+| **Signature technique** | CSS custom properties | Frequency-based decisions | Blur + opacity + translateY |
+| **Ideal context** | Learning & exploration | High-frequency tools | Production polish |
+
+**When to use Jhey**: You're learning something new, exploring what's possible, or building something for the joy of it. The skills transfer to production work later.