Motion Design
Purpose
Design motion systems for digital products: animation principles, micro-interactions, transitions, Lottie animations, and motion guidelines that enhance user experience. Motion should serve a functional purpose — guiding attention, providing feedback, communicating hierarchy, and creating continuity between states.
Agent Protocol
Trigger
Exact user phrases: "motion design", "animation", "micro-interaction", "Lottie", "transition", "UI animation", "motion guidelines", "easing", "keyframe animation", "spring animation", "motion system".
Input Context
- What is the product type and platform (web, mobile, native)?
- What is the purpose of the animation (feedback, navigation, delight)?
- What existing motion system or design system is in place?
- What are the performance constraints (device targets, frame rate)?
- What accessibility requirements exist (reduced motion preferences)?
- What is the animation complexity budget?
Output Artifact
Motion design system with animation principles, duration/easing specifications, micro-interaction patterns, and implementation guidelines.
Response Format
## Motion Design Specification
### Animation Principles
{principle}: {application}
### Timing Scale
{action}: {duration} | {easing} | {use case}
### Micro-interaction Patterns
{pattern}: {trigger} → {animation} → {feedback}
### Implementation
{platform}: {technique} | {code example}
No preamble. No postamble. No explanations.
Completion Criteria
Max Response Length
150 lines of spec and patterns.
Framework/Methodology
Functional Motion Framework
All motion in UI should serve one of four functional roles:
| Role |
Purpose |
Example |
Duration |
| Feedback |
Confirm user action |
Button press, toggle switch |
100-200ms |
| Focus |
Direct user attention |
Notification, error state |
200-400ms |
| Continuity |
Maintain context during change |
Page transition, element morph |
200-500ms |
| Expression |
Communicate brand personality |
Logo animation, loading |
400-1000ms |
Motion Design Process
User Need → Which functional role?
↓
Role → Which pattern?
↓
Pattern → Timing & Easing
↓
Spec → Implementation (CSS, Lottie, Rive, etc.)
↓
QA → Verify reduced motion, performance, feel
Animation Complexity Budget
| Complexity |
Description |
Performance Impact |
When to Use |
| Minimal |
0-5 animated elements, simple CSS transitions |
Negligible |
Critical tasks, data-heavy screens |
| Moderate |
5-15 animated elements, coordinated timing |
Low |
Standard UI transitions, navigation |
| Complex |
15+ animated elements, staggered choreography |
Medium |
Marketing, onboarding, celebrations |
| Heavy |
Full-scene animation, particle systems, video |
High |
Splash screens, immersive experiences |
Motion Design Principles
| Principle |
UI Application |
| Easing |
Natural acceleration/deceleration, not linear |
| Duration |
Short for functional (100-300ms), longer for expressive (300-500ms) |
| Stagger |
Offset animations for visual interest |
| Hierarchy |
Important elements animate first |
| Spatial continuity |
Elements should animate as if in physical space |
| Transformation |
Same element morphs between states; don't replace |
| Masking |
Use reveal/conceal to manage attention |
| Depth |
Use scale, shadow, and blur for z-space |
| Overlap |
Overlap animations to create fluidity |
| Anticipation |
Brief reverse motion before forward action |
Workflow
Step 1: Define Motion Principles
Establish the core principles that guide all animations in the product. These should align with brand personality and UX goals.
Example motion principles for different brand personalities:
- Professional: 300ms, ease-in-out, subtle, consistent
- Playful: 400-500ms, spring easing, bouncy, expressive
- Minimal: 200ms, ease-out, subtle, no decorative animation
- Bold: 500ms+ with anticipation, dramatic entrances
Document each principle with:
- Name and description
- Application guidelines (when to use, when to avoid)
- Code reference (easing function, duration range)
- Example of correct and incorrect usage
Step 2: Create Timing Scale
Define a consistent timing scale that covers all common animation needs.
| Type |
Duration |
Easing |
Use Cases |
| Instant |
0-50ms |
None |
Micro-feedback, cursor states |
| Fast |
100-150ms |
ease-out |
Button press, hover, toggle, checkbox |
| Normal |
200-300ms |
ease-in-out |
State changes, element appear/disappear, accordion |
| Slow |
300-500ms |
ease-in-out |
Page transitions, modal, drawer, notifications |
| Expressive |
500-1000ms |
ease-out / spring |
Hero animations, onboarding, celebrations |
Easing reference:
| Easing |
CSS Value |
Feel |
| ease-out |
cubic-bezier(0, 0, 0.2, 1) |
Natural deceleration, elements entering |
| ease-in |
cubic-bezier(0.4, 0, 1, 1) |
Acceleration, elements leaving |
| ease-in-out |
cubic-bezier(0.4, 0, 0.2, 1) |
Standard UI transitions |
| spring-light |
cubic-bezier(0.34, 1.56, 0.64, 1) |
Subtle bounce, playful |
| spring-strong |
cubic-bezier(0.175, 0.885, 0.32, 1.275) |
Exaggerated bounce |
| decelerate |
cubic-bezier(0, 0, 0.1, 1) |
Fast start, gradual end |
| accelerate |
cubic-bezier(0.4, 0, 1, 1) |
Slow start, fast end |
Step 3: Design Micro-interaction Patterns
Document reusable micro-interaction patterns. Each pattern should specify:
- Trigger (user action or system event)
- Animation (what animates, duration, easing)
- Feedback (what the user perceives)
- Edge cases (rapid triggering, interrupt, reduced motion)
| Interaction |
Trigger |
Response |
Duration |
Easing |
| Button hover |
Mouse enter |
Background shade, slight scale |
150ms |
ease-out |
| Button press |
Mouse down |
Scale 0.95, reduced shadow |
100ms |
ease-in |
| Toggle switch |
Click |
Knob slides, background color changes |
200ms |
ease-in-out |
| Card hover |
Mouse enter |
Elevation increase (shadow) |
300ms |
ease-out |
| Card expand |
Click |
Scale + reveal content |
300ms |
ease-out |
| Page transition |
Navigation |
Slide (direction based on hierarchy) |
300ms |
ease-in-out |
| Toast appear |
Event trigger |
Slide in from top |
250ms |
ease-out |
| Toast dismiss |
Timeout/click |
Fade out |
200ms |
ease-in |
| Modal open |
Click |
Backdrop fade (200ms) + content scale (300ms) |
300ms |
ease-out |
| Error shake |
Validation failure |
Horizontal shake 3px x 3 cycles |
400ms |
ease-in-out |
| Success check |
Validation pass |
Checkmark draw animation |
500ms |
ease-out |
| Accordion open |
Click |
Height expand |
250ms |
ease-out |
| Notification badge |
Trigger |
Scale bounce |
300ms |
spring |
| Dragging |
Mouse/touch down |
Element follows, slight lift |
50ms |
none |
| Pull to refresh |
Overscroll |
Icon rotation, indicator reveal |
200-500ms |
spring |
Step 4: Design Page and View Transitions
Transition types by navigation context:
| Navigation Type |
Transition Pattern |
Direction |
Duration |
| Push (drill down) |
Slide left |
Forward: left, Back: right |
300ms |
| Modal/Popover |
Scale up + fade |
Center to full |
300ms |
| Tab switch |
Fade |
No directional movement |
200ms |
| Sidebar/drawer |
Slide from edge |
From left or right |
250ms |
| Full-screen content |
Slide up from bottom |
Bottom to top |
350ms |
| Image gallery |
Swipe |
Direction of swipe |
300ms |
| Step wizard |
Slide forward/back |
Direction of progress |
200ms |
| Search expand |
Morph search icon to bar |
Icon to full bar |
300ms |
Shared element transitions:
- When the same element exists in both source and destination states
- The element "morphs" between states (position, size, shape, content)
- Creates continuity: user perceives the element is the same, just transformed
- Common use cases: list item to detail view, thumbnail to full image, icon to expanded form
Step 5: Design Loading and Progress Animations
| Context |
Pattern |
Duration |
Notes |
| Page load |
Skeleton screen (shimmer) |
Until content loads |
Match skeleton shape to content layout |
| Button action |
Button-inline spinner |
Until action completes |
Maintains context; don't disable button |
| Image load |
Blur-up (progressive JPEG) |
200-500ms |
Pleasant preview before full image |
| Refresh |
Pull-to-refresh spinner |
200-500ms |
Spring animation on release |
| Background sync |
Subtle indicator |
Continuous |
Minimize visual noise |
| Long operation |
Progress bar with percentage |
Variable |
Use determinate (known duration) or indeterminate (unknown) |
Skeleton screen guidelines:
- Match approximate layout of actual content
- Use subtle shimmer or pulse animation (400ms)
- Transition to content with cross-fade (300ms)
- Never show skeleton for more than 10 seconds
- Show error state if content fails to load
Step 6: Create Motion Guidelines Document
Organize all motion specifications into a reference document:
- Motion principles (3-5 principles with examples)
- Timing scale (duration + easing table)
- Easing reference (cubic-bezier values with descriptions)
- Micro-interaction library (trigger → animation → feedback per component)
- Transition patterns (by navigation type)
- Loading patterns (skeleton, spinner, progress)
- Accessibility: reduced motion implementation
- Performance guidelines (GPU-accelerated properties, avoiding layout triggers)
Step 7: Implement Reduced Motion
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
transition-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
}
}
For complex animations, provide alternative non-moving states:
- Skeleton: show static placeholder
- Carousel: instant slide change
- Parallax: static layered image
- Confetti: static celebratory graphic
Step 8: Lottie and Rive Animation Workflow
Lottie:
- Design animation in After Effects
- Export as JSON using Bodymovin
- Optimize: reduce keyframes, remove unused assets
- Test on target devices (performance, rendering)
- Integrate using Lottie-web, Lottie-iOS, or Lottie-Android
Rive:
- Design animation in Rive editor
- Set up state machine for interaction-driven animation
- Export as .riv file
- Integrate using Rive runtime
Lottie optimization checklist:
- Remove unused layers before exporting
- Keep animation under 30KB for UI micro-interactions
- Test at 60fps on target devices
- Avoid expressions in After Effects (not supported in Lottie)
- Use solid color fills over gradients (smaller file size)
- Set Bodomovin to "Minimum" image quality
Common Pitfalls
| Pitfall |
Description |
Prevention |
| Gratuitous animation |
Motion without purpose distracts and annoys |
Every animation must serve a functional role (feedback, focus, continuity, expression) |
| Linear easing |
Feels robotic and unnatural |
Always use cubic-bezier, ease-in-out, or spring easings |
| Inconsistent timing |
Similar interactions animate at different speeds |
Define a timing scale and stick to it |
| No reduced motion support |
Excludes users with vestibular disorders |
Add prefers-reduced-motion to every animation |
| Performance-heavy animations |
Animating expensive properties causing jank |
Animate only transform and opacity; avoid animating layout properties |
| Too slow |
>500ms feels sluggish for functional UI |
Functional animations: 100-300ms. Expressive only for special moments |
| Ignoring loading states |
Users see blank screen while content loads |
Always show skeleton or loading indicator within 200ms |
| Conflicting animations |
Multiple animations fight for attention |
Use stagger and hierarchy; one primary animation at a time |
| Missing exit animations |
Elements disappear without transition |
Every entrance should have a corresponding exit |
| Over-engineered Lottie |
Large files causing download delays |
Keep Lottie under 30KB for UI, optimize before export |
Best Practices
| Practice |
Rationale |
| Animate only transform and opacity |
These are GPU-accelerated and won't trigger layout recalculations |
| Use consistent duration for similar interactions |
200ms for all state changes builds predictability |
| Always test on lowest-powered target device |
Animations that work on iPhone 16 may stutter on iPhone 12 |
| Respect prefers-reduced-motion for every animation |
Required for accessibility; benefits users with vestibular disorders |
| Document motion in design system |
Ensures consistency across team and product |
| Use ease-out for entrances, ease-in for exits |
Natural feel: things slow down when arriving, speed up when leaving |
| Avoid animating on page load for first-time visitors |
Wait until user interacts before showing animations |
| Coordinate animation timing across elements |
Stagger multiple animations by 30-80ms for natural feel |
| Provide visual feedback within 100ms |
Users perceive actions as instant if feedback is within 100ms |
| Use spring animations sparingly |
Effective for delight; overuse feels gimmicky |
Templates & Tools
Micro-interaction Specification Template
Component: {component name}
Trigger: {user action or system event}
Animation:
- Target: {element(s) being animated}
- Duration: {N}ms
- Easing: cubic-bezier({x1}, {y1}, {x2}, {y2})
- Delay: {N}ms (if applicable)
- Properties: {properties animated}
State Change:
- From: {starting state}
- To: {ending state}
Reduced Motion Fallback: {description}
Edge Cases:
- Rapid trigger: {how animation handles rapid repeated triggers}
- Interrupt: {what happens if triggered again during animation}
Motion Spec Sheet Template
Motion Piece: {name}
Classification: {feedback / focus / continuity / expression}
Timing:
- Total duration: {N}ms
- Stagger delay: {N}ms per item (if applicable)
Easing:
- Entrance: {type}
- Exit: {type}
- Internal: {type}
Interaction:
- Trigger: {what initiates}
- Loop: {yes/no} — if yes, {loops condition}
- Progress: {linear / user-controlled / automatic}
Platform Notes:
- CSS: {implementation notes}
- Lottie: {file size, platform compatibility}
- Handoff: {link to Lottie JSON or code}
Implementation Reference
CSS transitions (simple states):
.button {
transition: transform 150ms ease-out, background-color 150ms ease-out;
}
.button:active {
transform: scale(0.97);
}
CSS keyframes (complex sequences):
@keyframes slideIn {
from { opacity: 0; transform: translateY(20px); }
to { opacity: 1; transform: translateY(0); }
}
.element {
animation: slideIn 300ms ease-out both;
}
JavaScript Web Animations API:
element.animate([
{ opacity: 0, transform: 'translateY(20px)' },
{ opacity: 1, transform: 'translateY(0)' }
], {
duration: 300,
easing: 'ease-out',
fill: 'both'
});
Spring animation (React Spring):
import { useSpring, animated } from '@react-spring/web';
function AnimatedComponent() {
const props = useSpring({
from: { opacity: 0, transform: 'scale(0.9)' },
to: { opacity: 1, transform: 'scale(1)' },
config: { mass: 1, tension: 200, friction: 16 }
});
return <animated.div style={props} />;
}
Tools
| Tool |
Purpose |
Best For |
Export |
| After Effects + Bodymovin |
Lottie animation creation |
Complex vector animations |
Lottie JSON |
| Rive |
Interactive animations, state machines |
Game-like UI, avatars |
.riv file |
| Principle |
UI animation prototyping |
Timeline-based motion design |
Video, GIF |
| ProtoPie |
Advanced interaction prototyping |
Multi-device, sensor-based |
Prototype link |
| Haiku Animator |
Code-focused motion design |
Developer handoff |
React/Vue components |
| LottieFiles |
Lottie preview, optimization, library |
Lottie workflow |
Optimized Lottie JSON |
| Framer Motion (React) |
React animation library |
Production web animation |
React code |
| Greensock (GSAP) |
JavaScript animation library |
High-performance web animation |
JavaScript code |
Case Studies
Case Study 1: E-commerce Micro-interaction Overhaul Increases Conversion 12%
An e-commerce site had no micro-interactions — buttons simply changed appearance without animation. They implemented purposeful micro-interactions: hover animations on product cards (300ms, ease-out, shadow lift), button press feedback (100ms, scale 0.95), cart add confirmation (badge bounce animation), and smooth page transitions between categories. The result: 12% increase in add-to-cart rate, 8% increase in conversion, and a 5% decrease in bounce rate. Users perceived the site as faster and more responsive even though actual load times hadn't changed.
Method: Systematic micro-interaction audit and redesign
Key insight: Perceived performance (mediated by animation) matters as much as actual performance
Impact: Add-to-cart +12%, conversion +8%, bounce -5%
Case Study 2: Motion Design System for Enterprise SaaS
An enterprise SaaS platform had 40+ teams building features with inconsistent animation — some used 1000ms transitions, others had none. A centralized motion system was created with: timing scale (100/200/300/400/500ms), easing specifications (ease-out, ease-in-out, spring), micro-interaction patterns per component, and page transition guidelines. After adoption, user satisfaction scores for "smoothness" improved by 22%, and development time for animation decreased by 40% because patterns were pre-defined.
Method: Centralized motion design system with documented patterns and code
Key insight: Design systems must include motion, not just visual components
Impact: Satisfaction score +22%, animation dev time -40%
Case Study 3: Lottie Optimization for Mobile Performance
A mobile app used Lottie animations for onboarding illustrations but users experienced jank on mid-range Android devices. Analysis showed Lottie files were averaging 120KB each with 2000+ keyframes. After optimization — reducing to 6 keyframes per animation, removing unused layers, using solid fills instead of gradients, and converting complex shapes to simpler paths — file sizes dropped to 18KB average and frame rate improved from 30fps to 58fps on target devices.
Method: Lottie file optimization audit and reconstruction
Key insight: Animation file size and complexity directly impact runtime performance
Impact: File size 120KB to 18KB, frame rate 30fps to 58fps on mid-range devices
Rules
- Every animation must serve a functional role (feedback, focus, continuity, or expression).
- Never use linear easing — always use ease-in-out, ease-out, or spring.
- Functional animations must be 100-300ms; only expressive animations may exceed 500ms.
- Animate only transform and opacity properties for UI elements.
- Respect prefers-reduced-motion with an alternative static state for every animation.
- Similar interactions must use consistent duration and easing.
- Every entrance animation should have a corresponding exit animation.
- Stagger multiple related animations by 30-80ms for natural-feeling sequences.
- Lottie files for UI micro-interactions must be under 30KB.
- Test all animations on the lowest-powered target device in the product's supported range.
- Avoid animating on initial page load for first-time visitors.
- Skeleton screens must appear within 200ms of navigation start.
- Spring animations should be used sparingly for delight, not routine interactions.
- Conflicting animations (multiple elements animating simultaneously) must be avoided.
- Motion documentation must include timing, easing, and reduced motion fallback for every pattern.
- Color transitions need easing, not just an instant swap.
- Animation specs must be included in developer handoff documentation.
- Motion design review must include a playback speed check at 0.5x for accuracy.
- Shared element transitions require identical element structure (same name, matching layers).
- Metrics must be defined to measure animation effectiveness before implementation.
References
- references/animation-principles.md — Animation Principles Reference
- references/lotti-rive.md — Lottie and Rive Animation Reference
- references/motion-accessibility.md — Motion Accessibility Reference
- references/motion-design-advanced.md — Motion Design Advanced Topics
- references/motion-design-fundamentals.md — Motion Design Fundamentals
- references/ui-animation-patterns.md — UI Animation Patterns Reference
- references/motion-design-principles.md — Motion Design Principles
- references/motion-design-implementation.md — Motion Design Implementation
Implementation Patterns
Observer Pattern for Event Handling
`
interface EventObserver {
onEvent(event: T): Promise;
}
class EventBus {
private observers: Set<EventObserver> = new Set();
subscribe(observer: EventObserver): void {
this.observers.add(observer);
}
unsubscribe(observer: EventObserver): void {
this.observers.delete(observer);
}
async emit(event: T): Promise {
const results = Array.from(this.observers).map(o => o.onEvent(event));
await Promise.allSettled(results);
}
}
`
Configuration-Driven Approach
config: defaults: timeout: 30s retryCount: 3 overrides: production: timeout: 60s retryCount: 5 development: timeout: 300s retryCount: 1
Production Considerations
Deployment Checklist
Monitoring and Alerting
| Metric |
Threshold |
Severity |
Action |
| Error rate |
> 1% over 5min |
Critical |
Page on-call |
| p99 latency |
> 2s over 5min |
Warning |
Investigate |
| Throughput drop |
> 50% over 1min |
Critical |
Check upstream |
| Queue depth |
> 1000 over 1min |
Warning |
Scale consumers |
| Disk usage |
> 85% |
Warning |
Clean or expand |
| Memory usage |
> 90% heap |
Critical |
Restart or scale |
Anti-Patterns
| Anti-Pattern |
Symptom |
Root Cause |
Solution |
| Premature optimization |
Complex code for no measured benefit |
Guessing instead of profiling |
Measure first, optimize based on data |
| Copy-paste reuse |
Duplicate code across codebase |
Lack of abstraction |
Extract shared logic into libraries |
| Gold-plating |
Features with no current requirement |
Over-engineering |
YAGNI — build what's needed now |
| Magical thinking |
Assumptions without validation |
Skipping error handling |
Handle all failure modes explicitly |
Performance Optimization
Caching Strategy
Cache hierarchy: L1 (in-memory local) → L2 (distributed Redis/Memcached) → L3 (CDN/Edge).
Cache invalidation: TTL-based (simple, stale), event-based (complex, fresh), write-through (consistent, higher write latency), write-behind (fast writes, eventual consistency).
Resource Pooling
- Database connections: Pool of reusable connections (HikariCP, pgBouncer)
- HTTP connections: Keep-alive + connection pooling for external calls
- Thread pool: Bounded thread pools for async task execution
Profiling Methodology
- Establish baseline with production traffic profile
- Profile CPU with sampling profiler (pprof, perf, async-profiler)
- Profile memory with heap dumps and allocation tracking
- Profile I/O with strace/perf trace for syscall analysis
- Profile latency with distributed tracing (OpenTelemetry)
- Identify bottleneck, formulate hypothesis, implement fix
- Re-profile to verify improvement, repeat
Security Considerations
Threat Modeling (STRIDE)
- Spoofing: Identity validation, authentication
- Tampering: Integrity checks, digital signatures
- Repudiation: Audit logs, non-repudiation
- Information disclosure: Encryption, access control
- Denial of service: Rate limiting, resource quotas
- Elevation of privilege: Principle of least privilege
Supply Chain Security
- Dependency scanning: Snyk, Dependabot, Trivy
- SBOM generation: CycloneDX or SPDX format
- Signed commits: GPG or SSH commit signing
- Artifact verification: Checksum validation, signature verification
Secrets Management
- Secrets never in code — always in secrets manager (Vault, AWS Secrets Manager)
- Rotation policy: Rotate database credentials every 90 days
- Access audit: Log every secrets access, alert on anomalies
- Encryption at rest and in transit for all secrets
- Principle of least privilege: each service gets only its own secrets
Architecture Decision Trees
Animation Strategy Decision Tree
What is the purpose of the animation? ├── Functional feedback (button click, form submit) → 100-200ms, subtle ├── Navigation transition (page change, route switch) → 200-400ms, directional └── Storytelling/hero (marketing, onboarding) → 400-2000ms, expressive Does the animation convey meaning? ├── Yes → Purpose-driven motion with clear start/end states └── No → Decorative motion, reduced motion preference respected Platform constraints? ├── Mobile → 60fps target, avoid GPU-intensive effects, battery aware └── Desktop → Higher complexity acceptable, multiple simultaneous animations
Tool Selection Decision Tree
Does the animation need interactivity? ├── No → Lottie (JSON) exported from After Effects with bodymovin └── Yes → Does it need state-driven animation? ├── Yes → Rive (state machine) for interactive animated components └── No → CSS transitions/animations for simple micro-interactions Developer handoff format? ├── Lottie → JSON file for Lottie-web, Lottie-iOS, Lottie-Android └── Rive → .riv file with runtimes for web, iOS, Android
1---2name: design-motion-design3description: Use when the user asks about motion design, animation, micro-interactions, Lottie, animation principles, UI animation, transition design, or motion guidelines. Do NOT use for: frontend animation implementation (frontend-animation), or visual design (design-visual-design).4license: MIT5---67# Motion Design89## Purpose10Design motion systems for digital products: animation principles, micro-interactions, transitions, Lottie animations, and motion guidelines that enhance user experience. Motion should serve a functional purpose — guiding attention, providing feedback, communicating hierarchy, and creating continuity between states.1112## Agent Protocol1314### Trigger15Exact user phrases: "motion design", "animation", "micro-interaction", "Lottie", "transition", "UI animation", "motion guidelines", "easing", "keyframe animation", "spring animation", "motion system".1617### Input Context18- What is the product type and platform (web, mobile, native)?19- What is the purpose of the animation (feedback, navigation, delight)?20- What existing motion system or design system is in place?21- What are the performance constraints (device targets, frame rate)?22- What accessibility requirements exist (reduced motion preferences)?23- What is the animation complexity budget?2425### Output Artifact26Motion design system with animation principles, duration/easing specifications, micro-interaction patterns, and implementation guidelines.2728### Response Format29```30## Motion Design Specification31### Animation Principles32{principle}: {application}3334### Timing Scale35{action}: {duration} | {easing} | {use case}3637### Micro-interaction Patterns38{pattern}: {trigger} → {animation} → {feedback}3940### Implementation41{platform}: {technique} | {code example}42```4344No preamble. No postamble. No explanations.4546### Completion Criteria47- [ ] Motion principles defined and documented48- [ ] Timing scale established with duration and easing values49- [ ] Micro-interaction patterns cataloged50- [ ] Page/view transitions specified51- [ ] Loading and progress animations designed52- [ ] Reduced motion fallback defined53- [ ] Lottie animation specifications (if applicable)54- [ ] Implementation guidance for developers5556### Max Response Length57150 lines of spec and patterns.5859## Framework/Methodology6061### Functional Motion Framework62All motion in UI should serve one of four functional roles:6364| Role | Purpose | Example | Duration |65|------|---------|---------|----------|66| Feedback | Confirm user action | Button press, toggle switch | 100-200ms |67| Focus | Direct user attention | Notification, error state | 200-400ms |68| Continuity | Maintain context during change | Page transition, element morph | 200-500ms |69| Expression | Communicate brand personality | Logo animation, loading | 400-1000ms |7071### Motion Design Process7273```74User Need → Which functional role?75 ↓76Role → Which pattern?77 ↓78Pattern → Timing & Easing79 ↓80Spec → Implementation (CSS, Lottie, Rive, etc.)81 ↓82QA → Verify reduced motion, performance, feel83```8485### Animation Complexity Budget8687| Complexity | Description | Performance Impact | When to Use |88|------------|-------------|-------------------|-------------|89| Minimal | 0-5 animated elements, simple CSS transitions | Negligible | Critical tasks, data-heavy screens |90| Moderate | 5-15 animated elements, coordinated timing | Low | Standard UI transitions, navigation |91| Complex | 15+ animated elements, staggered choreography | Medium | Marketing, onboarding, celebrations |92| Heavy | Full-scene animation, particle systems, video | High | Splash screens, immersive experiences |9394### Motion Design Principles9596| Principle | UI Application |97|-----------|----------------|98| Easing | Natural acceleration/deceleration, not linear |99| Duration | Short for functional (100-300ms), longer for expressive (300-500ms) |100| Stagger | Offset animations for visual interest |101| Hierarchy | Important elements animate first |102| Spatial continuity | Elements should animate as if in physical space |103| Transformation | Same element morphs between states; don't replace |104| Masking | Use reveal/conceal to manage attention |105| Depth | Use scale, shadow, and blur for z-space |106| Overlap | Overlap animations to create fluidity |107| Anticipation | Brief reverse motion before forward action |108109## Workflow110111### Step 1: Define Motion Principles112Establish the core principles that guide all animations in the product. These should align with brand personality and UX goals.113114Example motion principles for different brand personalities:115- Professional: 300ms, ease-in-out, subtle, consistent116- Playful: 400-500ms, spring easing, bouncy, expressive117- Minimal: 200ms, ease-out, subtle, no decorative animation118- Bold: 500ms+ with anticipation, dramatic entrances119120Document each principle with:121- Name and description122- Application guidelines (when to use, when to avoid)123- Code reference (easing function, duration range)124- Example of correct and incorrect usage125126### Step 2: Create Timing Scale127Define a consistent timing scale that covers all common animation needs.128129| Type | Duration | Easing | Use Cases |130|------|----------|--------|-----------|131| Instant | 0-50ms | None | Micro-feedback, cursor states |132| Fast | 100-150ms | ease-out | Button press, hover, toggle, checkbox |133| Normal | 200-300ms | ease-in-out | State changes, element appear/disappear, accordion |134| Slow | 300-500ms | ease-in-out | Page transitions, modal, drawer, notifications |135| Expressive | 500-1000ms | ease-out / spring | Hero animations, onboarding, celebrations |136137Easing reference:138139| Easing | CSS Value | Feel |140|--------|-----------|------|141| ease-out | cubic-bezier(0, 0, 0.2, 1) | Natural deceleration, elements entering |142| ease-in | cubic-bezier(0.4, 0, 1, 1) | Acceleration, elements leaving |143| ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) | Standard UI transitions |144| spring-light | cubic-bezier(0.34, 1.56, 0.64, 1) | Subtle bounce, playful |145| spring-strong | cubic-bezier(0.175, 0.885, 0.32, 1.275) | Exaggerated bounce |146| decelerate | cubic-bezier(0, 0, 0.1, 1) | Fast start, gradual end |147| accelerate | cubic-bezier(0.4, 0, 1, 1) | Slow start, fast end |148149### Step 3: Design Micro-interaction Patterns150Document reusable micro-interaction patterns. Each pattern should specify:151- Trigger (user action or system event)152- Animation (what animates, duration, easing)153- Feedback (what the user perceives)154- Edge cases (rapid triggering, interrupt, reduced motion)155156| Interaction | Trigger | Response | Duration | Easing |157|-------------|---------|----------|----------|--------|158| Button hover | Mouse enter | Background shade, slight scale | 150ms | ease-out |159| Button press | Mouse down | Scale 0.95, reduced shadow | 100ms | ease-in |160| Toggle switch | Click | Knob slides, background color changes | 200ms | ease-in-out |161| Card hover | Mouse enter | Elevation increase (shadow) | 300ms | ease-out |162| Card expand | Click | Scale + reveal content | 300ms | ease-out |163| Page transition | Navigation | Slide (direction based on hierarchy) | 300ms | ease-in-out |164| Toast appear | Event trigger | Slide in from top | 250ms | ease-out |165| Toast dismiss | Timeout/click | Fade out | 200ms | ease-in |166| Modal open | Click | Backdrop fade (200ms) + content scale (300ms) | 300ms | ease-out |167| Error shake | Validation failure | Horizontal shake 3px x 3 cycles | 400ms | ease-in-out |168| Success check | Validation pass | Checkmark draw animation | 500ms | ease-out |169| Accordion open | Click | Height expand | 250ms | ease-out |170| Notification badge | Trigger | Scale bounce | 300ms | spring |171| Dragging | Mouse/touch down | Element follows, slight lift | 50ms | none |172| Pull to refresh | Overscroll | Icon rotation, indicator reveal | 200-500ms | spring |173174### Step 4: Design Page and View Transitions175176Transition types by navigation context:177178| Navigation Type | Transition Pattern | Direction | Duration |179|----------------|-------------------|-----------|----------|180| Push (drill down) | Slide left | Forward: left, Back: right | 300ms |181| Modal/Popover | Scale up + fade | Center to full | 300ms |182| Tab switch | Fade | No directional movement | 200ms |183| Sidebar/drawer | Slide from edge | From left or right | 250ms |184| Full-screen content | Slide up from bottom | Bottom to top | 350ms |185| Image gallery | Swipe | Direction of swipe | 300ms |186| Step wizard | Slide forward/back | Direction of progress | 200ms |187| Search expand | Morph search icon to bar | Icon to full bar | 300ms |188189Shared element transitions:190- When the same element exists in both source and destination states191- The element "morphs" between states (position, size, shape, content)192- Creates continuity: user perceives the element is the same, just transformed193- Common use cases: list item to detail view, thumbnail to full image, icon to expanded form194195### Step 5: Design Loading and Progress Animations196197| Context | Pattern | Duration | Notes |198|---------|---------|----------|-------|199| Page load | Skeleton screen (shimmer) | Until content loads | Match skeleton shape to content layout |200| Button action | Button-inline spinner | Until action completes | Maintains context; don't disable button |201| Image load | Blur-up (progressive JPEG) | 200-500ms | Pleasant preview before full image |202| Refresh | Pull-to-refresh spinner | 200-500ms | Spring animation on release |203| Background sync | Subtle indicator | Continuous | Minimize visual noise |204| Long operation | Progress bar with percentage | Variable | Use determinate (known duration) or indeterminate (unknown) |205206Skeleton screen guidelines:207- Match approximate layout of actual content208- Use subtle shimmer or pulse animation (400ms)209- Transition to content with cross-fade (300ms)210- Never show skeleton for more than 10 seconds211- Show error state if content fails to load212213### Step 6: Create Motion Guidelines Document214Organize all motion specifications into a reference document:2152161. Motion principles (3-5 principles with examples)2172. Timing scale (duration + easing table)2183. Easing reference (cubic-bezier values with descriptions)2194. Micro-interaction library (trigger → animation → feedback per component)2205. Transition patterns (by navigation type)2216. Loading patterns (skeleton, spinner, progress)2227. Accessibility: reduced motion implementation2238. Performance guidelines (GPU-accelerated properties, avoiding layout triggers)224225### Step 7: Implement Reduced Motion226```css227@media (prefers-reduced-motion: reduce) {228 *, *::before, *::after {229 animation-duration: 0.01ms !important;230 transition-duration: 0.01ms !important;231 animation-iteration-count: 1 !important;232 }233}234```235For complex animations, provide alternative non-moving states:236- Skeleton: show static placeholder237- Carousel: instant slide change238- Parallax: static layered image239- Confetti: static celebratory graphic240241### Step 8: Lottie and Rive Animation Workflow242243Lottie:2441. Design animation in After Effects2452. Export as JSON using Bodymovin2463. Optimize: reduce keyframes, remove unused assets2474. Test on target devices (performance, rendering)2485. Integrate using Lottie-web, Lottie-iOS, or Lottie-Android249250Rive:2511. Design animation in Rive editor2522. Set up state machine for interaction-driven animation2533. Export as .riv file2544. Integrate using Rive runtime255256Lottie optimization checklist:257- Remove unused layers before exporting258- Keep animation under 30KB for UI micro-interactions259- Test at 60fps on target devices260- Avoid expressions in After Effects (not supported in Lottie)261- Use solid color fills over gradients (smaller file size)262- Set Bodomovin to "Minimum" image quality263264## Common Pitfalls265266| Pitfall | Description | Prevention |267|---------|-------------|------------|268| Gratuitous animation | Motion without purpose distracts and annoys | Every animation must serve a functional role (feedback, focus, continuity, expression) |269| Linear easing | Feels robotic and unnatural | Always use cubic-bezier, ease-in-out, or spring easings |270| Inconsistent timing | Similar interactions animate at different speeds | Define a timing scale and stick to it |271| No reduced motion support | Excludes users with vestibular disorders | Add prefers-reduced-motion to every animation |272| Performance-heavy animations | Animating expensive properties causing jank | Animate only transform and opacity; avoid animating layout properties |273| Too slow | >500ms feels sluggish for functional UI | Functional animations: 100-300ms. Expressive only for special moments |274| Ignoring loading states | Users see blank screen while content loads | Always show skeleton or loading indicator within 200ms |275| Conflicting animations | Multiple animations fight for attention | Use stagger and hierarchy; one primary animation at a time |276| Missing exit animations | Elements disappear without transition | Every entrance should have a corresponding exit |277| Over-engineered Lottie | Large files causing download delays | Keep Lottie under 30KB for UI, optimize before export |278279## Best Practices280281| Practice | Rationale |282|----------|-----------|283| Animate only transform and opacity | These are GPU-accelerated and won't trigger layout recalculations |284| Use consistent duration for similar interactions | 200ms for all state changes builds predictability |285| Always test on lowest-powered target device | Animations that work on iPhone 16 may stutter on iPhone 12 |286| Respect prefers-reduced-motion for every animation | Required for accessibility; benefits users with vestibular disorders |287| Document motion in design system | Ensures consistency across team and product |288| Use ease-out for entrances, ease-in for exits | Natural feel: things slow down when arriving, speed up when leaving |289| Avoid animating on page load for first-time visitors | Wait until user interacts before showing animations |290| Coordinate animation timing across elements | Stagger multiple animations by 30-80ms for natural feel |291| Provide visual feedback within 100ms | Users perceive actions as instant if feedback is within 100ms |292| Use spring animations sparingly | Effective for delight; overuse feels gimmicky |293294## Templates & Tools295296### Micro-interaction Specification Template297```298Component: {component name}299Trigger: {user action or system event}300301Animation:302- Target: {element(s) being animated}303- Duration: {N}ms304- Easing: cubic-bezier({x1}, {y1}, {x2}, {y2})305- Delay: {N}ms (if applicable)306- Properties: {properties animated}307308State Change:309- From: {starting state}310- To: {ending state}311312Reduced Motion Fallback: {description}313314Edge Cases:315- Rapid trigger: {how animation handles rapid repeated triggers}316- Interrupt: {what happens if triggered again during animation}317```318319### Motion Spec Sheet Template320```321Motion Piece: {name}322Classification: {feedback / focus / continuity / expression}323324Timing:325- Total duration: {N}ms326- Stagger delay: {N}ms per item (if applicable)327328Easing:329- Entrance: {type}330- Exit: {type}331- Internal: {type}332333Interaction:334- Trigger: {what initiates}335- Loop: {yes/no} — if yes, {loops condition}336- Progress: {linear / user-controlled / automatic}337338Platform Notes:339- CSS: {implementation notes}340- Lottie: {file size, platform compatibility}341- Handoff: {link to Lottie JSON or code}342```343344### Implementation Reference345346**CSS transitions (simple states):**347```css348.button {349 transition: transform 150ms ease-out, background-color 150ms ease-out;350}351.button:active {352 transform: scale(0.97);353}354```355356**CSS keyframes (complex sequences):**357```css358@keyframes slideIn {359 from { opacity: 0; transform: translateY(20px); }360 to { opacity: 1; transform: translateY(0); }361}362.element {363 animation: slideIn 300ms ease-out both;364}365```366367**JavaScript Web Animations API:**368```javascript369element.animate([370 { opacity: 0, transform: 'translateY(20px)' },371 { opacity: 1, transform: 'translateY(0)' }372], {373 duration: 300,374 easing: 'ease-out',375 fill: 'both'376});377```378379**Spring animation (React Spring):**380```javascript381import { useSpring, animated } from '@react-spring/web';382383function AnimatedComponent() {384 const props = useSpring({385 from: { opacity: 0, transform: 'scale(0.9)' },386 to: { opacity: 1, transform: 'scale(1)' },387 config: { mass: 1, tension: 200, friction: 16 }388 });389 return <animated.div style={props} />;390}391```392393### Tools394395| Tool | Purpose | Best For | Export |396|------|---------|----------|--------|397| After Effects + Bodymovin | Lottie animation creation | Complex vector animations | Lottie JSON |398| Rive | Interactive animations, state machines | Game-like UI, avatars | .riv file |399| Principle | UI animation prototyping | Timeline-based motion design | Video, GIF |400| ProtoPie | Advanced interaction prototyping | Multi-device, sensor-based | Prototype link |401| Haiku Animator | Code-focused motion design | Developer handoff | React/Vue components |402| LottieFiles | Lottie preview, optimization, library | Lottie workflow | Optimized Lottie JSON |403| Framer Motion (React) | React animation library | Production web animation | React code |404| Greensock (GSAP) | JavaScript animation library | High-performance web animation | JavaScript code |405406## Case Studies407408### Case Study 1: E-commerce Micro-interaction Overhaul Increases Conversion 12%409An e-commerce site had no micro-interactions — buttons simply changed appearance without animation. They implemented purposeful micro-interactions: hover animations on product cards (300ms, ease-out, shadow lift), button press feedback (100ms, scale 0.95), cart add confirmation (badge bounce animation), and smooth page transitions between categories. The result: 12% increase in add-to-cart rate, 8% increase in conversion, and a 5% decrease in bounce rate. Users perceived the site as faster and more responsive even though actual load times hadn't changed.410411Method: Systematic micro-interaction audit and redesign412Key insight: Perceived performance (mediated by animation) matters as much as actual performance413Impact: Add-to-cart +12%, conversion +8%, bounce -5%414415### Case Study 2: Motion Design System for Enterprise SaaS416An enterprise SaaS platform had 40+ teams building features with inconsistent animation — some used 1000ms transitions, others had none. A centralized motion system was created with: timing scale (100/200/300/400/500ms), easing specifications (ease-out, ease-in-out, spring), micro-interaction patterns per component, and page transition guidelines. After adoption, user satisfaction scores for "smoothness" improved by 22%, and development time for animation decreased by 40% because patterns were pre-defined.417418Method: Centralized motion design system with documented patterns and code419Key insight: Design systems must include motion, not just visual components420Impact: Satisfaction score +22%, animation dev time -40%421422### Case Study 3: Lottie Optimization for Mobile Performance423A mobile app used Lottie animations for onboarding illustrations but users experienced jank on mid-range Android devices. Analysis showed Lottie files were averaging 120KB each with 2000+ keyframes. After optimization — reducing to 6 keyframes per animation, removing unused layers, using solid fills instead of gradients, and converting complex shapes to simpler paths — file sizes dropped to 18KB average and frame rate improved from 30fps to 58fps on target devices.424425Method: Lottie file optimization audit and reconstruction426Key insight: Animation file size and complexity directly impact runtime performance427Impact: File size 120KB to 18KB, frame rate 30fps to 58fps on mid-range devices428429## Rules430- Every animation must serve a functional role (feedback, focus, continuity, or expression).431- Never use linear easing — always use ease-in-out, ease-out, or spring.432- Functional animations must be 100-300ms; only expressive animations may exceed 500ms.433- Animate only transform and opacity properties for UI elements.434- Respect prefers-reduced-motion with an alternative static state for every animation.435- Similar interactions must use consistent duration and easing.436- Every entrance animation should have a corresponding exit animation.437- Stagger multiple related animations by 30-80ms for natural-feeling sequences.438- Lottie files for UI micro-interactions must be under 30KB.439- Test all animations on the lowest-powered target device in the product's supported range.440- Avoid animating on initial page load for first-time visitors.441- Skeleton screens must appear within 200ms of navigation start.442- Spring animations should be used sparingly for delight, not routine interactions.443- Conflicting animations (multiple elements animating simultaneously) must be avoided.444- Motion documentation must include timing, easing, and reduced motion fallback for every pattern.445- Color transitions need easing, not just an instant swap.446- Animation specs must be included in developer handoff documentation.447- Motion design review must include a playback speed check at 0.5x for accuracy.448- Shared element transitions require identical element structure (same name, matching layers).449- Metrics must be defined to measure animation effectiveness before implementation.450451## References452 - references/animation-principles.md — Animation Principles Reference453 - references/lotti-rive.md — Lottie and Rive Animation Reference454 - references/motion-accessibility.md — Motion Accessibility Reference455 - references/motion-design-advanced.md — Motion Design Advanced Topics456 - references/motion-design-fundamentals.md — Motion Design Fundamentals457 - references/ui-animation-patterns.md — UI Animation Patterns Reference458 - references/motion-design-principles.md — Motion Design Principles459 - references/motion-design-implementation.md — Motion Design Implementation460## Implementation Patterns461462### Observer Pattern for Event Handling463`464interface EventObserver<T> {465 onEvent(event: T): Promise<void>;466}467468class EventBus<T> {469 private observers: Set<EventObserver<T>> = new Set();470 subscribe(observer: EventObserver<T>): void {471 this.observers.add(observer);472 }473 unsubscribe(observer: EventObserver<T>): void {474 this.observers.delete(observer);475 }476 async emit(event: T): Promise<void> {477 const results = Array.from(this.observers).map(o => o.onEvent(event));478 await Promise.allSettled(results);479 }480}481`482483### Configuration-Driven Approach484`485config:486 defaults:487 timeout: 30s488 retryCount: 3489 overrides:490 production:491 timeout: 60s492 retryCount: 5493 development:494 timeout: 300s495 retryCount: 1496`497498## Production Considerations499500### Deployment Checklist501- [ ] Configuration validated against schema before startup502- [ ] Health check endpoints registered and monitored503- [ ] Graceful shutdown with draining period (30s timeout)504- [ ] Resource limits configured (CPU, memory, file descriptors)505- [ ] Log level set appropriate for environment506- [ ] Metrics endpoint secured and exposed507- [ ] Rate limiting configured per-tier508- [ ] TLS certificates valid and auto-renewing509- [ ] Database migrations run as separate deployment step510- [ ] Feature flags ready for gradual rollout511512### Monitoring and Alerting513| Metric | Threshold | Severity | Action |514|--------|-----------|----------|--------|515| Error rate | > 1% over 5min | Critical | Page on-call |516| p99 latency | > 2s over 5min | Warning | Investigate |517| Throughput drop | > 50% over 1min | Critical | Check upstream |518| Queue depth | > 1000 over 1min | Warning | Scale consumers |519| Disk usage | > 85% | Warning | Clean or expand |520| Memory usage | > 90% heap | Critical | Restart or scale |521522## Anti-Patterns523524| Anti-Pattern | Symptom | Root Cause | Solution |525|-------------|---------|------------|----------|526| Premature optimization | Complex code for no measured benefit | Guessing instead of profiling | Measure first, optimize based on data |527| Copy-paste reuse | Duplicate code across codebase | Lack of abstraction | Extract shared logic into libraries |528| Gold-plating | Features with no current requirement | Over-engineering | YAGNI — build what's needed now |529| Magical thinking | Assumptions without validation | Skipping error handling | Handle all failure modes explicitly |530531## Performance Optimization532533### Caching Strategy534Cache hierarchy: L1 (in-memory local) → L2 (distributed Redis/Memcached) → L3 (CDN/Edge).535Cache invalidation: TTL-based (simple, stale), event-based (complex, fresh), write-through (consistent, higher write latency), write-behind (fast writes, eventual consistency).536537### Resource Pooling538- Database connections: Pool of reusable connections (HikariCP, pgBouncer)539- HTTP connections: Keep-alive + connection pooling for external calls540- Thread pool: Bounded thread pools for async task execution541542### Profiling Methodology5431. Establish baseline with production traffic profile5442. Profile CPU with sampling profiler (pprof, perf, async-profiler)5453. Profile memory with heap dumps and allocation tracking5464. Profile I/O with strace/perf trace for syscall analysis5475. Profile latency with distributed tracing (OpenTelemetry)5486. Identify bottleneck, formulate hypothesis, implement fix5497. Re-profile to verify improvement, repeat550551## Security Considerations552553### Threat Modeling (STRIDE)554- Spoofing: Identity validation, authentication555- Tampering: Integrity checks, digital signatures556- Repudiation: Audit logs, non-repudiation557- Information disclosure: Encryption, access control558- Denial of service: Rate limiting, resource quotas559- Elevation of privilege: Principle of least privilege560561### Supply Chain Security562- Dependency scanning: Snyk, Dependabot, Trivy563- SBOM generation: CycloneDX or SPDX format564- Signed commits: GPG or SSH commit signing565- Artifact verification: Checksum validation, signature verification566567### Secrets Management568- Secrets never in code — always in secrets manager (Vault, AWS Secrets Manager)569- Rotation policy: Rotate database credentials every 90 days570- Access audit: Log every secrets access, alert on anomalies571- Encryption at rest and in transit for all secrets572- Principle of least privilege: each service gets only its own secrets573574## Architecture Decision Trees575576### Animation Strategy Decision Tree577`578What is the purpose of the animation?579 ├── Functional feedback (button click, form submit) → 100-200ms, subtle580 ├── Navigation transition (page change, route switch) → 200-400ms, directional581 └── Storytelling/hero (marketing, onboarding) → 400-2000ms, expressive582 Does the animation convey meaning?583 ├── Yes → Purpose-driven motion with clear start/end states584 └── No → Decorative motion, reduced motion preference respected585 Platform constraints?586 ├── Mobile → 60fps target, avoid GPU-intensive effects, battery aware587 └── Desktop → Higher complexity acceptable, multiple simultaneous animations588`589590### Tool Selection Decision Tree591`592Does the animation need interactivity?593 ├── No → Lottie (JSON) exported from After Effects with bodymovin594 └── Yes → Does it need state-driven animation?595 ├── Yes → Rive (state machine) for interactive animated components596 └── No → CSS transitions/animations for simple micro-interactions597 Developer handoff format?598 ├── Lottie → JSON file for Lottie-web, Lottie-iOS, Lottie-Android599 └── Rive → .riv file with runtimes for web, iOS, Android600`