| name | motion-choreography-patterns |
| description | Use when orchestrating multi-element UI motion, stagger systems, list reorder/insert/remove flows, modal and overlay stacks, gesture-driven transitions, and route-level choreography that preserves hierarchy and attention. |
Motion Choreography Patterns
Overview
This skill focuses on choreography: how multiple moving parts coordinate in time and space to communicate interaction intent.
Use it alongside foundational motion guidance to create motion systems that are legible, consistent, and production-ready across complex UI flows.
When to Use
- Designing sequences with more than one animated element
- Building staggered reveals, list transitions, and layout mode changes
- Implementing modal, drawer, popover, and overlay interaction stacks
- Handling add/remove/reorder scenarios in dense interfaces
- Mapping user input (tap, drag, scroll) to motion responses
- Auditing whether motion hierarchy matches product hierarchy
Choreography Model
Treat each sequence as three actor layers:
- Primary actor - the element representing the state change
- Supporting actors - nearby elements that reinforce context
- Environment actors - backdrop, scrim, container, page-level continuity
Animate primary first, then supporting, then environment unless the interaction model requires the reverse.
Timing Architecture
Use predictable beat structure:
- Lead beat (
0-80ms) - immediate acknowledgment
- Primary beat (
120-240ms) - main state change
- Follow beat (
20-60ms offset) - supporting context update
- Settle beat (
80-180ms) - final stabilization
Favor asymmetry: exits slightly faster than enters.
Core Choreography Principles
- One dominant axis per beat (avoid conflicting direction signals)
- Keep simultaneous high-amplitude motions limited
- Use stagger only when it improves scan order and hierarchy
- Keep rhythm consistent across similar components
- Preserve spatial anchors during reflow/reorder transitions
Pattern Library
For concrete recipes and timelines, see:
For reusable stagger utilities, see:
Input-to-Motion Mapping
- Tap/click: immediate visual response in under
80ms
- Press/hold: include press state before commitment transition
- Drag: motion follows pointer directly; settle animation occurs only on drop/commit
- Keyboard navigation: preserve focus continuity and avoid disorienting travel
Reduced Motion Choreography
When reduced motion is requested:
- Remove spatial travel when possible
- Keep sequencing logic with opacity/state changes
- Preserve hierarchy with contrast, layering, and timing rather than movement distance
- Ensure state change remains obvious and immediate
Anti-Patterns
- Cascades that delay interaction completion
- Independent components using unrelated easing and duration tokens
- Large travel distances for frequent interactions
- Simultaneous enter and exit motions that compete for focus
- Decorative infinite animations in core task surfaces
Output Contract
When using this skill, return these five sections:
- Storyboard - who moves, in what order, and why
- Timeline Spec - durations, offsets, easing tokens, and distances
- Implementation Plan - CSS/JS/View Transition structure
- A11y + Fallback - reduced-motion and unsupported-feature strategy
- Validation Plan - performance and UX checks
QA Checklist
Use this before shipping:
