motion-patterns

Motion Patterns

最も一般的な UI アニメーションニーズに対するコピペ可能なパターン。 ここにあるすべてのパターンは motion-foundations のトークンとスプリングをベースに構築されています。 新しい duration や easing の値を定義せず、インポートしてください。

いつ有効にするか

• ボタン、カード、モーダル、トースト通知をアニメーションさせる場合
• スタガー効果でリストの要素を順に表示する場合
• Next.js App Router でページトランジションを構築する場合
• 条件付きコンテンツに出現・終了アニメーションを追加する場合
• スクロールに応じた表示、スクロール連動プログレス、スティッキーなストーリーセクションを実装する場合
• 展開カード、アコーディオン、共有要素トランジションを構築する場合

出力内容

このスキルは以下を生成します:

• アクセシブルで SSR セーフな、すべての標準 UI コンポーネント向けアニメーション
• 正しい終了動作を持つ AnimatePresence でラップされた条件付きレンダリング
• Next.js App Router 用のページトランジションラッパーコンポーネント
• useScroll + useTransform を使用したスクロール表示・スクロール連動パターン
• 展開およびクロスフェード要素のためのレイアウトアニメーションパターン（layout、layoutId）

原則

• すべてのパターンは motion-foundations からインポートします。生の数値は使用しません。
• すべての条件付きレンダリングは AnimatePresence でラップし、key を指定します。
• 終了アニメーションは常に出現アニメーションと一緒に定義し、後付けにしてはいけません。
• layout は小さく隔離された動きにのみ使用します。大きなサブツリーには明示的なトランスフォームを使用します。

ルール

1. 常に条件付きレンダリングを AnimatePresence でラップし、直接の子要素に key を付与します。 key がないと終了アニメーションは決して実行されません。
2. initial + animate を定義するときは常に exit も定義します。 終了のないアニメーションは不完全です。
3. ページトランジションには mode="wait" を使用します。 終了が完了するまで出現を開始しないようにします。
4. 子要素が約5個以上、または DOM が深くネストされているサブツリーでは layout を使用しないでください。 代わりに明示的な x/y トランスフォームを使用します。
5. スタガー間隔は必ず 0.05s ～ 0.10s の範囲に収めます。 これより短いと機械的に、長いと緩慢に見えます。
6. モーダルには常に以下を含める必要があります: フォーカストラップ、Escape キーでの閉じる操作、スクロールロック、role="dialog"、aria-modal="true"。
7. スクロールリビールは viewport={{ once: true }} を使用します。 スクロールアウト時に繰り返すと、情報的ではなく邪魔になります。
8. すべてのトークン値は motion-foundations からインポートされます。 インラインの数値は使用しません。

判断ガイドライン

適切なパターンの選択

状況	パターン
要素が表示 / 非表示になる	AnimatePresence
アイテムのリストが順に読み込まれる	スタガーバリアント
ルート間を移動する	ページトランジションラッパー
要素がその場でサイズを変える	layout プロパティ
同じ要素がページコンテキスト間を移動する	layoutId
要素がビューポートにスクロールされたときに入る	whileInView
値がスクロール位置に連動する	useScroll + useTransform

mode="wait" と mode="sync" の使い分け

モード	使用時
wait	ページトランジション、コンテンツの入れ替え（一度に一つ）
sync	積み上げ通知、リストアイテム（重なりが許容される場合）
popLayout	リフローするリストからアイテムが削除される場合

コアコンセプト

AnimatePresence 契約

以下の3つが常に真である必要があります:

1. AnimatePresence が条件をラップしている
2. 直接の子要素が key を持っている
3. 子要素が exit プロパティを持っている

このうちどれか一つでも欠けると、終了アニメーションは静かに失敗します。

layout と layoutId の違い

• layout — 要素自身のサイズ/位置の変化をその場でアニメーションする
• layoutId — 2つの別々の要素をリンクし、レンダリング間でクロスフェードする

拡大するコンテナ内のテキストには layout="position" を使用して、テキストのリフローがアニメーションしないようにします。

