Enhance motion

enhance-motion — Coherent Motion for an Existing App

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.

---

Phase 0 — Detect the design system and current motion

0a. Applicability gate

This 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.

0b. Inventory the design system + motion state

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}"

0c. Record discovery

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>

---

Phase 1 — Choose the tier + define the motion-token SSOT

1a. Research (current)

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.

1b. Right-size the library per interaction

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.

1c. Define the motion-token SSOT

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.

---

Phase 2 — Apply motion, tier by tier

Work interaction-by-interaction; prefer mechanical, token-driven edits. For each element, use the lightest fitting tier from 1b.

• Buttons / links / cards: Tier 1 CSS — hover, active (scale 0.98), focus-visible ring, using tokens. Distinct response per element type.
• Lists / grids / expandable sections: Tier 2 Auto-Animate — wrap the parent; items animate on add/remove/reorder with zero per-item code.
• Modals / dialogs / toasts / tabs / dropdowns: Tier 3 Motion — AnimatePresence for exit, backdrop fade + content scale/slide, tab indicator slide. Gestures (drag, whileHover, whileTap) where they add feel.
• Page/route transitions: template/layout-level fade+shift, kept subtle (respect the "component transitions only" scope — no heavyweight route choreography by default).
• Scroll narratives / hero timelines: Tier 4 GSAP only if genuinely needed.

Preserve all existing functionality and states — motion is additive. Never remove a handler or state to "simplify."

---

Phase 3 — Accessibility & performance gates (non-negotiable)

• Reduced motion: every animation degrades under 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.
• GPU-only: animate transform / opacity only. No animating width/height/top/left.
• No CLS: transitions must not shift layout unexpectedly; reserve space.
• Interruptibility: enter/exit must not trap state if toggled rapidly.

rg -n "animate\[.*(width|height|top|left|margin)" -g "*.{tsx,css}"   # flag layout-triggering
rg -n "prefers-reduced-motion|useReducedMotion|motion-reduce" -g "*.{tsx,css}"  # confirm coverage

---

Phase 4 — Verify and report

• playwright-cli: navigate touched routes, capture before/after screenshots to .playwright-mcp/, check console for errors, confirm animations run and reduced-motion drops them (toggle emulation).
• 60fps: spot-check in DevTools Performance for any Tier 3/4 animation.
• Build/typecheck: run the repo's commands; fix anything introduced.

## 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]

---

Related

• design-motion — from-scratch motion cookbook (Framer/Motion/GSAP/CSS patterns)
• audit-uiux-design-system — the broader visual coherency audit this builds on
• audit-performance — animation performance / Core Web Vitals triage
• audit-accessibility — reduced-motion and focus-order verification
• housekeep-design — if motion incoherence is part of wider design drift, consolidate first
• protocol-browser-anti-stall — required for the browser verification step