set-up-motion · diff
git:20260608.8cf5ea0 to git:20261009.0ae007b
21 added, 14 removed. Audit A to A.
---
name: set-up-motion
description: Use when adding animation and transitions to a frontend — uses the native View Transitions API for navigation/layout changes and the Motion library (motion/react, formerly Framer Motion) for component enter/exit/gesture animation, with every animation gated behind prefers-reduced-motion.
---
# Set Up Motion
## 1. Audit current state
```bash
- grep -E '"(motion|framer-motion|@vueuse/motion)"' package.json 2>/dev/null
+ cat .claude/stack-profile.md 2>/dev/null || cat ~/.claude/stack-profile.md 2>/dev/null # frontend.framework, frontend.meta, package_manager
+ grep -E '"(motion|framer-motion|motion-v|@vueuse/motion)"' package.json 2>/dev/null
grep -rn "startViewTransition\|view-transition-name\|prefers-reduced-motion\|useReducedMotion" src/ 2>/dev/null | head
```
- **Prerequisites:** `@/` alias; pairs with `set-up-routing` (route view-transitions) and `configure-accessibility` (reduced-motion is an a11y requirement, not a nicety).
+ Read `frontend.framework` and `package_manager` (commands use pnpm). `frontend.meta` of `nuxt` ships `motion-v/nuxt` and its own page transitions — prefer those. **Prerequisites:** `@/` alias; pairs with `set-up-routing` (route view-transitions) and `configure-accessibility` (reduced-motion is an a11y requirement, not a nicety).
## 2. Decide what to do
- No motion → full setup.
- Animations present but always-on (ignore reduce-motion) → gate them (step 7) — that's an accessibility bug.
## 3. Detect framework
- React → **Motion** (`motion/react`). Vue → **`@vueuse/motion`**. The View Transitions API is native (no dependency) and works in both.
+ React → **Motion** (`motion/react`). Vue → **`motion-v`**, the Vue build of Motion (documented on motion.dev; same props, `AnimatePresence`, `MotionConfig`). The View Transitions API is native (no dependency) and works in both. Why: `motion-patterns.md`.
## 4. Install
```bash
pnpm add motion # React (the package was renamed from framer-motion)
- # Vue: pnpm add @vueuse/motion
+ # Vue: pnpm add motion-v
```
## 5. View Transitions for navigation + layout changes
Native, GPU-accelerated, near-zero JS. Wrap any DOM change you want animated:
```ts
// src/utils/withViewTransition.ts
- export function withViewTransition(update: () => void) {
+ export function withViewTransition(update: () => void | Promise<void>): void {
const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches;
if (reduce || !document.startViewTransition) {
- update();
+ void update();
return;
}
- document.startViewTransition(update);
+ document.startViewTransition(update); // the browser snapshots the new DOM after `update` settles
}
```
+ The callback must finish the DOM change before it returns or its promise settles. React state updates are batched, so flush them inside: `withViewTransition(() => flushSync(() => setView(next)))`. In Vue, await the DOM: `withViewTransition(async () => { await router.push(to); await nextTick(); })`. React 19.3 also ships a stable `<ViewTransition>` component that animates updates made in a `startTransition` / Suspense reveal without calling the API by hand — prefer it for React state changes; keep this helper for Vue and non-React code.
- For routing, let the router drive it: TanStack Router exposes a `viewTransition` option on `<Link>`/navigation; Vue Router pairs with `startViewTransition` in an `afterEach`/`<RouterView>` wrapper. Name shared elements so they morph between routes:
+ For routing, let the router drive it: TanStack Router has `defaultViewTransition` on `createRouter` and a `viewTransition` prop on `<Link>`; Vue Router has no built-in hook, so wrap the navigation as above. Name shared elements so they morph between routes:
```css
/* the element that persists across routes */
.hero { view-transition-name: hero; }
@media (prefers-reduced-motion: reduce) {
::view-transition-group(*),
::view-transition-old(*),
::view-transition-new(*) { animation: none !important; }
}
```
## 6. Component animation with Motion (React)
```tsx
- import { motion, AnimatePresence, useReducedMotion } from 'motion/react';
+ // src/main.tsx — once, at the root: every motion component honours the OS setting
+ import { MotionConfig } from 'motion/react';
+ // <MotionConfig reducedMotion="user"><App /></MotionConfig>
+ ```
+ ```tsx
+ import { AnimatePresence, motion } from 'motion/react';
export function Toast({ open, children }: { open: boolean; children: React.ReactNode }) {
- const reduce = useReducedMotion();
return (
<AnimatePresence>
{open && (
<motion.div
- initial={reduce ? false : { opacity: 0, y: 8 }}
+ initial={{ opacity: 0, y: 8 }}
animate={{ opacity: 1, y: 0 }}
- exit={reduce ? { opacity: 0 } : { opacity: 0, y: 8 }}
+ exit={{ opacity: 0, y: 8 }}
transition={{ duration: 0.2, ease: 'easeOut' }}
>
{children}
</motion.div>
)}
</AnimatePresence>
);
}
```
- `AnimatePresence` is the reason to reach for Motion — it animates **exit**, which CSS can't do on unmount. Vue: `@vueuse/motion`'s `v-motion` directive, or Vue's built-in `<Transition>`/`<TransitionGroup>` for simple enter/exit.
+ Under `reducedMotion="user"` Motion drops the transform (`y`) and layout animation and keeps the opacity fade, so the component carries no reduced-motion branch of its own.
+ `AnimatePresence` is the reason to reach for Motion — it animates **exit**, which CSS can't do on unmount. Vue: `motion-v`'s `<motion.div>` inside `<AnimatePresence>` (same API, wrap the app in its `MotionConfig`), or Vue's built-in `<Transition>`/`<TransitionGroup>` for simple enter/exit.
## 7. Gate everything behind reduced motion
Three layers, all required:
- - **Motion:** `useReducedMotion()` → skip or simplify (above).
+ - **Motion:** `<MotionConfig reducedMotion="user">` at the root (above); `useReducedMotion()` only for custom cases such as stopping autoplay video.
- **Tailwind:** author transitions as `motion-safe:transition` / disable with `motion-reduce:transition-none`.
- **View Transitions:** the `@media (prefers-reduced-motion: reduce)` block (step 5) kills them.
Essential feedback (a spinner) may remain; decorative motion (parallax, large slides) must not.
## 8. Verify
```bash
pnpm dev
```
Animations play normally; with OS "Reduce motion" on, transitions are removed/instant and nothing janks. Check the Performance panel: animated properties stay on the compositor (transform/opacity), no layout thrash.
## References
- ./motion-patterns.md — View-Transitions-vs-Motion, animate-transform-not-layout, reduced-motion, motion-is-feedback, performance budget.
- ../configure-accessibility/SKILL.md — reduced motion as an a11y requirement.
- ../_shared/conventions.md — `@/` alias, `utils/` for the pure `withViewTransition` helper.