コード例

ボタンフィードバック

"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 }}
  transition={springs.snappy}
/>

スタガーリスト

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

const container = {
  hidden: {},
  visible: {
    transition: {
      staggerChildren: 0.08,   // 0.05–0.10 のルール内
      delayChildren: 0.1,
    },
  },
}

const item = {
  hidden:  { opacity: 0, y: motionTokens.distance.md },
  visible: { opacity: 1, y: 0, transition: springs.gentle },
}

<motion.ul variants={container} initial="hidden" animate="visible">
  {items.map((i) => (
    <motion.li key={i.id} variants={item} />
  ))}
</motion.ul>

モーダル

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

// 呼び出し側でラップ:
// <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>

export function Modal({ onClose }: { onClose: () => void }) {
  return (
    <>
      {/* オーバーレイ */}
      <motion.div
        className="fixed inset-0 bg-black/50"
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        exit={{ opacity: 0 }}
        onClick={onClose}
      />

      {/* パネル — アクセシビリティ要件: フォーカストラップ、Escape キーで閉じる、
          スクロールロック、role="dialog"、aria-modal="true" */}
      <motion.div
        role="dialog"
        aria-modal="true"
        className="fixed inset-x-4 top-1/2 -translate-y-1/2 rounded-xl bg-white p-6"
        initial={{
          opacity: 0,
          scale: motionTokens.scale.press,
          y: motionTokens.distance.sm,
        }}
        animate={{ opacity: 1, scale: 1, y: 0 }}
        exit={{
          opacity: 0,
          scale: motionTokens.scale.press,
          y: motionTokens.distance.sm,
        }}
        transition={springs.gentle}
      />
    </>
  )
}

トーストスタック

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

<AnimatePresence mode="sync">
  {toasts.map((t) => (
    <motion.div
      key={t.id}
      layout
      initial={{
        opacity: 0,
        x: motionTokens.distance.xl,
        scale: motionTokens.scale.subtle,
      }}
      animate={{ opacity: 1, x: 0, scale: 1 }}
      exit={{
        opacity: 0,
        x: motionTokens.distance.xl,
        scale: motionTokens.scale.subtle,
      }}
      transition={springs.snappy}
    />
  ))}
</AnimatePresence>

ページトランジション（Next.js App Router）

// components/page-transition.tsx
"use client"
import { motion, AnimatePresence } from "motion/react"
import { usePathname } from "next/navigation"
import { motionTokens } from "@/lib/motion-tokens"

const variants = {
  initial: { opacity: 0, y: motionTokens.distance.sm },
  enter:   { opacity: 1, y: 0 },
  exit:    { opacity: 0, y: -motionTokens.distance.sm },
}

export function PageTransition({ children }: { children: React.ReactNode }) {
  const pathname = usePathname()
  return (
    <AnimatePresence mode="wait">
      <motion.div
        key={pathname}
        variants={variants}
        initial="initial"
        animate="enter"
        exit="exit"
        transition={{
          duration: motionTokens.duration.normal,
          ease: motionTokens.easing.smooth,
        }}
      >
        {children}
      </motion.div>
    </AnimatePresence>
  )
}

スクロールリビール

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

<motion.div
  initial={{ opacity: 0, y: motionTokens.distance.lg }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: "-80px" }}   // once: true — ルール 7
  transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>

スクロールプログレスバー

"use client"
import { motion, useScroll } from "motion/react"

export function ScrollProgress() {
  const { scrollYProgress } = useScroll()
  return (
    <motion.div
      className="fixed top-0 left-0 h-1 bg-indigo-500 origin-left w-full"
      style={{ scaleX: scrollYProgress }}
    />
  )
}

展開カード

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

export function ExpandingCard({ title, body }: { title: string; body: string }) {
  const [expanded, setExpanded] = useState(false)

  return (
    <motion.div layout onClick={() => setExpanded(!expanded)} className="cursor-pointer">
      {/* layout="position" によりテキストのリフローがアニメーションしない */}
      <motion.h2 layout="position" className="font-semibold">
        {title}
      </motion.h2>

      <AnimatePresence>
        {expanded && (
          <motion.p
            key="body"
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            transition={{ duration: motionTokens.duration.fast }}
          >
            {body}
          </motion.p>
        )}
      </AnimatePresence>
    </motion.div>
  )
}

