[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77XXXCTZMS002H2M8VATGSN":3,"skill-same:01M77XXXCTZMS002H2M8VATGSN":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":32,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M77XXXCTZMS002H2M8VATGSN","motion-ui",null,"Production-ready UI motion system for React\u002FNext.js. Use when implementing animations, transitions, or motion patterns.","503496348-ops\u002Fmischief-production","503496348-ops","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F266905914?v=4","01M77X5J7XQWWZGT8998HDGXQM","AtomCollide","01M77X5J8V78Y3NXMY6BBC75X9",2,"MIT","https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production\u002Fblob\u002Fmain\u002Fskills\u002Fecc-motion-ui\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: motion-ui\ndescription: \"Production-ready UI motion system for React\u002FNext.js. Use when implementing animations, transitions, or motion patterns.\"\nmetadata:\n  origin: HCP\n---\n\n# Motion System v4.2\n\nProduction-ready UI motion system for React \u002F Next.js.\n\nFocused on **performance, accessibility, and usability** — not decoration.\n\n## When to Use\n\nUse this motion system when motion:\n\n* Guides attention (e.g., onboarding, key actions)\n* Communicates state (loading, success, error, transitions)\n* Preserves spatial continuity (layout changes, navigation)\n\n### Appropriate Scenarios\n\n* Interactive components (buttons, modals, menus)\n* State transitions (loading → loaded, open → closed)\n* Navigation and layout continuity (shared elements, crossfade)\n\n### Considerations\n\n* **Accessibility**: Always support reduced motion\n* **Device adaptation**: Adjust for low-end devices\n* **Performance trade-offs**: Prefer responsiveness over visual smoothness\n\n### Avoid Using Motion When\n\n* It is purely decorative\n* It reduces usability or clarity\n* It impacts performance negatively\n\n---\n\n## How It Works\n\n### Core Principle\n\nMotion must:\n\n* Guide attention\n* Communicate state\n* Preserve spatial continuity\n\nIf it does none → remove it.\n\n---\n\n### Installation\n\n```bash\nnpm install motion\n```\n\n---\n\n### Version\n\n* `motion\u002Freact` - default for current Motion for React projects (package: `motion`)\n* `framer-motion` - legacy import path for projects that still depend on Framer Motion\n\n**Do not mix.** Mixing causes conflicting internal schedulers and broken `AnimatePresence` contexts — components from one package will not coordinate exit animations with components from the other.\n\nTo check which version your project uses:\n\n```bash\ncat package.json | grep -E '\"motion\"|\"framer-motion\"'\n```\n\nAlways import from one source consistently:\n\n```ts\n\u002F\u002F Correct (modern)\nimport { motion, AnimatePresence } from \"motion\u002Freact\"\n\n\u002F\u002F Correct (legacy)\nimport { motion, AnimatePresence } from \"framer-motion\"\n\n\u002F\u002F Never mix both in the same project\n```\n\n---\n\n### Motion Tokens\n\n```ts\n\u002F\u002F motionTokens.ts\nexport const motionTokens = {\n  duration: {\n    fast: 0.18,\n    normal: 0.35,\n    slow: 0.6\n  },\n  \u002F\u002F Use these as the `ease` value inside a `transition` object:\n  \u002F\u002F transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}\n  easing: {\n    smooth: [0.22, 1, 0.36, 1] as [number, number, number, number],\n    sharp:  [0.4,  0, 0.2, 1] as [number, number, number, number]\n  },\n  distance: {\n    sm: 8,\n    md: 16,\n    lg: 24\n  }\n}\n```\n\nUsage example:\n\n```tsx\nimport { motionTokens } from \"@\u002Flib\u002FmotionTokens\"\n\n\u003Cmotion.div\n  initial={{ opacity: 0, y: motionTokens.distance.md }}\n  animate={{ opacity: 1, y: 0 }}\n  transition={{\n    duration: motionTokens.duration.normal,\n    ease: motionTokens.easing.smooth\n  }}\n\u002F>\n```\n\n---\n\n### Performance Rules\n\n**Safe**\n\n* transform\n* opacity\n\n**Avoid**\n\n* width \u002F height\n* top \u002F left\n\nRule: responsiveness > smoothness\n\n---\n\n### Device Adaptation\n\nThe heuristic combines CPU core count **and** available memory for a more reliable signal. `deviceMemory` is available on Chrome\u002FAndroid; the fallback covers Safari and Firefox.\n\n```ts\nconst isLowEnd =\n  typeof navigator !== \"undefined\" && (\n    \u002F\u002F Low memory (Chrome\u002FAndroid only; undefined elsewhere → treat as capable)\n    (navigator.deviceMemory !== undefined && navigator.deviceMemory \u003C= 2) ||\n    \u002F\u002F Few cores AND no memory API (covers Safari\u002FFirefox on weak hardware)\n    (navigator.deviceMemory === undefined && navigator.hardwareConcurrency \u003C= 4)\n  )\n\nconst duration = isLowEnd ? 0.2 : 0.4\n```\n\n---\n\n### Accessibility\n\n#### JS (useReducedMotion)\n\n```tsx\nimport { motion, useReducedMotion } from \"motion\u002Freact\"\n\nexport function FadeIn() {\n  const reduce = useReducedMotion()\n\n  return (\n    \u003Cmotion.div\n      initial={{ opacity: 0, y: reduce ? 0 : 24 }}\n      animate={{ opacity: 1, y: 0 }}\n    \u002F>\n  )\n}\n```\n\n#### CSS\n\n```css\n@media (prefers-reduced-motion: reduce) {\n  .motion-safe-transition {\n    transition: opacity 0.2s;\n  }\n\n  .motion-reduce-transform {\n    transform: none !important;\n  }\n}\n```\n\n#### Tailwind\n\n```html\n\u003Cdiv class=\"motion-safe:animate-fade motion-reduce:opacity-100\">\u003C\u002Fdiv>\n```\n\n---\n\n### Architecture & Patterns\n\n#### Core Patterns\n\n| Scenario | Pattern |\n|---|---|\n| Hover feedback | `whileHover` |\n| Tap \u002F press feedback | `whileTap` |\n| Reveal on scroll | `whileInView` |\n| Scroll-linked value | `useScroll` + `useTransform` |\n| Conditional mount\u002Funmount | `AnimatePresence` |\n| Small layout shifts (single element, \u003C ~300px change) | `layout` prop |\n| Large layout shifts or full-page reflows | Avoid `layout`; use CSS transitions or page-level routing instead |\n| Complex, imperative sequences | `useAnimate` |\n\n> **Why avoid `layout` on large containers?** Framer's layout animation uses `transform` to reconcile positions, but on elements that span the full viewport or trigger deep reflow, the measurement cost causes visible jank and CLS. Prefer CSS Grid\u002FFlexbox transitions or coordinate with `layoutId` on specific child elements only.\n\n#### Layout & Transitions\n\n* Shared element transitions → `layoutId` (must be unique per mounted instance)\n* Enter \u002F exit transitions → `AnimatePresence` (see `mode` guidance below)\n\n#### AnimatePresence `mode`\n\nAlways specify `mode` explicitly — the default (`\"sync\"`) runs enter and exit simultaneously, which causes visual overlap in most UI patterns.\n\n| `mode` | When to use |\n|---|---|\n| `\"wait\"` | Exit completes before enter starts. Use for **modals, toasts, page transitions**. |\n| `\"sync\"` (default) | Enter and exit overlap. Use only when overlap is intentional (e.g., crossfade carousels). |\n| `\"popLayout\"` | Exiting element is popped out of flow immediately; remaining items animate to fill. Use for **lists, tabs, dismissible cards**. |\n\n```tsx\n\u002F\u002F Modal — always use \"wait\"\n\u003CAnimatePresence mode=\"wait\">\n  {open && \u003CModal key=\"modal\" \u002F>}\n\u003C\u002FAnimatePresence>\n\n\u002F\u002F Dismissible list item — use \"popLayout\"\n\u003CAnimatePresence mode=\"popLayout\">\n  {items.map(item => \u003CCard key={item.id} \u002F>)}\n\u003C\u002FAnimatePresence>\n```\n\n---\n\n### Advanced Patterns (Concepts)\n\n* Parallax (scroll-linked transforms)\n* Scroll storytelling (sticky sections)\n* 3D tilt (pointer-based transforms)\n* Crossfade (shared `layoutId`)\n* Progressive reveal (clip-path)\n* Skeleton loading (looped opacity)\n* Micro-interactions (hover\u002Ftap feedback)\n* Spring system (physics-based motion)\n\n---\n\n### Modal Essentials\n\n* Focus trap\n* Escape close\n* Scroll lock\n* ARIA roles\n* Use `AnimatePresence mode=\"wait\"` so exit animation completes before the next modal enters\n\n#### Full Example\n\n```tsx\nimport React, { useEffect, useRef, useState } from \"react\"\nimport { motion, AnimatePresence } from \"motion\u002Freact\"\n\nfunction useFocusTrap(ref: React.RefObject\u003CHTMLDivElement | null>, active: boolean) {\n  useEffect(() => {\n    if (!active || !ref.current) return\n    const el = ref.current\n    const focusable = el.querySelectorAll\u003CHTMLElement>(\n      'button, [href], input, select, textarea, [tabindex]:not([tabindex=\"-1\"])'\n    )\n    const first = focusable[0]\n    const last  = focusable[focusable.length - 1]\n\n    function handleKey(e: KeyboardEvent) {\n      if (e.key !== \"Tab\") return\n      if (e.shiftKey && document.activeElement === first) {\n        e.preventDefault()\n        last?.focus()\n      } else if (!e.shiftKey && document.activeElement === last) {\n        e.preventDefault()\n        first?.focus()\n      }\n    }\n\n    el.addEventListener(\"keydown\", handleKey)\n    first?.focus()\n    return () => el.removeEventListener(\"keydown\", handleKey)\n  }, [active, ref])\n}\n\nfunction useScrollLock(active: boolean) {\n  useEffect(() => {\n    if (!active) return\n    const prev = document.body.style.overflow\n    document.body.style.overflow = \"hidden\"\n    return () => { document.body.style.overflow = prev }\n  }, [active])\n}\n\nfunction Modal({ open, closeModal }: { open: boolean; closeModal: () => void }) {\n  const ref = useRef\u003CHTMLDivElement>(null)\n\n  useFocusTrap(ref, open)\n  useScrollLock(open)\n\n  useEffect(() => {\n    function onKey(e: KeyboardEvent) {\n      if (e.key === \"Escape\") closeModal()\n    }\n    if (open) window.addEventListener(\"keydown\", onKey)\n    return () => window.removeEventListener(\"keydown\", onKey)\n  }, [open, closeModal])\n\n  return (\n    \u002F\u002F mode=\"wait\" ensures exit animation finishes before any new modal enters\n    \u003CAnimatePresence mode=\"wait\">\n      {open && (\n        \u003Cmotion.div\n          role=\"dialog\"\n          aria-modal=\"true\"\n          aria-labelledby=\"modal-title\"\n          initial={{ opacity: 0 }}\n          animate={{ opacity: 1 }}\n          exit={{ opacity: 0 }}\n          transition={{ duration: 0.2 }}\n          className=\"fixed inset-0 flex items-center justify-center bg-black\u002F40\"\n        >\n          \u003Cmotion.div\n            ref={ref}\n            initial={{ scale: 0.95, opacity: 0 }}\n            animate={{ scale: 1,    opacity: 1 }}\n            exit={{    scale: 0.95, opacity: 0 }}\n            transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}\n            className=\"bg-white p-6 rounded\"\n          >\n            \u003Ch2 id=\"modal-title\">Dialog Title\u003C\u002Fh2>\n            \u003Cbutton onClick={closeModal}>Close\u003C\u002Fbutton>\n          \u003C\u002Fmotion.div>\n        \u003C\u002Fmotion.div>\n      )}\n    \u003C\u002FAnimatePresence>\n  )\n}\n\nexport function Example() {\n  const [open, setOpen] = useState(false)\n\n  return (\n    \u003C>\n      \u003Cbutton onClick={() => setOpen(true)}>Open\u003C\u002Fbutton>\n      \u003CModal open={open} closeModal={() => setOpen(false)} \u002F>\n    \u003C\u002F>\n  )\n}\n```\n\n---\n\n### SSR Safety\n\n* Match initial states between server and client renders\n* Avoid implicit animation origins (always set `initial` explicitly)\n* Wrap motion components in `\"use client\"` in Next.js App Router\n\n---\n\n### Debugging\n\nCheck:\n\n* Wrong import (mixing `motion\u002Freact` and `framer-motion`)\n* Missing `\"use client\"` directive in Next.js App Router\n* Missing `key` prop on `AnimatePresence` children\n* Hydration mismatch (initial state differs between SSR and client)\n* `layout` prop misuse on large containers causing reflow jank\n* State-driven animation not triggering (check dependency arrays)\n\n---\n\n### QA\n\n* No CLS\n* Keyboard works\n* Focus trapped in modals\n* ARIA roles correct (`role=\"dialog\"`, `aria-modal=\"true\"`)\n* Reduced motion respected (`useReducedMotion` + CSS media query)\n* No hydration warnings in Next.js\n* Animations stop cleanly on unmount (no memory leaks)\n* `AnimatePresence mode` set explicitly on all usage sites\n\n---\n\n### Anti-Patterns\n\n* Animating layout properties (`width`, `height`, `top`, `left`)\n* Infinite animations without purpose (always ask: what state does this communicate?)\n* Over-staggering lists (keep `staggerChildren` ≤ 0.1s; beyond that it feels slow)\n* Ignoring reduced motion preferences\n* Using `layout` on large or full-viewport containers\n* Omitting `mode` on `AnimatePresence` (default `\"sync\"` causes visual overlap)\n* Using motion purely for decoration\n\n---\n\n### Philosophy\n\nMotion is interaction design.\n\n---\n\n### Final Rule\n\n> If motion does not improve UX → remove it.\n\n---\n\n## Examples\n\n### Button Interaction\n\n```tsx\nimport { motion } from \"motion\u002Freact\"\n\nexport function Button() {\n  return (\n    \u003Cmotion.button\n      whileHover={{ scale: 1.02 }}\n      whileTap={{ scale: 0.97 }}\n      transition={{ duration: 0.15, ease: [0.4, 0, 0.2, 1] }}\n    >\n      Click me\n    \u003C\u002Fmotion.button>\n  )\n}\n```\n\n---\n\n### Reduced Motion Example\n\n```tsx\nimport { motion, useReducedMotion } from \"motion\u002Freact\"\n\nexport function FadeIn() {\n  const reduce = useReducedMotion()\n\n  return (\n    \u003Cmotion.div\n      initial={{ opacity: 0, y: reduce ? 0 : 24 }}\n      animate={{ opacity: 1, y: 0 }}\n      transition={{ duration: reduce ? 0.1 : 0.35, ease: [0.22, 1, 0.36, 1] }}\n    \u002F>\n  )\n}\n```\n\n---\n\n### Stagger List\n\n```tsx\nimport { motion } from \"motion\u002Freact\"\n\nconst container = {\n  hidden: {},\n  visible: {\n    transition: { staggerChildren: 0.08 } \u002F\u002F keep ≤ 0.1s to avoid sluggishness\n  }\n}\n\nconst item = {\n  hidden:  { opacity: 0, y: 10 },\n  visible: { opacity: 1, y: 0,  transition: { duration: 0.3, ease: [0.22, 1, 0.36, 1] } }\n}\n\nexport function List() {\n  return (\n    \u003Cmotion.ul variants={container} initial=\"hidden\" animate=\"visible\">\n      {[1, 2, 3].map(i => (\n        \u003Cmotion.li key={i} variants={item}>Item {i}\u003C\u002Fmotion.li>\n      ))}\n    \u003C\u002Fmotion.ul>\n  )\n}\n```\n\n---\n\n### Modal with AnimatePresence\n\n```tsx\nimport { motion, AnimatePresence } from \"motion\u002Freact\"\n\nexport function Modal({ open }: { open: boolean }) {\n  return (\n    \u003CAnimatePresence mode=\"wait\">\n      {open && (\n        \u003Cmotion.div\n          initial={{ opacity: 0, scale: 0.95 }}\n          animate={{ opacity: 1, scale: 1    }}\n          exit={{    opacity: 0, scale: 0.95 }}\n          transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}\n        \u002F>\n      )}\n    \u003C\u002FAnimatePresence>\n  )\n}\n```\n\n---\n\n### Scroll Parallax\n\n```tsx\nimport { useScroll, useTransform, motion } from \"motion\u002Freact\"\n\nexport function Parallax() {\n  const { scrollYProgress } = useScroll()\n  const y = useTransform(scrollYProgress, [0, 1], [0, -80])\n\n  return \u003Cmotion.div style={{ y }} \u002F>\n}\n```\n\n---\n\n### Skeleton Loading\n\n```tsx\nimport { motion } from \"motion\u002Freact\"\n\nexport function Skeleton() {\n  return (\n    \u003Cmotion.div\n      className=\"bg-gray-200 h-6 w-full rounded\"\n      animate={{ opacity: [0.5, 1, 0.5] }}\n      transition={{\n        duration: 1.5,       \u002F\u002F comfortable pulse — was missing, caused fast flash\n        repeat: Infinity,\n        ease: \"easeInOut\"\n      }}\n    \u002F>\n  )\n}\n```\n\n---\n\n### Shared Layout (Crossfade)\n\n```tsx\nimport { motion } from \"motion\u002Freact\"\n\n\u002F\u002F layoutId must be unique per mounted instance.\n\u002F\u002F If multiple instances can exist simultaneously, append a unique id:\n\u002F\u002F layoutId={`shared-${item.id}`}\nexport function Shared() {\n  return \u003Cmotion.div layoutId=\"shared\" \u002F>\n}\n```\n","# Motion System v4.2\n\nProduction-ready UI motion system for React \u002F Next.js.\n\nFocused on **performance, accessibility, and usability** — not decoration.\n\n## When to Use\n\nUse this motion system when motion:\n\n* Guides attention (e.g., onboarding, key actions)\n* Communicates state (loading, success, error, transitions)\n* Preserves spatial continuity (layout changes, navigation)\n\n### Appropriate Scenarios\n\n* Interactive components (buttons, modals, menus)\n* State transitions (loading → loaded, open → closed)\n* Navigation and layout continuity (shared elements, crossfade)\n\n### Considerations\n\n* **Accessibility**: Always support reduced motion\n* **Device adaptation**: Adjust for low-end devices\n* **Performance trade-offs**: Prefer responsiveness over visual smoothness\n\n### Avoid Using Motion When\n\n* It is purely decorative\n* It reduces usability or clarity\n* It impacts performance negatively\n\n---\n\n## How It Works\n\n### Core Principle\n\nMotion must:\n\n* Guide attention\n* Communicate state\n* Preserve spatial continuity\n\nIf it does none → remove it.\n\n---\n\n### Installation\n\n```bash\nnpm install motion\n```\n\n---\n\n### Version\n\n* `motion\u002Freact` - default for current Motion for React projects (package: `motion`)\n* `framer-motion` - legacy import path for projects that still depend on Framer Motion\n\n**Do not mix.** Mixing causes conflicting internal schedulers and broken `AnimatePresence` contexts — components from one package will not coordinate exit animations with components from the other.\n\nTo check which version your project uses:\n\n```bash\ncat package.json | grep -E '\"motion\"|\"framer-motion\"'\n```\n\nAlways import from one source consistently:\n\n```ts\n\u002F\u002F Correct (modern)\nimport { motion, AnimatePresence } from \"motion\u002Freact\"\n\n\u002F\u002F Correct (legacy)\nimport { motion, AnimatePresence } from \"framer-motion\"\n\n\u002F\u002F Never mix both in the same project\n```\n\n---\n\n### Motion Tokens\n\n```ts\n\u002F\u002F motionTokens.ts\nexport const motionTokens = {\n  duration: {\n    fast: 0.18,\n    normal: 0.35,\n    slow: 0.6\n  },\n  \u002F\u002F Use these as the `ease` value inside a `transition` object:\n  \u002F\u002F transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}\n  easing: {\n    smooth: [0.22, 1, 0.36, 1] as [number, number, number, number],\n    sharp:  [0.4,  0, 0.2, 1] as [number, number, number, number]\n  },\n  distance: {\n    sm: 8,\n    md: 16,\n    lg: 24\n  }\n}\n```\n\nUsage example:\n\n```tsx\nimport { motionTokens } from \"@\u002Flib\u002FmotionTokens\"\n\n\u003Cmotion.div\n  initial={{ opacity: 0, y: motionTokens.distance.md }}\n  animate={{ opacity: 1, y: 0 }}\n  transition={{\n    duration: motionTokens.duration.normal,\n    ease: motionTokens.easing.smooth\n  }}\n\u002F>\n```\n\n---\n\n### Performance Rules\n\n**Safe**\n\n* transform\n* opacity\n\n**Avoid**\n\n* width \u002F height\n* top \u002F left\n\nRule: responsiveness > smoothness\n\n---\n\n### Device Adaptation\n\nThe heuristic combines CPU core count **and** available memory for a more reliable signal. `deviceMemory` is available on Chrome\u002FAndroid; the fallback covers Safari and Firefox.\n\n```ts\nconst isLowEnd =\n  typeof navigator !== \"undefined\" && (\n    \u002F\u002F Low memory (Chrome\u002FAndroid only; undefined elsewhere → treat as capable)\n    (navigator.deviceMemory !== undefined && navigator.deviceMemory \u003C= 2) ||\n    \u002F\u002F Few cores AND no memory API (covers Safari\u002FFirefox on weak hardware)\n    (navigator.deviceMemory === undefined && navigator.hardwareConcurrency \u003C= 4)\n  )\n\nconst duration = isLowEnd ? 0.2 : 0.4\n```\n\n---\n\n### Accessibility\n\n#### JS (useReducedMotion)\n\n```tsx\nimport { motion, useReducedMotion } from \"motion\u002Freact\"\n\nexport function FadeIn() {\n  const reduce = useReducedMotion()\n\n  return (\n    \u003Cmotion.div\n      initial={{ opacity: 0, y: reduce ? 0 : 24 }}\n      animate={{ opacity: 1, y: 0 }}\n    \u002F>\n  )\n}\n```\n\n#### CSS\n\n```css\n@media (prefers-reduced-motion: reduce) {\n  .motion-safe-transition {\n    transition: opacity 0.2s;\n  }\n\n  .motion-reduce-transform {\n    transform: none !important;\n  }\n}\n```\n\n#### Tailwind\n\n```html\n\u003Cdiv class=\"motion-safe:animate-fade motion-reduce:opacity-100\">\u003C\u002Fdiv>\n```\n\n---\n\n### Architecture & Patterns\n\n#### Core Patterns\n\n| Scenario | Pattern |\n|---|---|\n| Hover feedback | `whileHover` |\n| Tap \u002F press feedback | `whileTap` |\n| Reveal on scroll | `whileInView` |\n| Scroll-linked value | `useScroll` + `useTransform` |\n| Conditional mount\u002Funmount | `AnimatePresence` |\n| Small layout shifts (single element, \u003C ~300px change) | `layout` prop |\n| Large layout shifts or full-page reflows | Avoid `layout`; use CSS transitions or page-level routing instead |\n| Complex, imperative sequences | `useAnimate` |\n\n> **Why avoid `layout` on large containers?** Framer's layout animation uses `transform` to reconcile positions, but on elements that span the full viewport or trigger deep reflow, the measurement cost causes visible jank and CLS. Prefer CSS Grid\u002FFlexbox transitions or coordinate with `layoutId` on specific child elements only.\n\n#### Layout & Transitions\n\n* Shared element transitions → `layoutId` (must be unique per mounted instance)\n* Enter \u002F exit transitions → `AnimatePresence` (see `mode` guidance below)\n\n#### AnimatePresence `mode`\n\nAlways specify `mode` explicitly — the default (`\"sync\"`) runs enter and exit simultaneously, which causes visual overlap in most UI patterns.\n\n| `mode` | When to use |\n|---|---|\n| `\"wait\"` | Exit completes before enter starts. Use for **modals, toasts, page transitions**. |\n| `\"sync\"` (default) | Enter and exit overlap. Use only when overlap is intentional (e.g., crossfade carousels). |\n| `\"popLayout\"` | Exiting element is popped out of flow immediately; remaining items animate to fill. Use for **lists, tabs, dismissible cards**. |\n\n```tsx\n\u002F\u002F Modal — always use \"wait\"\n\u003CAnimatePresence mode=\"wait\">\n  {open && \u003CModal key=\"modal\" \u002F>}\n\u003C\u002FAnimatePresence>\n\n\u002F\u002F Dismissible list item — use \"popLayout\"\n\u003CAnimatePresence mode=\"popLayout\">\n  {items.map(item => \u003CCard key={item.id} \u002F>)}\n\u003C\u002FAnimatePresence>\n```\n\n---\n\n### Advanced Patterns (Concepts)\n\n* Parallax (scroll-linked transforms)\n* Scroll storytelling (sticky sections)\n* 3D tilt (pointer-based transforms)\n* Crossfade (shared `layoutId`)\n* Progressive reveal (clip-path)\n* Skeleton loading (looped opacity)\n* Micro-interactions (hover\u002Ftap feedback)\n* Spring system (physics-based motion)\n\n---\n\n### Modal Essentials\n\n* Focus trap\n* Escape close\n* Scroll lock\n* ARIA roles\n* Use `AnimatePresence mode=\"wait\"` so exit animation completes before the next modal enters\n\n#### Full Example\n\n```tsx\nimport React, { useEffect, useRef, useState } from \"react\"\nimport { motion, AnimatePresence } from \"motion\u002Freact\"\n\nfunction useFocusTrap(ref: React.RefObject\u003CHTMLDivElement | null>, active: boolean) {\n  useEffect(() => {\n    if (!active || !ref.current) return\n    const el = ref.current\n    const focusable = el.querySelectorAll\u003CHTMLElement>(\n      'button, [href], input, select, textarea, [tabindex]:not([tabindex=\"-1\"])'\n    )\n    const first = focusable[0]\n    const last  = focusable[focusable.length - 1]\n\n    function handleKey(e: KeyboardEvent) {\n      if (e.key !== \"Tab\") return\n      if (e.shiftKey && document.activeElement === first) {\n        e.preventDefault()\n        last?.focus()\n      } else if (!e.shiftKey && document.activeElement === last) {\n        e.preventDefault()\n        first?.focus()\n      }\n    }\n\n    el.addEventListener(\"keydown\", handleKey)\n    first?.focus()\n    return () => el.removeEventListener(\"keydown\", handleKey)\n  }, [active, ref])\n}\n\nfunction useScrollLock(active: boolean) {\n  useEffect(() => {\n    if (!active) return\n    const prev = document.body.style.overflow\n    document.body.style.overflow = \"hidden\"\n    return () => { document.body.style.overflow = prev }\n  }, [active])\n}\n\nfunction Modal({ open, closeModal }: { open: boolean; closeModal: () => void }) {\n  const ref = useRef\u003CHTMLDivElement>(null)\n\n  useFocusTrap(ref, open)\n  useScrollLock(open)\n\n  useEffect(() => {\n    function onKey(e: KeyboardEvent) {\n      if (e.key === \"Escape\") closeModal()\n    }\n    if (open) window.addEventListener(\"keydown\", onKey)\n    return () => window.removeEventListener(\"keydown\", onKey)\n  }, [open, closeModal])\n\n  return (\n    \u002F\u002F mode=\"wait\" ensures exit animation finishes before any new modal enters\n    \u003CAnimatePresence mode=\"wait\">\n      {open && (\n        \u003Cmotion.div\n          role=\"dialog\"\n          aria-modal=\"true\"\n          aria-labelledby=\"modal-title\"\n          initial={{ opacity: 0 }}\n          animate={{ opacity: 1 }}\n          exit={{ opacity: 0 }}\n          transition={{ duration: 0.2 }}\n          className=\"fixed inset-0 flex items-center justify-center bg-black\u002F40\"\n        >\n          \u003Cmotion.div\n            ref={ref}\n            initial={{ scale: 0.95, opacity: 0 }}\n            animate={{ scale: 1,    opacity: 1 }}\n            exit={{    scale: 0.95, opacity: 0 }}\n            transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}\n            className=\"bg-white p-6 rounded\"\n          >\n            \u003Ch2 id=\"modal-title\">Dialog Title\u003C\u002Fh2>\n            \u003Cbutton onClick={closeModal}>Close\u003C\u002Fbutton>\n          \u003C\u002Fmotion.div>\n        \u003C\u002Fmotion.div>\n      )}\n    \u003C\u002FAnimatePresence>\n  )\n}\n\nexport function Example() {\n  const [open, setOpen] = useState(false)\n\n  return (\n    \u003C>\n      \u003Cbutton onClick={() => setOpen(true)}>Open\u003C\u002Fbutton>\n      \u003CModal open={open} closeModal={() => setOpen(false)} \u002F>\n    \u003C\u002F>\n  )\n}\n```\n\n---\n\n### SSR Safety\n\n* Match initial states between server and client renders\n* Avoid implicit animation origins (always set `initial` explicitly)\n* Wrap motion components in `\"use client\"` in Next.js App Router\n\n---\n\n### Debugging\n\nCheck:\n\n* Wrong import (mixing `motion\u002Freact` and `framer-motion`)\n* Missing `\"use client\"` directive in Next.js App Router\n* Missing `key` prop on `AnimatePresence` children\n* Hydration mismatch (initial state differs between SSR and client)\n* `layout` prop misuse on large containers causing reflow jank\n* State-driven animation not triggering (check dependency arrays)\n\n---\n\n### QA\n\n* No CLS\n* Keyboard works\n* Focus trapped in modals\n* ARIA roles correct (`role=\"dialog\"`, `aria-modal=\"true\"`)\n* Reduced motion respected (`useReducedMotion` + CSS media query)\n* No hydration warnings in Next.js\n* Animations stop cleanly on unmount (no memory leaks)\n* `AnimatePresence mode` set explicitly on all usage sites\n\n---\n\n### Anti-Patterns\n\n* Animating layout properties (`width`, `height`, `top`, `left`)\n* Infinite animations without purpose (always ask: what state does this communicate?)\n* Over-staggering lists (keep `staggerChildren` ≤ 0.1s; beyond that it feels slow)\n* Ignoring reduced motion preferences\n* Using `layout` on large or full-viewport containers\n* Omitting `mode` on `AnimatePresence` (default `\"sync\"` causes visual overlap)\n* Using motion purely for decoration\n\n---\n\n### Philosophy\n\nMotion is interaction design.\n\n---\n\n### Final Rule\n\n> If motion does not improve UX → remove it.\n\n---\n\n## Examples\n\n### Button Interaction\n\n```tsx\nimport { motion } from \"motion\u002Freact\"\n\nexport function Button() {\n  return (\n    \u003Cmotion.button\n      whileHover={{ scale: 1.02 }}\n      whileTap={{ scale: 0.97 }}\n      transition={{ duration: 0.15, ease: [0.4, 0, 0.2, 1] }}\n    >\n      Click me\n    \u003C\u002Fmotion.button>\n  )\n}\n```\n\n---\n\n### Reduced Motion Example\n\n```tsx\nimport { motion, useReducedMotion } from \"motion\u002Freact\"\n\nexport function FadeIn() {\n  const reduce = useReducedMotion()\n\n  return (\n    \u003Cmotion.div\n      initial={{ opacity: 0, y: reduce ? 0 : 24 }}\n      animate={{ opacity: 1, y: 0 }}\n      transition={{ duration: reduce ? 0.1 : 0.35, ease: [0.22, 1, 0.36, 1] }}\n    \u002F>\n  )\n}\n```\n\n---\n\n### Stagger List\n\n```tsx\nimport { motion } from \"motion\u002Freact\"\n\nconst container = {\n  hidden: {},\n  visible: {\n    transition: { staggerChildren: 0.08 } \u002F\u002F keep ≤ 0.1s to avoid sluggishness\n  }\n}\n\nconst item = {\n  hidden:  { opacity: 0, y: 10 },\n  visible: { opacity: 1, y: 0,  transition: { duration: 0.3, ease: [0.22, 1, 0.36, 1] } }\n}\n\nexport function List() {\n  return (\n    \u003Cmotion.ul variants={container} initial=\"hidden\" animate=\"visible\">\n      {[1, 2, 3].map(i => (\n        \u003Cmotion.li key={i} variants={item}>Item {i}\u003C\u002Fmotion.li>\n      ))}\n    \u003C\u002Fmotion.ul>\n  )\n}\n```\n\n---\n\n### Modal with AnimatePresence\n\n```tsx\nimport { motion, AnimatePresence } from \"motion\u002Freact\"\n\nexport function Modal({ open }: { open: boolean }) {\n  return (\n    \u003CAnimatePresence mode=\"wait\">\n      {open && (\n        \u003Cmotion.div\n          initial={{ opacity: 0, scale: 0.95 }}\n          animate={{ opacity: 1, scale: 1    }}\n          exit={{    opacity: 0, scale: 0.95 }}\n          transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}\n        \u002F>\n      )}\n    \u003C\u002FAnimatePresence>\n  )\n}\n```\n\n---\n\n### Scroll Parallax\n\n```tsx\nimport { useScroll, useTransform, motion } from \"motion\u002Freact\"\n\nexport function Parallax() {\n  const { scrollYProgress } = useScroll()\n  const y = useTransform(scrollYProgress, [0, 1], [0, -80])\n\n  return \u003Cmotion.div style={{ y }} \u002F>\n}\n```\n\n---\n\n### Skeleton Loading\n\n```tsx\nimport { motion } from \"motion\u002Freact\"\n\nexport function Skeleton() {\n  return (\n    \u003Cmotion.div\n      className=\"bg-gray-200 h-6 w-full rounded\"\n      animate={{ opacity: [0.5, 1, 0.5] }}\n      transition={{\n        duration: 1.5,       \u002F\u002F comfortable pulse — was missing, caused fast flash\n        repeat: Infinity,\n        ease: \"easeInOut\"\n      }}\n    \u002F>\n  )\n}\n```\n\n---\n\n### Shared Layout (Crossfade)\n\n```tsx\nimport { motion } from \"motion\u002Freact\"\n\n\u002F\u002F layoutId must be unique per mounted instance.\n\u002F\u002F If multiple instances can exist simultaneously, append a unique id:\n\u002F\u002F layoutId={`shared-${item.id}`}\nexport function Shared() {\n  return \u003Cmotion.div layoutId=\"shared\" \u002F>\n}\n```\n",{"name":5,"metadata":24,"description":7},{"origin":25},"HCP","main","c9103dbad48ef3005f163584d0f2abd4591217f6","skills\u002Fecc-motion-ui",1,"https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production","https:\u002F\u002Fgithub.com\u002F503496348-ops","https:\u002F\u002F503496348-ops.github.io\u002Fatomcollide-product-matrix\u002F#tree","元素碰撞-AtomCollide-AI 智能体实验室 测试人专属成长社群 正式招募\r\n我们的目标很纯粹：连接每一位测试工程师\u002FAI使用探索与爱好者，让你在这里既能扎实打磨技术硬实力，也能打通职业晋升的新通路，这是一个专注于AI领域的开源组","2026-07-30 00:35:42",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add 503496348-ops\u002Fmischief-production --skill motion-ui",{"tool":41,"command":42},"bunx","bunx skills add 503496348-ops\u002Fmischief-production --skill motion-ui",{"tool":44,"command":45},"pnpm","pnpm dlx skills add 503496348-ops\u002Fmischief-production --skill motion-ui","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production\u002Fblob\u002Fmain\u002Fskills\u002Fecc-motion-ui\u002FSKILL.md",true,[],[50,57,64,71,78,85],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M77YG7NPZHE751W9QGK3H9ED","writing-skills","Use when creating new skills, editing existing skills, or verifying skills work before deployment","https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production\u002Fblob\u002Fmain\u002Fskills\u002Fsp-writing-skills\u002FSKILL.md",[],[],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M77YG4HPYH0GJP974DZ6KCPQ","writing-plans","Use when you have a spec or requirements for a multi-step task, before touching code","https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production\u002Fblob\u002Fmain\u002Fskills\u002Fsp-writing-plans\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M77YFZW1FZ1GVC5C89NPE5M8","verification-before-completion","Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always","https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production\u002Fblob\u002Fmain\u002Fskills\u002Fsp-verification-before-completion\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M77YFVPWANT5VE5GWBTKHPA2","using-智械工程","Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions","https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production\u002Fblob\u002Fmain\u002Fskills\u002Fsp-using-superpowers\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M77YFQJAW5PX3QYSBCD3B24S","using-git-worktrees","Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback","https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production\u002Fblob\u002Fmain\u002Fskills\u002Fsp-using-git-worktrees\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M77YFMSTB70VX8W2QHNJWYB0","test-driven-development","Use when implementing any feature or bugfix, before writing implementation code","https:\u002F\u002Fgithub.com\u002F503496348-ops\u002Fmischief-production\u002Fblob\u002Fmain\u002Fskills\u002Fsp-test-driven-development\u002FSKILL.md",[],[]]