Motion must do at least one of the following or it must be removed:

• Guide attention
• Communicate state
• Preserve spatial continuity

Responsiveness always outranks smoothness. A 60 fps animation that causes input delay is worse than no animation.

Rules

These are non-negotiable. They apply to every component in the system.

1. Use motion/react only. Never import from framer-motion. Never mix the two in the same tree.
2. initial must match server output. If the server renders opacity: 1, the initial prop must also be opacity: 1. No exceptions.
3. Reduced motion overrides everything. When useReducedMotion() returns true or prefersReduced is true, all transforms are disabled. Opacity-only fades at ≤ 0.2s are the only permitted fallback.
4. Never animate layout properties. width, height, top, left, margin, padding are banned from animate. Use transform and opacity only.
5. All token values come from motionTokens. Hardcoded durations and easings in component files are forbidden.
6. All spring configs come from the springs map. Inline stiffness/damping values are forbidden.
7. "use client" is required on every file that imports from motion/react.
8. Never read window or navigator at module level. Always guard with typeof window !== "undefined".

Decision Guidance

Choosing a duration

Choosing a spring

When to disable animation entirely

Disable (make shouldAnimate() return false) when:

• prefersReduced is true
• isLowEnd is true and the animation is non-essential
• The element is off-screen and will never enter the viewport
• The animation is purely decorative with no UX purpose

Core Concepts

Token system

// lib/motion-tokens.ts
export const motionTokens = {
  duration: {
    instant: 0.08,
    fast:    0.18,
    normal:  0.35,
    slow:    0.6,
    crawl:   1.0,
  },
  easing: {
    smooth: [0.22, 1, 0.36, 1],
    sharp:  [0.4, 0, 0.2, 1],
    bounce: [0.34, 1.56, 0.64, 1],
    linear: [0, 0, 1, 1],
  },
  distance: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 48,
  },
  scale: {
    subtle: 0.98,
    press:  0.95,
    pop:    1.04,
  },
}

export const springs = {
  snappy:  { type: "spring", stiffness: 300, damping: 30 },
  gentle:  { type: "spring", stiffness: 120, damping: 14 },
  bouncy:  { type: "spring", stiffness: 400, damping: 10 },

…

motion-patterns

提供适用于 React/Next.js 的高质量动画模式，快速实现常见交互动效。