共有要素クロスフェード

// ソースコンテキスト
<motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />

// 宛先コンテキスト（同じ layoutId — motion がトランジションを処理）
<motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" />

アコーディオン

<motion.div
  initial={false}
  animate={{ opacity: open ? 1 : 0, scaleY: open ? 1 : 0 }}
  style={{ transformOrigin: "top", overflow: "hidden" }}
  transition={{
    duration: motionTokens.duration.normal,
    ease: motionTokens.easing.smooth,
  }}
> {children}
</motion.div>

エンドツーエンドの例

マウント時に現れ、条件付きプレゼンスを処理し、動きの軽減設定を尊重するスタガーリスト — トークン、スプリング、AnimatePresence、そして motion-foundations のアクセシビリティフックを組み合わせたもの:

"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"

const containerVariants = {
  hidden: {},
  visible: {
    transition: { staggerChildren: 0.08, delayChildren: 0.1 },
  },
}

function ListItem({ label, onRemove }: { label: string; onRemove: () => void }) {
  const safe = useSafeMotion(motionTokens.distance.sm)
  return (
    <motion.li
      variants={{
        hidden:  safe.initial,
        visible: safe.animate,
      }}
      exit={safe.exit}
      transition={springs.gentle}
      className="flex items-center justify-between p-3 rounded-lg bg-white shadow-sm"
    >
      <span>{label}</span>
      <button onClick={onRemove}>削除</button>
    </motion.li>
  )
}

export function AnimatedList({ items, onRemove }: {
  items: { id: string; label: string }[]
  onRemove: (id: string) => void
}) {
  return (
    <motion.ul
      variants={containerVariants}
      initial="hidden"
      animate="visible"
      className="space-y-2"
    >
      <AnimatePresence mode="popLayout">
        {items.map((item) => (
          <ListItem
            key={item.id}
            label={item.label}
            onRemove={() => onRemove(item.id)}
          />
        ))}
      </AnimatePresence>
    </motion.ul>
  )
}

制約 / 対象外

このスキルは以下を カバーしません:

• トークンとスプリングの定義 → motion-foundations を参照
• ドラッグ操作、スワイプジェスチャー、並べ替え可能リスト → motion-advanced を参照
• テキストアニメーション（単語/文字の表示、カウンター） → motion-advanced を参照
• SVG パス描画またはモーフィング → motion-advanced を参照
• カスタムアニメーションフック → motion-advanced を参照
• motion/react を使用しない CSS のみのトランジション

アンチパターン

アンチパターン	違反するルール	修正方法
AnimatePresence の子要素に key がない	ルール 1	直接の子要素に安定した key を追加
initial + animate に exit がない	ルール 2	常に3つすべてを一緒に定義する
mode="wait" のないページトランジション	ルール 3	AnimatePresence に mode="wait" を追加
50 個のアイテムがあるリストでの layout	ルール 4	mode="popLayout" または明示的なトランスフォームを使用
10 個のアイテムがあるリストでの staggerChildren: 0.2	ルール 5	0.08–0.10 に抑える
フォーカストラップのないモーダル	ルール 6	focus-trap-react または Radix Dialog を追加
viewport={{ once: true }} のない whileInView	ルール 7	繰り返し出現は情報的でなく邪魔
transition={{ duration: 0.3 }} のインライン記述	ルール 8	motionTokens.duration.normal を使用

関連スキル

• motion-foundations — ここにあるすべてのパターンがインポートする、すべてのトークン、スプリング、useSafeMotion フック、SSR ガードを定義します。最初にセットアップする必要があります。
• motion-advanced — これらのパターンをドラッグ、ジェスチャー、SVG、テキスト、カスタムフック、命令型シーケンスで拡張します。このスキルのパターンを再定義することはありません。