Skip to content

SKILL.md

Latest commit

 

History

History
101 lines (67 loc) · 3.71 KB

SKILL.md

File metadata and controls

101 lines (67 loc) · 3.71 KB
Raw
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:

  1. Primary actor - the element representing the state change
  2. Supporting actors - nearby elements that reinforce context
  3. 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:

  1. Storyboard - who moves, in what order, and why
  2. Timeline Spec - durations, offsets, easing tokens, and distances
  3. Implementation Plan - CSS/JS/View Transition structure
  4. A11y + Fallback - reduced-motion and unsupported-feature strategy
  5. Validation Plan - performance and UX checks

QA Checklist

Use this before shipping: