@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/cursor/design-material-design-3/skill.yaml

@@ -0,0 +1,36 @@
+name: design-material-design-3
+version: '1.0.0'
+description: Google Material You design language covering dynamic color, tonal palettes, elevation with tonal surface color, shape theming, and motion choreography
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-token-architecture
+  - design-elevation-shadow
+  - design-color-harmony
+stack_signals: []
+keywords:
+  - material-design
+  - material-you
+  - M3
+  - dynamic-color
+  - tonal-palette
+  - shape-theme
+  - elevation-tint
+  - Android
+  - Google
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-micro-interactions/SKILL.md

@@ -0,0 +1,156 @@
+# Micro-Interactions
+
+> Small moments that delight — trigger, rules, feedback, loops/modes (Dan Saffer's framework), when micro-interactions aid usability vs decoration
+
+## When to Use
+
+- Adding interactive feedback to buttons, toggles, switches, or form controls
+- Designing pull-to-refresh, swipe-to-dismiss, long-press, or gesture-driven interactions
+- Evaluating whether an animation serves usability or is purely decorative
+- Building loading transitions, success confirmations, or error acknowledgments
+- Creating onboarding moments that teach through interaction rather than text
+- Reviewing motion design for performance impact and accessibility compliance
+- Designing system status indicators (typing indicators, sync status, connection state)
+- Any moment where the interface responds to a single user action with a contained, purposeful animation
+
+## Instructions
+
+1. **Decompose every micro-interaction into Dan Saffer's four-part structure.** Every micro-interaction has: (a) a Trigger — what initiates it (user action or system event), (b) Rules — what happens and in what order, (c) Feedback — what the user perceives, and (d) Loops and Modes — whether the interaction repeats, changes over time, or has alternate behaviors. If you cannot articulate all four parts, the interaction is underdesigned. Saffer's framework from _Microinteractions_ (2013) remains the definitive structural model.
+
+2. **Start with the trigger type.** Triggers are either user-initiated (tap, click, hover, scroll, gesture, voice) or system-initiated (notification, timer, state change, incoming data). User-initiated triggers must have zero perceptible delay — the feedback must begin within one animation frame (16ms at 60fps). System-initiated triggers must be non-intrusive: they should not interrupt the user's current task. Slack's typing indicator is system-initiated ("Someone is typing...") and appears in a dedicated, predictable location below the message input — it never interrupts reading flow.
+
+3. **Define rules that are simple and deterministic.** Rules govern the behavior between trigger and feedback. Good rules have no branching visible to the user. The iOS toggle switch has one rule: "When tapped, slide the knob to the opposite position and change the background color." The user never needs to think about conditional logic. If your micro-interaction requires the user to understand conditional rules ("If X, then Y, but if Z, then W"), it is too complex — split it into separate interactions.
+
+4. **Design feedback across three sensory channels.** The strongest micro-interactions use multiple channels simultaneously: visual (color change, position shift, scale transform), auditory (click sound, chime), and haptic (vibration, force feedback). Apple's iOS toggle combines all three: the knob slides (visual), a subtle click plays (auditory on supported devices), and a light haptic tap fires (haptic via Taptic Engine). For web interfaces where haptic and audio are limited, visual feedback must carry the full communicative load — use at least two visual properties (e.g., color + position, scale + opacity).
+
+5. **Calibrate duration to interaction weight.** Lightweight interactions (toggle, checkbox, hover) need 100-200ms durations. Medium interactions (panel expand, drawer open, card flip) need 200-350ms. Heavy interactions (page transition, modal entrance, complex state change) need 300-500ms. Anything over 500ms feels sluggish. Anything under 100ms feels instantaneous and may not register as a transition at all. Material Design specifies exact values: small components use 100ms, medium surfaces use 250ms, full-screen transitions use 300-375ms.
+
+6. **Use easing curves that match physical intuition.** Linear easing feels robotic. Standard easing (`cubic-bezier(0.4, 0.0, 0.2, 1)` in Material Design) mimics natural deceleration — objects accelerate quickly then ease to a stop, matching how physical objects behave under friction. Enter animations should use deceleration easing (fast start, slow end) because the element is "arriving." Exit animations should use acceleration easing (slow start, fast end) because the element is "departing." Material Design's easing tokens: `emphasized` for focal elements, `standard` for most transitions, `emphasized-decelerate` for entries, `emphasized-accelerate` for exits.
+
+7. **Apply the usability test: remove the micro-interaction and check if the UI still works.** If removing the animation makes the interface harder to use (the user cannot tell what changed, where an element went, or what state they are in), the micro-interaction is functional. If removing it changes nothing about usability (the user can still complete their task identically), the micro-interaction is decorative. Functional micro-interactions are essential. Decorative micro-interactions are budget-dependent — they add delight but are the first thing to cut when performance is constrained.
+
+8. **Design for loops and long-term exposure.** A micro-interaction that delights on first encounter may irritate on the hundredth. Saffer's "loops" concept addresses this: consider whether the interaction should attenuate over time (reduce in intensity after repeated exposure), remain constant (critical status indicators must never fade), or escalate (an unacknowledged notification that becomes more prominent). Slack's unread badge is constant — it must be reliable. A celebratory confetti animation on task completion should attenuate — show it the first five times, then replace it with a subtle checkmark.
+
+## Details
+
+### The Four-Part Framework in Depth
+
+**Triggers.** The best triggers are discoverable through existing affordances. A swipeable card should look swipeable (slight shadow suggesting depth, visible edge of the next card). Instagram's pull-to-refresh uses a trigger that aligns with the existing scroll gesture — the user does not need to learn a new action, they just scroll past the top. Hidden triggers (long press, force touch, multi-finger gestures) are power-user features and must never be the only way to access a function. Every hidden trigger must have a visible alternative.
+
+**Rules.** Rules should be expressible in a single sentence: "When the user clicks the heart icon, it scales to 120%, changes to red fill, and a particle burst emanates from center." Twitter/X's like animation follows this exactly. The particle burst is a single-sentence addition to the basic toggle rule. Rules become problematic when they depend on external state the user cannot see: "If the server has already processed this, do X; otherwise do Y" creates unpredictable behavior. Keep rules local to what the user can observe.
+
+**Feedback.** Feedback must be proportional to the action's significance. A trivial action (hovering over a menu item) deserves trivial feedback (subtle background color shift, 100ms). A significant action (submitting a form, deleting data) deserves significant feedback (confirmation animation, state change, 300-500ms). GitHub's star animation is proportional: a small bounce and fill change for a low-commitment action. Stripe's successful payment confirmation is proportionally larger: a checkmark draw animation, a green background pulse, and a summary slide-in.
+
+**Loops and Modes.** Loops govern what happens when the trigger fires repeatedly or when conditions change. A "like" button has a loop: tap once to like (fill), tap again to unlike (unfill). The loop must feel equally responsive in both directions — if the "like" animation is 300ms but the "unlike" is instant, the asymmetry feels broken. Modes are alternate behaviors under different conditions: a download button that shows progress while downloading, then changes to an "Open" button when complete. The mode change must be visually clear — GitHub's "Clone" button changes to "Open in Desktop" contextually, with a complete icon and label swap.
+
+### Micro-Interaction Patterns Catalog
+
+**Toggle/Switch.** Trigger: tap/click. Rules: slide knob, swap color, update state. Feedback: knob position + color change + haptic. Duration: 150-200ms. Easing: standard. Apple's iOS toggle is the benchmark: 200ms duration, the knob has a subtle scale bounce at the endpoints (102% then back to 100%), the track color transitions through an intermediate state. Material Design's switch adds a ripple effect at the touch point.
+
+**Button Press.** Trigger: pointerdown. Rules: scale down slightly (97-98%), increase shadow depth on release. Feedback: scale + shadow + color. Duration: 100ms press, 200ms release. The press-and-release rhythm must feel physical — like pushing a real button. Material Design elevates the button by 2dp on press (shadow increases from `elevation-1` to `elevation-3`). Stripe scales buttons to 98% with a 100ms `ease-out`, then returns to 100% with a 150ms `ease-in-out` on release.
+
+**Pull-to-Refresh.** Trigger: overscroll gesture. Rules: resistance curve increases with pull distance, icon rotates proportionally, threshold triggers refresh. Feedback: rubber-band resistance + rotating icon + haptic at threshold. The critical detail is the resistance curve: initial pull should move 1:1 with the finger, then progressively resist (logarithmic curve) past the trigger threshold. Apple's implementation adds a haptic tap at the exact moment the threshold is crossed — the user feels confirmation before releasing.
+
+**Swipe-to-Dismiss/Delete.** Trigger: horizontal swipe. Rules: element follows finger with friction, reveal action underneath, threshold triggers action or snap-back. Feedback: position tracking + background reveal + color change at threshold. The snap-back animation when the user does not reach the threshold must be fast (150ms) and springy — it communicates "you didn't go far enough" through physics. Apple Mail's swipe-to-delete reveals a red "Trash" action; the threshold is approximately 60% of the cell width.
+
+**Typing Indicator.** Trigger: system event (remote user starts typing). Rules: show indicator after 500ms of continuous typing, hide 3 seconds after last keystroke. Feedback: animated dots (the classic "..." bounce) or text ("Alex is typing..."). The 500ms delay before showing prevents flicker from brief typing bursts. The 3-second hide timeout prevents the indicator from staying visible after the remote user paused. Slack and iMessage both use this exact timing.
+
+**Form Validation Feedback.** Trigger: field blur (user leaves field). Rules: validate field value against constraints, determine valid/invalid. Feedback for valid: green checkmark fades in at field's right edge (150ms, ease-in), field border optionally shifts to green. Feedback for invalid: red border color transition (200ms), error icon appears, error message slides down below the field (200ms, ease-out). The error message animation must not cause layout shift in the form below — reserve space or use absolute positioning. Stripe's card number field validates on blur with a smooth border color transition and a specific error message that slides into a reserved space below the field.
+
+**Drag-and-Drop Reorder.** Trigger: pointerdown + hold (150ms delay to distinguish from click). Rules: element lifts with elevation increase (shadow deepens), follows pointer position with 1:1 tracking, other items reflow to indicate drop position. Feedback: elevation change (shadow from 2dp to 8dp), scale increase to 103%, subtle rotation (1-2 degrees) to break grid alignment and feel "picked up," drop target highlight (background color pulse on valid targets). The 150ms hold delay prevents accidental drags from fast clicks. Linear's issue list uses this pattern — dragging an issue between status columns feels physical because of the lift, scale, and shadow cues.
+
+### Performance Budgets for Micro-Interactions
+
+Every micro-interaction has a performance cost. The budget constraints:
+
+- **Frame budget:** 16.67ms per frame at 60fps. All animation calculations (transform, opacity, color) must complete within this window. Avoid animating `width`, `height`, `top`, `left`, or `margin` — these trigger layout recalculation. Instead animate `transform` (translateX/Y, scale, rotate) and `opacity`, which are compositor-only properties and run on the GPU.
+- **Paint budget:** Avoid `box-shadow` animations and `border-radius` animations on large elements — these trigger paint. Use `filter: drop-shadow()` with hardware acceleration or pre-render shadow states as separate layers.
+- **JavaScript budget:** `requestAnimationFrame` for imperative animations. Never use `setInterval` or `setTimeout` for frame-by-frame animation — they do not synchronize with the display refresh and cause jank. CSS transitions and Web Animations API are preferred over JavaScript-driven animations for simple transforms.
+- **Total animation weight:** A page should not run more than 3 simultaneous animations. Beyond 3, the compositor thread contends for GPU resources and frame drops become visible. If you need staggered animations (e.g., a list appearing item-by-item), use CSS `animation-delay` with a single animation definition rather than spawning independent animation instances.
+
+### Anti-Patterns
+
+1. **Gratuitous Bounce.** Adding spring/bounce easing to every element — buttons bounce, cards bounce, modals bounce. Bouncy animations signal playfulness, which is appropriate for a children's app but undermines credibility in finance, healthcare, or enterprise tools. Reserve spring physics for interactions where the physical metaphor adds meaning (pull-to-refresh, swipe snap-back). Use standard easing for everything else.
+
+2. **Animation Hostage.** Forcing users to wait for an animation to complete before they can interact. A modal that takes 500ms to open and disables all input during the animation holds the user hostage for half a second per interaction. Solution: allow input during entrance animations. The user should be able to click a button inside a modal before the modal's entrance animation completes. Linear's command palette is interactive before its slide-in animation finishes — the user can start typing immediately.
+
+3. **Inconsistent Duration Scale.** Using random durations (137ms here, 420ms there, 800ms elsewhere) with no systematic relationship. This creates a UI that feels chaotic — every element has its own temporal personality. Fix: define a duration scale (e.g., 100ms, 200ms, 300ms, 500ms) and map every animation to the nearest scale value. Material Design uses exactly this: `duration.short1` (50ms) through `duration.long4` (700ms) in defined steps.
+
+4. **Hover-Only Feedback.** Relying solely on hover states for interactive feedback, which excludes touch devices entirely (no hover on mobile) and keyboard users. Every hover-based micro-interaction must have a focus equivalent and a touch equivalent. If a button changes color on hover, it must also change color on `:focus-visible` and on `:active` for touch.
+
+5. **Decorative Overload.** Adding micro-interactions to every possible element — icon rotations, label fades, border pulses, background gradients — until the interface feels like a fireworks display. Each micro-interaction competes for the user's attention. More than 2-3 simultaneous animations on screen create cognitive overload. Fix: apply the usability test from Instruction 7 to every animation. If it is decorative, cut it unless you have explicit performance and attention budget for it.
+
+### Real-World Examples
+
+**Apple iOS Pull-to-Refresh.** Trigger: overscroll past top of scroll view. Rules: spinner appears, scales from 0 to 1 proportional to pull distance, begins rotating at threshold. Feedback: visual (spinner rotation + content displacement) + haptic (single tap at threshold). Loop: repeated pulls always behave identically — this is a constant loop, no attenuation. The interaction is so precisely tuned that users can feel the threshold without looking, relying on the haptic alone.
+
+**Material Design FAB Transformation.** The Floating Action Button transforms from a circular icon into an expanded surface (bottom sheet, full-screen dialog, or speed dial). Trigger: tap. Rules: circle expands along a deceleration curve, icon morphs into content, background floods to fill the target shape. Feedback: continuous shape transformation over 250-300ms using `emphasized-decelerate` easing. This micro-interaction communicates that the new surface originated from the FAB — spatial continuity that prevents the "where did this come from?" disorientation of a popup appearing from nowhere.
+
+**GitHub Star/Unstar.** Trigger: click on star icon. Rules: toggle filled/unfilled state, increment/decrement counter. Feedback: icon fills with yellow, counter updates, subtle scale bounce (110% then settle to 100%) over 200ms. The bounce is small enough to feel responsive without being playful. The unstar animation is equally weighted — same duration, same scale curve in reverse — so the interaction feels reversible and low-commitment.
+
+**Slack Typing Indicator.** Trigger: system event (remote keystroke received). Rules: show after 500ms continuous typing, hide 3s after last keystroke, display up to 3 names then "several people are typing." Feedback: animated ellipsis dots that bounce in sequence (each dot delayed 150ms from the previous) at the bottom of the message area. Loop: the animation loops continuously while active but is positioned to never obscure message content. The sequential dot bounce conveys ongoing activity without being distracting.
+
+**Vercel Deployment Status Transition.** Vercel's deployment card transitions between states (Queued, Building, Deploying, Ready, Error) with micro-interactions that communicate progress. The status dot changes color through a smooth hue transition (gray to yellow to blue to green) rather than an instant swap. The dot pulses with a subtle scale animation (100% to 110% to 100% over 1.2 seconds) while the deployment is in progress — the pulse communicates "working" without requiring the user to read the status text. On completion, the pulse stops and a checkmark draws in with a 300ms stroke animation. The entire transition sequence uses a consistent easing curve (`ease-in-out`) across all stages, creating temporal coherence.
+
+### Accessibility and Reduced Motion
+
+Micro-interactions must respect the `prefers-reduced-motion` media query. When the user has enabled reduced motion in their OS settings, all non-essential animations should be eliminated or replaced with instant state changes. The decision procedure:
+
+- **Essential animations (keep but simplify):** Loading spinners, progress indicators, state transitions that communicate system status. Replace with simpler versions — a spinner can become a pulsing dot, a slide transition can become a crossfade, a bounce can become an instant state swap.
+- **Decorative animations (remove entirely):** Celebratory confetti, hover bounces, parallax effects, background motion. These add delight for motion-tolerant users but cause discomfort (nausea, dizziness, disorientation) for vestibular disorder sufferers — approximately 35% of adults over 40 according to vestibular research.
+- **Implementation:** Wrap all animation definitions in a `prefers-reduced-motion: no-preference` media query. The default (no media query) should be the reduced state, not the animated state. This ensures that users with reduced motion preferences see no animation by default.
+
+```css
+/* Default: reduced motion (accessible baseline) */
+.button {
+  transition: none;
+}
+
+/* Enhanced: animations for users who have not requested reduced motion */
+@media (prefers-reduced-motion: no-preference) {
+  .button {
+    transition:
+      transform 150ms ease-out,
+      background-color 100ms ease;
+  }
+}
+```
+
+Material Design's motion documentation explicitly addresses this: all motion tokens have reduced-motion variants that replace transitions with instant state changes while preserving the visual state difference (the button still changes color on press, it just does not animate the change).
+
+### Micro-Interaction Decision Framework
+
+When deciding whether to add a micro-interaction, run this checklist:
+
+1. **Does it communicate state change?** If the interaction tells the user something changed (toggle flipped, item added, action completed), it is functional. Proceed.
+2. **Does it guide attention?** If the interaction draws the user's eye to where they need to look next (new item highlighted, error field pulsed), it is functional. Proceed.
+3. **Does it confirm the user's action?** If the interaction acknowledges that the system received the user's input (button press, form submit), it is functional. Proceed.
+4. **Does it only add visual delight?** If removing the interaction changes nothing about the user's ability to complete their task, it is decorative. Add it only if you have performance budget and it does not violate reduced motion preferences.
+5. **Does it delay the user?** If the user must wait for the animation to complete before they can proceed, the interaction is hostile regardless of how beautiful it is. Redesign it to be non-blocking.
+
+## Source
+
+- Saffer, D. — _Microinteractions: Designing with Details_ (2013), the four-part framework
+- Material Design — Motion documentation, https://m3.material.io/styles/motion
+- Apple Human Interface Guidelines — Animation and haptic feedback
+- Nielsen, J. — "Response Times: The 3 Important Limits" (1993), perceptual thresholds
+- Google Web Fundamentals — "Animations and Performance" (compositor-only properties)
+- W3C — "prefers-reduced-motion" media query specification, https://www.w3.org/TR/mediaqueries-5/#prefers-reduced-motion
+- Vestibular Disorders Association — Research on motion sensitivity prevalence
+- Thomas, B. and Tullis, T. — _Measuring the User Experience_ (2013), animation impact on task completion metrics
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/design-micro-interactions/skill.yaml

@@ -0,0 +1,35 @@
+name: design-micro-interactions
+version: "1.0.0"
+description: Small moments that delight — trigger, rules, feedback, loops/modes (Dan Saffer's framework), when micro-interactions aid usability vs decoration
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-feedback-patterns
+  - design-motion-principles
+  - design-affordances
+stack_signals: []
+keywords:
+  - micro-interactions
+  - trigger
+  - feedback
+  - loops
+  - Dan-Saffer
+  - delight
+  - usability
+  - animation
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/design-motion-principles/SKILL.md

@@ -0,0 +1,161 @@
+# Motion Principles
+
+> Purposeful animation — Disney's 12 principles adapted for UI, easing curves, duration guidelines, choreography, motion as feedback vs decoration, reducing motion
+
+## When to Use
+
+- Designing any interface element that changes state, position, size, or visibility over time
+- Evaluating whether an animation is purposeful (aids comprehension) or decorative (adds delight but no function)
+- Building a motion system or defining animation tokens for a design system
+- Choreographing multi-element transitions where several components animate simultaneously
+- Implementing reduced-motion alternatives for accessibility compliance
+- Reviewing animation performance and deciding between CSS transitions, CSS animations, and JavaScript-driven motion
+- Creating onboarding flows, page transitions, or loading sequences that use coordinated motion
+- Any decision about how something should move, how fast, and with what character
+
+## Instructions
+
+1. **Apply the "purpose test" before adding any animation.** Every animation must serve at least one of four purposes: (a) orient — show the user where they are in space or in a flow, (b) focus — direct attention to a change or new element, (c) express — reinforce brand personality through motion character, or (d) connect — show causal relationships between actions and outcomes. If an animation serves none of these, it is visual noise. Material Design 3's motion guidelines formalize this: transitions must "help users understand and navigate an app by showing how elements are related to each other." A sidebar sliding in from the left serves orient (spatial origin). A notification badge pulsing serves focus. A playful logo bounce serves express. A button morphing into a loading spinner serves connect.
+
+2. **Adapt Disney's 12 principles for UI motion selectively.** Disney's 1981 principles were designed for character animation, not interfaces. Six translate directly to UI. The remaining six are character-specific and should be ignored:
+
+   **Use these six:**
+   - **Squash and stretch** — elements compress on impact and stretch on departure. A modal landing on screen can scale from 102% to 100% on arrival (subtle squash). Material Design's FAB press applies 95% scale (squash) on press.
+   - **Anticipation** — a brief reverse motion before the main action. A card about to dismiss shifts 4-8px in the opposite direction before swiping away. Apple's delete animation retracts an item slightly before removing it.
+   - **Slow in and slow out (easing)** — natural motion accelerates and decelerates. This maps directly to CSS easing functions. Linear motion (`linear`) looks robotic. Always use curved easing.
+   - **Follow through and overlapping action** — secondary elements lag behind the primary. When a panel slides open, its content fades in 50-100ms after the panel reaches its final position. Linear's page transitions use this: the container slides in, then text elements fade up with a 40ms stagger.
+   - **Arcs** — natural motion follows curved paths, not straight lines. An element moving from a FAB position (bottom-right) to a dialog position (center) should follow a slight arc, not a straight diagonal. Material Design's "shared axis" transition uses arc paths for element relocation.
+   - **Staging** — present one idea at a time. Do not animate five elements simultaneously. Stagger entrances so the user can process each element: 40-80ms delay between items in a list, 100-150ms delay between major sections.
+
+   **Skip these six (character animation only):** Timing (subsumed by duration guidelines), secondary action (subsumed by overlapping action in UI), straight ahead / pose to pose (animation production methods), exaggeration (risks looking cartoonish in UI), solid drawing (3D modeling concept), appeal (subjective character design).
+
+3. **Define easing curves as system tokens.** Every animation in a system should use one of 3-5 named easing curves, never arbitrary `cubic-bezier` values. A production-ready easing system:
+   - **Standard** (`cubic-bezier(0.2, 0.0, 0, 1.0)`) — the default for most transitions. Starts fast, decelerates smoothly. Used for elements moving between resting positions.
+   - **Emphasized** (`cubic-bezier(0.2, 0.0, 0, 1.0)` for decelerate, `cubic-bezier(0.3, 0.0, 0.8, 0.15)` for accelerate) — for focal transitions that demand attention. Material Design 3 uses emphasized easing for hero transitions and container transforms.
+   - **Decelerate-only** (`cubic-bezier(0.0, 0.0, 0, 1.0)`) — for elements entering the screen. The element starts at full velocity and slows to a stop, matching the mental model of something arriving.
+   - **Accelerate-only** (`cubic-bezier(0.3, 0.0, 1, 1)`) — for elements exiting the screen. The element starts slow and accelerates away, matching departure.
+   - **Spring** (`spring(1, 100, 10, 0)` in frameworks that support it, or approximated as `cubic-bezier(0.34, 1.56, 0.64, 1)`) — for playful, physical interactions. Apple uses spring animations extensively: damping ratio 0.7-0.85, stiffness 200-400. The iOS keyboard uses a spring with damping 0.85 for its slide-up entrance.
+
+4. **Set duration by element size and travel distance, not by feel.** Small elements (icons, badges, checkmarks) need 100-150ms. Medium elements (cards, buttons, chips) need 200-300ms. Large elements (modals, drawers, page transitions) need 300-500ms. Full-screen transitions need 400-700ms. The rule: larger elements need more time because the eye tracks more visual change. Material Design 3's duration tokens:
+   - `duration-short1`: 50ms (micro-feedback: ripples, state layers)
+   - `duration-short2`: 100ms (small components: switch, checkbox)
+   - `duration-short3`: 150ms (selection controls, small transforms)
+   - `duration-short4`: 200ms (entering small components)
+   - `duration-medium1`: 250ms (standard component transitions)
+   - `duration-medium2`: 300ms (shared axis transitions)
+   - `duration-medium3`: 350ms (complex shape changes)
+   - `duration-medium4`: 400ms (full-screen transitions)
+   - `duration-long1` through `duration-long4`: 450-700ms (elaborate choreography)
+     Never exceed 700ms for any single animation. The user's perception of "instantaneous" ends at ~100ms and "connected to my action" ends at ~300ms.
+
+5. **Choreograph multi-element transitions with stagger and sequencing.** When multiple elements animate simultaneously, the result is chaos unless choreographed. Three choreography patterns:
+   - **Stagger:** Elements animate with identical motion but offset start times. List items entering: 40-80ms delay between each item. Linear uses 40ms stagger for issue lists — fast enough to feel fluid, slow enough that each item is individually perceivable.
+   - **Cascade:** Elements animate in dependency order — parent first, then children. A dialog enters (300ms), then its title fades in (200ms, 50ms delay), then body text (200ms, 100ms delay), then action buttons (150ms, 150ms delay). Vercel's deployment detail page uses this cascade pattern.
+   - **Shared motion:** Elements that are conceptually related animate in lockstep. A card expanding into a detail view — the card surface, the title, and the image all animate together on the same timeline with the same easing. Material Design's "container transform" is the canonical shared motion pattern.
+
+6. **Distinguish feedback motion from narrative motion.** Feedback motion is reactive — it responds to a user action (button press, toggle switch, form validation). Feedback must be fast (100-200ms), subtle, and never block the user from continuing. Narrative motion is proactive — it tells a story (onboarding sequence, loading animation, feature tour). Narrative motion can be longer (300-700ms per step), more elaborate, and is allowed to command full attention because it occurs at natural pause points. The error: using narrative-length motion for feedback actions, making the interface feel sluggish. A button press animation at 500ms is narrative motion misapplied to a feedback context.
+
+7. **Implement reduced motion as a first-class design concern, not an afterthought.** The `prefers-reduced-motion: reduce` media query indicates a user who experiences discomfort from animation. The implementation hierarchy:
+   - **Eliminate** all decorative animations (parallax, background motion, hover bounces)
+   - **Replace** transitions with instant state changes (crossfade in 1ms instead of slide over 300ms)
+   - **Preserve** essential state indicators (loading spinners become pulsing dots, progress bars remain but do not animate fill)
+   - **Never** remove information — if an animation communicates state (green checkmark drawing in), the end state must still appear (green checkmark shown instantly)
+
+   Apple's reduced-motion implementation is the gold standard: when enabled on iOS, the app-open zoom animation becomes a crossfade, the parallax home screen becomes static, and the swipe-to-go-back gesture still works but without the sliding animation — the page just appears.
+
+8. **Budget total motion per screen.** No more than 3 simultaneous animations visible to the user at any moment. Beyond 3, the eye cannot track individual movements and the experience feels chaotic. This budget means: if a page has a loading spinner, a skeleton screen pulse, and a notification badge animation all visible, adding a fourth animation (e.g., an animated gradient) exceeds the budget. Cut the least important one. Spotify's Now Playing screen respects this: album art color gradient (1), progress bar (2), and the waveform visualizer (3) — exactly three concurrent motions, each in a distinct screen region.
+
+## Details
+
+### Easing Function Mathematics
+
+An easing function maps input time `t` (0 to 1) to output progress `p` (0 to 1). A `cubic-bezier(x1, y1, x2, y2)` defines a cubic Bezier curve with fixed endpoints at (0,0) and (1,1) and two control points at (x1,y1) and (x2,y2).
+
+**Linear** (`cubic-bezier(0,0,1,1)`): `p = t`. Constant velocity. Feels mechanical. Use only for progress bars and video playback scrubbing where constant rate is the correct metaphor.
+
+**Ease-out** (`cubic-bezier(0, 0, 0.2, 1)`): Fast start, gradual deceleration. The element arrives with energy and settles. This is the most natural entry animation because it mimics an object being tossed — fast initial velocity, friction slows it. Material Design's `standard-decelerate` curve.
+
+**Ease-in** (`cubic-bezier(0.4, 0, 1, 1)`): Slow start, accelerating exit. The element gathers speed as it leaves. Less common in UI because exits are usually fast. Used for dismissal animations where the element accelerates off-screen.
+
+**Ease-in-out** (`cubic-bezier(0.4, 0, 0.2, 1)`): Accelerates then decelerates. Used for elements moving between two on-screen positions (e.g., a tab indicator sliding from one tab to another). Material Design's `standard` curve.
+
+**Spring physics** approximate overshoot — the element passes its target position, then oscillates back. Characterized by `damping` (how quickly oscillation stops; 0.7-0.85 for UI) and `stiffness` (how strong the pull to target; 200-400 for UI). Apple's iOS sheet presentation uses spring with damping 0.82, creating a single subtle overshoot that feels physically grounded without being bouncy. Frameworks: Framer Motion's `type: "spring"`, React Native's `Animated.spring()`, CSS `linear()` polyfill.
+
+### Motion Choreography Patterns
+
+**Shared-Axis Transition (Material Design 3).** When navigating along a spatial axis (list to detail, tab to tab), both the outgoing and incoming elements animate along that shared axis. Example: tapping a list item — the list fades and slides left (exit), while the detail view fades and slides in from the right (enter). Both use the x-axis as the shared axis. Duration: 300ms outgoing, 300ms incoming, with 35ms overlap. This creates spatial continuity — the user perceives a coherent space being navigated rather than disconnected pages being swapped.
+
+**Container Transform.** An element transforms into another element, maintaining visual continuity. The source element (e.g., a card) smoothly changes shape, size, and position to become the destination element (e.g., a full-screen detail view). The card's corner radius animates from 12px to 0px, its bounds expand to full screen, and its content crossfades from card layout to detail layout. Duration: 300-450ms. Easing: `emphasized`. Material Design 3 uses this for FAB-to-dialog and card-to-detail transitions.
+
+**Fade Through.** Two elements that are not spatially related transition via a sequential fade: the outgoing element fades out (90ms, `accelerate` easing), then the incoming element fades in (210ms, `decelerate` easing). Total: 300ms. A brief gap at the crossover point (both elements at low opacity) prevents the layered "double vision" effect of a simultaneous crossfade. Material Design uses fade through for bottom navigation tab switches.
+
+### Anti-Patterns
+
+1. **The Loading Screen Movie.** A 3-5 second elaborate animation sequence that plays every time the app loads or navigates between pages. Users see this animation hundreds of times. What felt impressive on first encounter becomes an infuriating delay by the tenth. The fix: loading animations should last no longer than the actual load time, and even then, they should be skeletal (skeleton screens, subtle pulsing) rather than narrative (logo animations, mascot dances). If your load time is 200ms, showing a 2-second loading animation makes the app feel 10x slower than it is.
+
+2. **Motion Sickness Roulette.** Using large-scale zoom, rotation, or parallax animations without reduced-motion alternatives. Approximately 35% of adults over 40 have vestibular sensitivity. A full-screen zoom transition or a rotating carousel can trigger nausea, dizziness, or disorientation. The fix: every animation that covers more than 50% of the viewport must have a `prefers-reduced-motion` alternative. This is not optional polish — it is an accessibility requirement equivalent to alt text for images.
+
+3. **Easing Anarchy.** Using different easing curves on every element — one card uses `ease-in-out`, another uses `ease-out`, the drawer uses a custom `cubic-bezier(0.68, -0.55, 0.27, 1.55)` with overshoot, and the tooltip uses `linear`. The interface feels like it was assembled from different physics engines. Fix: define 3-5 easing tokens and use them consistently. Every element in the system should share the same motion vocabulary.
+
+4. **Simultaneous Blast.** Animating all elements on a page at the same time with the same duration, creating a visual explosion where everything moves at once and nothing is individually trackable. The user's eye has no focal point. Fix: stagger entries by 40-80ms between elements. Lead with the most important element (the primary content), then reveal secondary elements (navigation, sidebar, auxiliary content) after the primary has settled.
+
+5. **The Un-interruptible Animation.** An animation that plays to completion regardless of user input. The user clicks a button, a 500ms animation starts, and the user cannot interact with anything until it finishes. This violates the fundamental principle that the interface should always respond to the user within 100ms. Fix: all animations should be interruptible — if the user takes a new action during an animation, the animation should be cancelled or rapidly completed (jump to end state in 50ms) so the new action can begin immediately.
+
+### Motion Budget Framework
+
+A motion budget prevents animation overload by quantifying the total animation complexity allowed per screen. The budget has three dimensions:
+
+**Concurrent animation count.** Maximum 3 simultaneous animations visible to the user at any moment. Track this by auditing each screen state: if a loading spinner, a skeleton pulse, and a background gradient animation are all visible, the budget is spent. A notification entrance animation would need to wait for one of the three to complete. Spotify's Now Playing screen exemplifies exact budget adherence: album art gradient (1), progress bar (2), waveform (3) — no fourth animation.
+
+**Cumulative animation duration per navigation action.** The total animation time between a user's action (click, tap, swipe) and the system reaching a fully settled state should not exceed 600ms. If a page transition takes 300ms and a content stagger takes 300ms, the budget is spent. Adding a third animation (e.g., sidebar slide) would push past the 600ms threshold and make the interface feel slow. Linear keeps total transition duration under 400ms by overlapping exit and entrance animations.
+
+**Animation surface area.** The percentage of the viewport undergoing animation at any moment. Full-screen transitions (100% surface area) should be reserved for major navigation events (page changes, modal opens). Partial-screen animations (cards, panels, lists) should affect less than 40% of the viewport simultaneously. Micro-interactions (buttons, toggles, icons) should affect less than 5%. When more than 40% of the viewport animates simultaneously, users report the interface feeling "chaotic" regardless of animation quality.
+
+### Motion Decision Procedure
+
+Before adding any animation, answer these questions in order:
+
+1. **Does this animation exist in the motion token system?** If yes, use the existing token (duration, easing, property). If no, check if an existing token can serve the purpose. Only create a new token if no existing one applies — and update the token documentation.
+2. **What purpose does this animation serve?** Map it to one of the four purposes (orient, focus, express, connect). If none apply, the animation is decorative — skip it unless you have explicit budget.
+3. **What is the duration?** Look up the element size in the duration scale. Do not use custom durations.
+4. **What is the easing?** Enter = decelerate. Exit = accelerate. Move = standard. Playful = spring. Do not use custom curves.
+5. **Does this exceed the concurrent animation budget?** Check what else will be animating when this fires. If the budget is spent, queue or cut.
+6. **What is the reduced-motion alternative?** Define it now, not later. If the animation is functional, provide a simplified version. If decorative, provide instant state change.
+
+### Real-World Examples
+
+**Apple's Spring Animation System.** Apple uses spring physics as the foundation for nearly all iOS animations. The home screen app icon press uses `stiffness: 400, damping: 0.72` — a quick, slightly bouncy compression. The sheet presentation (swipe up to show a modal card) uses `stiffness: 300, damping: 0.85` — a slower, more dampened slide with exactly one subtle overshoot. The key insight: spring animations feel natural because they are governed by physics equations rather than arbitrary curves. Two springs with different stiffness/damping values still feel like they belong to the same physical world because they share the same underlying motion model.
+
+**Material Design 3 Motion System.** MD3 defines three categories: transitions (between screens), component animations (within a screen), and state-layer animations (hover, press, focus). Each category has specific duration ranges and easing tokens. Transitions use 300-700ms with `emphasized` easing. Component animations use 100-300ms with `standard` easing. State-layer animations use 50-150ms with `standard` easing. This three-tier system ensures that no component animation is ever mistaken for a transition (the duration gap prevents it) and that state-layer feedback never feels sluggish (the 150ms ceiling ensures responsiveness).
+
+**Linear's Page Transition Choreography.** Linear's web app transitions between views (inbox, project board, settings) using a choreographed sequence: outgoing content fades out with a slight upward movement (150ms, `accelerate`), then incoming content fades in with a slight downward-to-resting movement (200ms, `decelerate`) with a 40ms stagger between the header, main content, and sidebar sections. The total transition feels instantaneous (~250ms perceived) despite involving 6+ individual animations. The secret: overlapping the exit and entrance by 50ms so there is no "dead" gap where the screen is empty.
+
+**Spotify's Contextual Motion Language.** Spotify uses motion to reinforce its audio-visual brand. Album art transitions use a crossfade with scale (the new album grows from 95% to 100% while fading in, the old album shrinks to 95% while fading out — 300ms, `ease-out`). The Now Playing bar slides up from the bottom with a spring animation when first invoked, then snaps between minimized and expanded states. List scrolling uses inertia-based deceleration that matches iOS physics exactly — Spotify does not override the platform scroll behavior, ensuring familiarity. The waveform visualizer uses a custom animation that synchronizes with audio amplitude, creating a motion that is impossible to separate from the content it represents.
+
+## Source
+
+- Thomas, F. and Johnston, O. — _The Illusion of Life: Disney Animation_ (1981), the 12 principles
+- Material Design 3 — Motion documentation, https://m3.material.io/styles/motion
+- Apple Human Interface Guidelines — Motion and spring animations
+- CSS Specification — `transition-timing-function`, https://www.w3.org/TR/css-transitions-1/#transition-timing-function-property
+- Google Web Fundamentals — "Animations and Performance" (compositor-only properties)
+- W3C — `prefers-reduced-motion` media query, https://www.w3.org/TR/mediaqueries-5/#prefers-reduced-motion
+- Framer Motion — Spring animation configuration documentation
+- Val Head — _Designing Interface Animation_ (2016), motion design principles for UI
+- Issara Willenskomer — "Creating Usability with Motion" (UX in Motion Manifesto)
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/design-motion-principles/skill.yaml

@@ -0,0 +1,36 @@
+name: design-motion-principles
+version: "1.0.0"
+description: Purposeful animation — Disney's 12 principles adapted for UI, easing curves, duration guidelines, choreography, motion as feedback vs decoration, reducing motion
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-micro-interactions
+  - design-transitions-timing
+  - design-gestalt-common-fate
+  - a11y-motion-animation
+stack_signals: []
+keywords:
+  - motion
+  - animation
+  - easing
+  - duration
+  - choreography
+  - Disney-principles
+  - reduced-motion
+  - purposeful-animation
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []