ui-animation

UI animation

Contract

Inputs

• Required: a UI element or component to animate, or an explicit request to build an animation from scratch.
• Optional: reference recording (screen capture or video), target framework or library (CSS, React, SwiftUI, Compose, etc.), existing design tokens or motion constants.
• Blocked: anything requiring network calls, authentication, or non-local execution beyond the project directory.

Procedure

1. Classify the ask. If the user names a framework or library, route to its animation primitives. If the user supplies a screen recording or video, propose curve-fitting extraction before writing code. Done when: the framework is identified and the approach is chosen.
2. Validate scope. Confirm the animation target is a UI element, component, or screen under the project directory. Done when: the target is confirmed local and in-scope.
3. Decide whether to animate. Reject a request if animation does not serve a clear functional purpose (feedback, transition, continuity, guidance). State the rejection reason and wait for clarification. Done when: a functional purpose is confirmed or the rejection is delivered.
4. Select animation type. Choose from: entrance, exit, state transition, scroll-linked, gesture-driven, or continuous ambient. Reject compound multi-type animations unless the user splits them. Done when: exactly one animation type is selected.
5. Design the animation. For each moving element:
   • Pick a physics model: spring (mass–stiffness–damping), easing curve (CSS cubic-bezier or equivalent), or keyframe sequence.
   • Choose a duration and easing. Default to fast (150–250 ms) for micro-interactions, medium (250–400 ms) for transitions.
   • For spring animations, compute or estimate stiffness, damping, and mass. Never hard-code arbitrary numbers without rationale.
   • For gesture-driven animations, model the drag axis, snap points, and release velocity. Done when: every moving element has a physics model, duration, and easing.
6. Apply choreography. When multiple elements move together, define the sequence, stagger interval, and overlap. State the choreography logic explicitly. Done when: the sequence and stagger are defined for every concurrent element.
7. Respect reduced motion. If the user request or the prefers-reduced-motion media query is detected, replace physics-based or continuous animations with instant state changes or opacity-only fades. Document this substitution. Done when: reduced-motion handling is present and documented.
8. Write the animation code. Produce code in the target framework or library. Annotate each transition with the curve name, duration, and the element it affects. Inline the animation; do not assume a shared motion library exists. Done when: every animation block has a named curve, duration, and target.
9. Validate the output. Confirm every animation block has a defined curve, duration, and target. Confirm reduced-motion is handled. If a Python script was run to extract motion, note the script name and what it produced. Done when: all blocks pass the validation checks.