Ui Animation

1---2name: ui-animation3description: Creates, reviews, and debugs UI motion and animation implementations. Covers springs, gestures, drag interactions, clip-path reveals, easing, timing, and animation review. Use when designing, implementing, or reviewing motion, CSS transitions, keyframes, framer-motion, spring animations, asking "add animations to", "make this feel smooth", "review my animations", "should this animate", or "add a swipe gesture"4---5 6# UI Animation7 8## Reference files9 10| File                                                                       | Read when                                                                    |11| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |12| [references/decision-framework.md](references/decision-framework.md)       | Default: animation decisions, easing, and duration                           |13| [references/spring-animations.md](references/spring-animations.md)         | Using spring physics, framer-motion useSpring, configuring spring params     |14| [references/component-patterns.md](references/component-patterns.md)       | Building buttons, popovers, tooltips, drawers, modals, toasts with animation |15| [references/clip-path-techniques.md](references/clip-path-techniques.md)   | Using clip-path for reveals, tabs, hold-to-delete, comparison sliders        |16| [references/gesture-drag.md](references/gesture-drag.md)                   | Implementing drag, swipe-to-dismiss, momentum, pointer capture               |17| [references/performance-deep-dive.md](references/performance-deep-dive.md) | Debugging jank, CSS vs JS, WAAPI, CSS variables trap, Framer Motion caveats  |18| [references/review-format.md](references/review-format.md)                 | Reviewing animation code — Before/After/Why table and issue checklist        |19| [references/contextual-animations.md](references/contextual-animations.md) | Implementing contextual icon swaps, word-level stagger entrances, or fixed-offset exit animations |20 21## Core rules22 23- Animate for feedback, orientation, continuity, or deliberate delight.24- Never animate keyboard-initiated actions (shortcuts, arrow navigation, tab/focus).25- Prefer CSS transitions for interruptible UI; use keyframes only for predetermined sequences.26- CSS transitions > WAAPI > CSS keyframes > JS (requestAnimationFrame).27- Make animations interruptible and input-driven.28- Asymmetric timing: enter can be slightly slower; exit should be fast.29- Use `@starting-style` for DOM entry animations; fall back to `data-mounted`.30- A small `filter: blur(2px)` can hide rough crossfades.31 32## Motion design principles33 34- **Continuity over teleportation.** Elements visible in both states transition in place. Never duplicate a persistent element or hard-cut between views that share components.35- **Directional motion matches position.** Tab and carousel transitions animate in the direction matching spatial layout (left-to-right for forward, right-to-left for back).36- **Emerge from the trigger.** Overlays, trays, and panels animate outward from the element that opened them. Generic centre-screen entrances break spatial orientation.37- **Consistent polish everywhere.** Under-animated areas make the entire product feel unpolished. Motion quality must be uniform across all surfaces.38- **Delight scales inversely with frequency.** Rarer interactions have more room for personality and surprise. High-frequency actions must be invisible.39- **Motion enhances perceived speed.** Smooth transitions between states feel faster than hard cuts, even at identical load times.40 41## What to animate42 43- Movement: `transform` and `opacity` only.44- State feedback: `color`, `background-color`, and `opacity` are acceptable.45- Never animate layout properties (`width`, `height`, `top`, `left`); never use `transition: all`.46- Avoid `filter` animation for core interactions; keep blur <= 20px if unavoidable.47- SVG: apply transforms on a `<g>` wrapper with `transform-box: fill-box; transform-origin: center`.48- Disable transitions during theme switches (`[data-theme-switching] * { transition: none !important }`).49 50## Easing defaults51 52| Element                       | Duration     | Easing                           |53| ----------------------------- | ------------ | -------------------------------- |54| Button press feedback         | 100–160ms    | `cubic-bezier(0.22, 1, 0.36, 1)` |55| Tooltips, small popovers      | 125–200ms    | `ease-out` or enter curve        |56| Dropdowns, selects            | 150–250ms    | `cubic-bezier(0.22, 1, 0.36, 1)` |57| Modals, drawers               | 200–350ms    | `cubic-bezier(0.22, 1, 0.36, 1)` |58| Move/slide on screen          | 200–300ms    | `cubic-bezier(0.25, 1, 0.5, 1)`  |59| Simple hover (colour/opacity) | 200ms        | `ease`                           |60| Illustrative/marketing        | Up to 1000ms | Spring or custom                 |61 62**Named curves**63 64- **Enter:** `cubic-bezier(0.22, 1, 0.36, 1)` — entrances and transform-based hover65- **Move:** `cubic-bezier(0.25, 1, 0.5, 1)` — slides, drawers, panels66- **Drawer (iOS-like):** `cubic-bezier(0.32, 0.72, 0, 1)`67 68Avoid `ease-in` for UI. Prefer custom curves from [easing.dev](https://easing.dev/).69 70## Spatial and sequencing71 72- Set `transform-origin` at the trigger point for popovers; keep `center` for modals.73- For dialogs/menus, start around `scale(0.85–0.9)`. Never `scale(0)`.74- Stagger reveals at 30–50ms per item; total stagger under 300ms.75 76## Accessibility77 78- Gate hover animations behind `@media (hover: hover) and (pointer: fine)` to avoid false positives on touch.79- During direct manipulation, keep the element locked to the pointer. Add easing only after release.80 81## Performance82 83- Only animate `transform` and `opacity` — these skip layout and paint.84- Pause looping animations off-screen with `IntersectionObserver`.85- Toggle `will-change` only during heavy motion and only for `transform`/`opacity` — remove after.86- Do not animate drag gestures using CSS variables (triggers recalc on all children).87- Motion `x`/`y` values are the normal choice for axis-based movement and drag. Use full `transform` strings when you need one transform owner for combined transforms or interop.88- See [references/performance-deep-dive.md](references/performance-deep-dive.md) for WAAPI, compositing layers, and CSS vs JS comparison.89 90## Anti-patterns91 92- `transition: all` — triggers layout recalc and animates unintended properties.93- Animating layout properties (`width`, `height`, `top`, `left`) for interactive feedback.94- Using `ease-in` for UI entrances — feels sluggish.95- Animating from `scale(0)` — nothing in the real world appears from nothing. Use `scale(0.85–0.95)`.96- Animating on mount without user trigger — unexpected motion is disorienting.97- Permanent `will-change` — toggle it only during heavy motion.98- CSS variables for drag gesture animation — repaints every frame.99- Symmetric enter/exit timing — exit should be faster (user expects instant response).100- Hard stops on drag boundaries — use friction/damping instead.101- Mixing Motion `x`/`y` props with a handwritten `transform` string on the same element.102- Keyframes on rapidly-triggered elements — use CSS transitions for interruptibility.103- Static cuts between related views — if views share elements, hard cuts lose spatial context. Transition shared elements in place.104- Duplicating persistent elements across states — animate the same element from its current position to its next, rather than hiding one and showing another.105- Generic centre-screen entrance for contextual content — overlays and trays should emerge from their trigger, not fade in from nowhere.106 107## Workflow108 109Copy and track this checklist:110 111```text112Animation progress:113- [ ] Step 1: Decide whether the interaction should animate114- [ ] Step 2: Choose purpose, easing, and duration115- [ ] Step 3: Pick the implementation style116- [ ] Step 4: Load the relevant component or technique reference117- [ ] Step 5: Validate timing, interruption, and device behavior118```119 1201. Answer the four questions from [references/decision-framework.md](references/decision-framework.md): should it animate? What purpose? What easing? What speed?1212. Pick duration from the easing defaults table above.1223. Choose implementation: CSS transition > WAAPI > spring > keyframe > JS.1234. Load the relevant reference for your component type or technique.1245. When reviewing, use the Before/After/Why table format from [references/review-format.md](references/review-format.md).125 126## Validation127 128- Verify no layout property animations (`width`, `height`, `top`, `left`).129- Check that looping animations pause off-screen.130- Confirm `will-change` is toggled only during animation, not permanently set.131- Retoggle components quickly to confirm transitions retarget cleanly instead of restarting from zero.132- Slow animations to 0.1x in DevTools to catch timing issues invisible at full speed.133- Record and play back frame-by-frame for coordinated property timing.134- Test touch interactions on real devices (not just simulators).