TheGoat395/Codex-Skills / skills/design-motion-principles
design-motion-principles
VerifiedMotion through Kowalski, Krehel and Jhey lenses.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
| agents/openai.yaml | config | 264 B |
| references/accessibility.md | markdown | 2.5 KB |
| references/anti-checklist.md | markdown | 13.4 KB |
| references/audit-checklist.md | markdown | 5.5 KB |
| references/creation-gotchas.md | markdown | 3.5 KB |
| references/demo-shell.html | other | 14.5 KB |
| references/emil-kowalski.md | markdown | 6.5 KB |
| references/jakub-krehel.md | markdown | 4.8 KB |
| references/jhey-tompkins.md | markdown | 6.1 KB |
| references/motion-cookbook.md | markdown | 18.3 KB |
| references/output-format.md | markdown | 18.0 KB |
| references/performance.md | markdown | 1.6 KB |
| references/report-template.html | other | 64.3 KB |
| workflows/audit.md | markdown | 12.7 KB |
| workflows/create.md | markdown | 4.4 KB |
references/motion-cookbook.md
View on GitHub# Motion Cookbook
The single source of truth for motion **recipes** — implementation patterns and code. In Create mode this is your primary reference; in Audit mode load it when making implementation recommendations. Designer philosophy and decision frameworks live in the per-designer reference files; the code lives here.
---
## 1. Enter & Exit Animations
### Enter Animation Recipe (Jakub)
A standard enter animation combines three properties:
- **Opacity**: 0 → 1
- **TranslateY**: ~8px → 0 (or calc(-100% - 4px) for full container slides)
- **Blur**: 4px → 0px
```jsx
initial={{ opacity: 0, translateY: "calc(-100% - 4px)", filter: "blur(4px)" }}
animate={{ opacity: 1, translateY: 0, filter: "blur(0px)" }}
transition={{ type: "spring", duration: 0.45, bounce: 0 }}
```
**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.
### Exit Animation Subtlety (Jakub)
**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 with whatever is entering or remaining.
**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
### Fill Mode for Persistence (Jhey)
Use `animation-fill-mode` to prevent jarring visual resets:
- `forwards`: Element retains animation styling after completion
- `backwards`: Element 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.
---
## 2. Easing & Timing
### Duration Impacts Naturalness
> "Duration is all about timing, and timing has a big impact on the movement's naturalness." — Jhey Tompkins
### Custom Easing is Essential (Emil)
> "Easing is the most important part of any animation. It can make a bad animation feel great."
Choose easing for context and continuity. Custom Bézier curves and springs give control; a suitable built-in curve is not automatically defective. Resources: easing.dev, easings.co
### Easing Selection Guidelines (Jhey)
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. A playful brand can use bouncy, elastic easing. A professional brand should use 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
### Spring Animations (Jakub)
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.
### The linear() Function (Jhey)
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
);
}
```
Use Jake Archibald's linear() generator for custom curves: https://linear-easing-generator.netlify.app/
### Stagger Techniques (Jhey)
`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 within the animation:
```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.
---
## 3. Visual Effects
### Shadows Instead of Borders (Jakub)
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) because they use 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 with `transition: box-shadow`
**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 (Jakub)
- Use `oklch` for gradients to avoid muddy midpoints:
```css
element { background: linear-gradient(in oklch, blue, red); }
```
- **Color hints** control where the blend midpoint appears (different from color stops)
- Layer gradients with `background-blend-mode` for unique effects
**Why oklch?** It interpolates through perceptually uniform color space, avoiding the gray/muddy zone that sRGB hits when blending complementary colors.
### Blur as a Signal (Jakub)
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
---
## 4. Optical Alignment
### Geometric vs. Optical (Jakub)
> "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.
**Icons in general**: Many icon packs account for optical balance, but asymmetric shapes (arrows, play, chevrons) may need manual margin/padding adjustment.
**The rule**: If it looks wrong despite being mathematically correct, trust your eyes and adjust.
---
## 5. Icon & State Animations (Jakub)
### Contextual Icon Transitions
When useful for a contextual icon state (copy → check, loading → done), consider:
- Opacity
- Scale
- Blur
```jsx
import { AnimatePresence, motion, useReducedMotion } from "motion/react";
// Presentation only: the caller performs the real copy and owns isCopied.
export function CopyStateIcon({ isCopied }) {
const reduce = useReducedMotion();
return (
<span aria-hidden="true" style={{ display: "inline-grid", width: 20, height: 20 }}>
<AnimatePresence initial={false} mode="wait">
<motion.span
key={isCopied ? "copied" : "copy"}
initial={reduce ? false : { opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={reduce ? { opacity: 1 } : { opacity: 0, scale: 0.95 }}
transition={{ duration: reduce ? 0 : 0.15 }}
style={{ display: "inline-grid", placeItems: "center" }}
>
{isCopied ? "✓" : "⧉"}
</motion.span>
</AnimatePresence>
</span>
);
}
// Caller supplies the accessible button label and status announcement.
```
**Why consider icon motion?** When a change is being missed, a brief transition can reinforce it; an understandable instant swap is valid. Suitable transitions:
- Draw attention to the state change
- Feel responsive and polished
- Give the user confidence their action registered
---
## 6. Shared Layout Animations (Jakub)
### 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
- `layoutId` works with `AnimatePresence`, which can retain the outgoing element for its exit/shared transition.
- Coordinate presence, layout and opacity deliberately; test shared transitions and avoid unintended overlapping effects.
- Multiple elements can animate if each has a unique `layoutId`
- Works for different heights, widths, positions, and even component types (card → modal)
---
## 7. CSS Custom Properties & @property (Jhey)
### 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
For independently eased axes, split motion into typed properties. Monolithic keyframes, motion paths or wrappers can also express 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 gives the axes independent interpolation; validate the intended arc and intermediate keyframe values. CSS motion paths or ordinary multi-keyframe transforms are alternatives.
### Scoped Variables for Dynamic Behavior (Jhey)
CSS custom properties respect scope, enabling powerful patterns:
```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.
---
## 8. 3D CSS (Jhey)
### Think in Cuboids
> "Think in cubes instead of boxes" — Jhey Tompkins
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);
}
```
---
## 9. Clip-Path Animations (Emil)
### Why clip-path?
- Potential compositing benefits for supported shapes; measure actual paint/raster cost
- No layout shifts
- No additional DOM elements needed
- Can avoid layout work; bounded size/layout animation may still fit content flow better
### Basic Syntax
```css
clip-path: inset(top right bottom left);
clip-path: circle(radius at x y);
clip-path: polygon(coordinates);
```
### Image Reveal Effect
```css
.reveal { clip-path: inset(0); } /* Complete without animation. */
@media (prefers-reduced-motion: no-preference) {
.reveal { animation: reveal 1s both cubic-bezier(0.77, 0, 0.175, 1); }
@keyframes reveal {
from { clip-path: inset(0 0 100% 0); }
to { clip-path: inset(0); }
}
}
```
### Tab Transitions
Duplicate tab lists with different styling. Animate the overlay's clip-path to reveal only the active tab—creates smooth color transitions without timing issues.
### Scroll-Driven with clip-path
```javascript
const clipPathY = useTransform(scrollYProgress, [0, 1], ["100%", "0%"]);
const motionClipPath = useMotionTemplate`inset(0 0 ${clipPathY} 0)`;
```
### Text Mask Effect
Stack elements with complementary clip-paths:
```css
.top { clip-path: inset(0 0 50% 0); } /* Shows top half */
.bottom { clip-path: inset(50% 0 0 0); } /* Shows bottom half */
```
Adjust values on mouse interaction for seamless transitions.
---
## 10. Button & Interactive Feedback (Emil)
### Scale on Press
Add immediate tactile feedback:
```css
button:active {
transform: scale(0.97);
}
```
### Choose an Appropriate Scale Range
```jsx
// Strong emergence: reserve for an effect that warrants the range
initial={{ scale: 0 }}
// Restrained alternative for routine UI
initial={{ scale: 0.9, opacity: 0 }}
animate={{ scale: 1, opacity: 1 }}
```
### Tooltip Delay Pattern
First tooltip in a group: delay + animation. Subsequent tooltips: instant.
```css
[data-instant] {
transition-duration: 0ms;
}
```
### Blur as a Bridge
When state transitions aren't smooth enough, add blur to mask imperfections:
```css
.transitioning {
filter: blur(2px);
}
```
---
## 11. CSS Transitions vs Keyframes (Emil)
### Interruptibility Problem
CSS keyframe animations can be cancelled, paused or controlled through animation APIs, but changing their endpoint does not automatically provide smooth retargeting. Test rapid retriggering; transitions or a suitable motion API may preserve continuity better.
**Solution**: Use CSS transitions with state-driven classes:
```jsx
useEffect(() => {
setMounted(true);
}, []);
```
```css
.element {
transform: translateY(100%);
transition: transform 400ms ease;
}
.element.mounted {
transform: translateY(0);
}
```
### Direct Style Updates for Performance
Inherited CSS variables can cause wider style invalidation. For frequent updates, compare scoped/non-inherited variables and direct styles in actual traces; use the smallest measured update surface:
```javascript
// May invalidate descendants when inherited; measure and scope carefully
element.style.setProperty('--drag-y', `${y}px`);
// Direct update narrows the changed style; rendering cost still depends on the property
element.style.transform = `translateY(${y}px)`;
```
### Momentum-Based Dismissal
Consider displacement and recent release velocity together. Define the axis, direction, units and thresholds from the interaction; average speed across the entire drag can misread a paused or reversed gesture. Test slow deliberate drags, quick short flicks, cancellation and a non-gesture close control. A framework's documented gesture velocity can supply the recent sample; do not treat a unitless magic number as a universal threshold.
### Damping for Natural Boundaries
When dragging past boundaries, reduce movement progressively. Things in real life slow down before stopping.
---
## 12. Spring Physics (Emil)
### Key Parameters
| Parameter | Effect |
|-----------|--------|
| **Stiffness** | How quickly spring reaches target (higher = faster) |
| **Damping** | How quickly oscillations settle (higher = less bounce) |
| **Mass** | Weight of object (higher = more momentum) |
### Spring for Mouse Position
```javascript
const springConfig = { stiffness: 300, damping: 30 };
const x = useSpring(mouseX, springConfig);
const y = useSpring(mouseY, springConfig);
```
Use `useSpring` when interpolation improves the interaction; instant values and direct manipulation remain valid.
### Interruptibility
Great animations can be interrupted mid-play:
- Framer Motion supports interruption natively
- CSS transitions allow smooth interruption before completion
- Test by clicking rapidly—animations should blend, not queue
---
## 13. Origin-Aware Animations (Emil)
Animations should originate from their logical source:
```css
/* Dropdown from button should expand from button, not center */
.dropdown {
transform-origin: top center;
}
```
**Component library support:**
- Base UI: `--transform-origin` CSS variable
- Radix UI: `--radix-dropdown-menu-content-transform-origin`
---
## 14. Scroll-Driven Animations (Jhey)
### The Core Problem
A scroll/view-progress timeline maps scroll position or visibility to animation progress. This is useful for scrubbing and spatial narratives. A one-shot entrance instead needs a trigger followed by a time-based animation; choose from the requested behavior, not a rule that scrubbing is wrong.
### Duration Control Pattern
For a compatible experimental setup, one approach uses 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, regardless of how fast the user scrolled.
### Progressive Enhancement
Verify support for every feature in the chosen pattern, including style queries; an `animation-timeline` check alone does not prove the entire composition works. A conventional IntersectionObserver trigger is sufficient for many one-shot entrances. Preserve visible static content and reduced motion. [Timeline semantics](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/animation-timeline).
Provide fallbacks:
```javascript
// IntersectionObserver fallback for browsers without scroll-driven animation support
if (!CSS.supports('animation-timeline', 'scroll()')) {
// Use IntersectionObserver instead
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |