Principles

• Every pattern imports from motion-foundations. No raw numbers.
• Every conditional render is wrapped in AnimatePresence with a key.
• Exit animations are always defined alongside enter animations — never as an afterthought.
• layout is used only for small, isolated shifts. Large subtrees get explicit transforms.

Rules

1. Always wrap conditional renders in AnimatePresence with a key on the direct child. Without a key, exit animations never fire.
2. Always define exit when defining initial + animate. An animation without an exit is incomplete.
3. Use mode="wait" on page transitions. Enter must not start until exit completes.
4. Never use layout on subtrees with more than ~5 children or deeply nested DOM. Use explicit x/y transforms instead.
5. Stagger interval must stay between 0.05s and 0.10s. Below feels mechanical; above feels sluggish.
6. Modals must always include: focus trap, Escape-key close, scroll lock, role="dialog", aria-modal="true".
7. Scroll reveals use viewport={{ once: true }}. Repeating on scroll-out is distracting, not informative.
8. All token values are imported from motion-foundations. No inline numbers.

Decision Guidance

Choosing the right pattern

When to use mode="wait" vs mode="sync"

Core Concepts

AnimatePresence contract

Three things must always be true:

1. AnimatePresence wraps the conditional
2. The direct child has a key
3. The child has an exit prop

Miss any one of these and the exit animation silently fails.

layout vs layoutId

• layout — animates the element's own size/position change in place
• layoutId — links two separate elements, crossfading between them across renders

Use layout="position" on text inside an expanding container to prevent text reflow from animating.

Code Examples

Button feedback

"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"

<motion.button
  whileHover={{ scale: motionTokens.scale.pop }}
  whileTap={{ scale: motionTokens.scale.press }}

…

santa-method

通过双评审智能体对结果进行对抗式校验，提升输出发布前的可靠性

motion-foundations

为 React/Next.js 动效系统建立规范基座，统一令牌、弹簧预设、性能与无障碍规则。