enhance-motionAudit an existing web app's motion, then apply one coherent, reduced-motion-safe pass. Use when "motion pass", "animate the app", or "add micro-interactions". One new animation → design-motion.
Independent GitHub snapshot · Automated classification · Original documentation governs
Degree of freedom: MIXED. Tier and token judgment [HIGH freedom]; reduced-motion, GPU-only, and verify [LOW freedom — run exactly].
Add motion to an app that already exists, without fragmenting its visual language. The failure mode this prevents: bolting on one hero animation, three different easing curves, and a heavyweight library where a CSS class would do — motion that fights the design system instead of reinforcing it.
Motion must be coherent, purposeful, reduced-motion-safe, and 60fps. Pick the lightest tool that fits each interaction. Every animation gets its timing and easing from a motion-token SSOT, not ad-hoc magic numbers.
This skill applies motion and verifies it. For a from-scratch motion cookbook (no
existing system to respect), use design-motion. For pure animation-perf triage, use
audit-performance.
Before any browser interaction, read protocol-browser-anti-stall and apply it.
Inventory: Tailwind
duration-300+ oneframer-motionmodal; no reduced-motion; four easings. Right-size: buttons stay CSS; lists get Auto-Animate; modal stays Motion; no GSAP. Tokenize:--motion-fast/base/slow+ three easings in the theme file. Gate:motion-reduce:zeros travel; layout props not animated; modal 60fps.
design-motion; perf-only triage → audit-performanceThis skill targets web / React (or Vue/Svelte) UI. If the repo is a CLI, library,
backend, or non-visual target, bow out and say so. If it is an Expo / React Native
or Capacitor app, hand off to enhance-mobile-native-feel: spring motion on the UI
thread, haptics, and native chrome live there, and the web tiers below do not apply.
Reuse the audit-uiux-design-system detection, then focus on motion:
# Libraries already present
cat package.json | grep -iE "motion|framer|gsap|auto-animate|tw-animate|animate.css|react-spring"
# Existing CSS motion + Tailwind config
rg -n "@keyframes|animation:|transition:" -g "*.css"
rg -n "animate-|transition-|duration-|ease-" -g "*.{tsx,jsx,vue,svelte}" -c
# Existing JS motion
rg -n "motion\.|useSpring|AnimatePresence|useScroll|gsap|autoAnimate" -g "*.{tsx,jsx}" -c
# Reduced-motion support (critical)
rg -n "prefers-reduced-motion|motion-safe|motion-reduce|useReducedMotion" -g "*.{tsx,jsx,css}"
STACK: framework=<...> · CSS=<Tailwind v3/v4 / CSS Modules / ...> · UI lib=<...>
MOTION TODAY: libraries=<...> · easings in use=<list> · durations in use=<list>
REDUCED MOTION: honored? <yes/no — where>
INCOHERENCE FOUND: <e.g. 4 easing curves, 3 durations for the same interaction>
Follow the /research protocol: Context7 for the chosen library's current API, Firecrawl
for current patterns dated to now. Anchor to versions actually installed. Motion (formerly
Framer Motion) is motion on npm.
Do not add every library. Pick the lightest tool that fits, and prefer what the repo already uses if it's adequate:
| Tier | Tool | Use for |
|---|---|---|
| 1 — CSS utility | tw-animate-css (Tailwind v4 successor to tailwindcss-animate; shadcn's default) or existing Tailwind keyframes | fades, accordions, enter/exit utility classes, simple hovers |
| 2 — zero-config layout | @formkit/auto-animate | list/table add·remove·reorder, expanding sections — no config |
| 3 — component transitions | motion (motion.dev) — scoped to component transitions, AnimatePresence, gestures, spring hovers | modals, tabs, toasts, presence, drag |
| 4 — complex timelines | gsap — only when Tier 3 cannot express it | scroll narratives, sequenced SVG, scrubbed timelines |
| Reference | Kinetics (kinetics.colorion.co) | curated copy-paste pattern source — adapt to tokens; not a dependency |
State the chosen tier(s) and why. Keep the dependency footprint minimal.
Motion values are tokens, coherent with the existing scale (collapse the incoherence found in 0c into one set). Add to the token source (Tailwind theme / CSS variables):
/* durations */ --motion-fast: 120ms; --motion-base: 200ms; --motion-slow: 320ms;
/* easings */ --ease-standard: cubic-bezier(0.2,0,0,1); /* enter/state */
--ease-emphasized: cubic-bezier(0.3,0,0,1); /* prominent */
--ease-exit: cubic-bezier(0.4,0,1,1); /* exit */
/* distance */ --motion-shift: 8px;
All animations reference these — no inline magic numbers. Micro-interactions ≤ ~150ms, entrances ~200–320ms, exits faster than entrances.
Work interaction-by-interaction; prefer mechanical, token-driven edits. For each element, use the lightest fitting tier from 1b.
hover, active (scale 0.98), focus-visible
ring, using tokens. Distinct response per element type.AnimatePresence for
exit, backdrop fade + content scale/slide, tab indicator slide. Gestures (drag,
whileHover, whileTap) where they add feel.Preserve all existing functionality and states — motion is additive. Never remove a handler or state to "simplify."
prefers-reduced-motion: reduce.
Use useReducedMotion() (Motion), motion-safe:/motion-reduce: (Tailwind), or a CSS
media query that drops durations to ~0. Essential feedback stays (opacity), spatial
movement is removed.transform / opacity only. No animating width/height/top/left.rg -n "(transition|animate)-\[[^]]*(width|height|top|left|margin)" -g "*.{tsx,jsx,css}" # flag layout-triggering
rg -n "prefers-reduced-motion|useReducedMotion|motion-reduce" -g "*.{tsx,css}" # confirm coverage
.playwright-mcp/, check console for errors, confirm animations run
and reduced-motion drops them (toggle emulation).## Motion Enhancement — report
**Stack:** [..] **Tiers used:** CSS/tw-animate-css · Auto-Animate · Motion · (GSAP: y/n)
**Motion tokens:** durations [..] · easings [..] — single source in [file]
**Coherence fixed:** collapsed [N] easings → 3, [N] durations → 3
**Applied to:** buttons/cards (CSS), lists (Auto-Animate), modals/tabs/toasts (Motion), ...
**A11y:** prefers-reduced-motion honored across [N] components (evidence)
**Perf:** transform/opacity only; [component] verified 60fps; no CLS
**Verification:** build ✓ · console clean ✓ · before/after screenshots [paths]
design-motion — from-scratch motion cookbook (Framer/Motion/GSAP/CSS patterns)enhance-mobile-native-feel — the mobile-app counterpart (Reanimated springs, haptics, native chrome)audit-uiux-design-system — the broader visual coherency audit this builds onaudit-performance — animation performance / Core Web Vitals triageaudit-accessibility — reduced-motion and focus-order verificationhousekeep-design — if motion incoherence is part of wider design drift, consolidate firstprotocol-browser-anti-stall — required for the browser verification step