Motion アニメーションライブラリ

概要

Motion (パッケージ: motion、旧名: framer-motion) は、数千のアプリケーションで本番環境で使用されている業界標準の React アニメーションライブラリです。30,200 以上の GitHub スター、300 以上の公式サンプルを誇り、最小限のコードで複雑なアニメーションを作成できる宣言的な API を提供します。

主な機能:

• ジェスチャー: ドラッグ、ホバー、タップ、パン、フォーカス（クロスデバイス対応）
• スクロールアニメーション: ビューポートトリガー、スクロールリンク、パララックス効果
• レイアウトアニメーション: レイアウト変更を滑らかにする FLIP テクニック、共有要素トランジション
• スプリングフィジックス: 物理ベースのイージング、自然でカスタマイズ可能なモーション
• SVG: パスモーフィング、ライン描画、属性アニメーション
• 終了アニメーション: AnimatePresence でアンマウント時のトランジション
• パフォーマンス: ハードウェアアクセラレーション、ScrollTimeline API、バンドル最適化（2.3 KB～34 KB）

本番テスト済み: React 19、Next.js 15、Vite 6、Tailwind v4

---

このスキルを使用する場合

✅ Motion を使用する場合:

複雑なインタラクション:

• ドラッグ&ドロップインターフェース（ソート可能なリスト、カンバンボード、スライダー）
• スケール/回転/色変更を伴うホバー状態
• バウンス/スクイーズ効果を持つタップフィードバック
• モバイルフレンドリーなコントロール用パンジェスチャー

スクロールベースのアニメーション:

• パララックスレイヤーを備えたヒーローセクション
• スクロールトリガーされる表示（ビューポート内に要素が入ると フェードイン）
• スクロール位置にリンクされたプログレスバー
• スクロール依存のトランスフォームを持つスティッキーヘッダー

レイアウトトランジション:

• ルート間の共有要素トランジション（カード → 詳細ページ）
• 自動高さアニメーション付きの展開/折りたたみ
• グリッド/リストビュー切り替え（スムーズな再配置）
• アニメーション下線を持つタブナビゲーション

高度な機能:

• SVG ラインドローイングアニメーション
• 図形間のパスモーフィング
• 自然なバウンスのためのスプリングフィジックス
• 動作組成（段階的な表示）
• バックドロップぼかし付きのモーダルダイアログ

バンドル最適化:

• 2.3 KB のアニメーションライブラリが必要（useAnimate ミニ）
• Motion を 34 KB から 4.6 KB に削減したい（LazyMotion）

❌ Motion を使用しない場合:

• シンプルなリストアニメーション（代わりに auto-animate を使用: 3.28 KB vs 34 KB）
• インタラクションのない静的コンテンツ
• Cloudflare Workers（framer-motion v12.23.24 回避策を使用 - 既知の問題を参照）
• 3D アニメーション（代わりに Three.js または React Three Fiber を使用）

---

インストール

最新安定版

bun add motion  # 推奨
# または: npm install motion
# または: yarn add motion

現在のバージョン: 12.23.24（検証日: 2025-11-07）

Cloudflare Workers 向け別バージョン:

# Cloudflare Workers へのデプロイ時は framer-motion を使用
bun add framer-motion
# または: npm install framer-motion

パッケージ情報

• バンドルサイズ:
  • 完全な motion コンポーネント: ~34 KB (minified+gzipped)
  • LazyMotion + m コンポーネント: ~4.6 KB
  • useAnimate ミニ: 2.3 KB（最小 React アニメーションライブラリ）
  • useAnimate ハイブリッド: 17 KB
• 依存関係: React 18+ または React 19+
• TypeScript: ネイティブサポート含まれる（@types パッケージは不要）

---

コアコンセプト

1. motion コンポーネント

任意の HTML/SVG 要素をアニメーション可能なコンポーネントに変換:

import { motion } from "motion/react"

// 基本的なアニメーション
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  コンテンツがフェードインしてスライドアップ
</motion.div>

// ジェスチャーコントロール
<motion.button
  whileHover={{ scale: 1.1 }}
  whileTap={{ scale: 0.95 }}
>
  クリック
</motion.button>

プロパティ:

• initial: 開始状態（オブジェクトまたはバリアント名）
• animate: ターゲット状態（オブジェクトまたはバリアント名）
• exit: アンマウント状態（AnimatePresence が必須）
• transition: タイミング/イージング設定
• whileHover, whileTap, whileFocus: ジェスチャー状態
• whileInView: ビューポートトリガーアニメーション
• drag: ドラッグ有効化（"x"、"y"、または両方）
• layout: FLIP レイアウトアニメーションを有効化

2. バリアント（アニメーション動作組成）

コンポーネントツリー全体に伝播する名前付きアニメーション状態:

const variants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0 }
}

<motion.div variants={variants} initial="hidden" animate="visible">
  コンテンツ
</motion.div>

高度な動作組成の場合（staggerChildren、delayChildren、動的バリアント）、references/core-concepts-deep-dive.md を読み込んでください。

3. AnimatePresence（終了アニメーション）

コンポーネントアンマウント時のアニメーション実行を有効化:

import { AnimatePresence } from "motion/react"

<AnimatePresence>
  {isVisible && (
    <motion.div
      key="modal"
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      exit={{ opacity: 0 }}
    >
      モーダルコンテンツ
    </motion.div>
  )}
</AnimatePresence>

重要ルール:

• AnimatePresence はマウント状態を保つ必須（条件付きでラップしない）
• すべての子要素は一意の key プロパティを持つ必須
• AnimatePresence は条件をラップ（反対ではない）

よくあるミス（終了アニメーションが再生されない）:

// ❌ 間違い - AnimatePresence が条件と共にアンマウント
{isVisible && (
  <AnimatePresence>
    <motion.div>コンテンツ</motion.div>
  </AnimatePresence>
)}

// ✅ 正解 - AnimatePresence がマウント状態を保つ
<AnimatePresence>
  {isVisible && <motion.div key="unique">コンテンツ</motion.div>}
</AnimatePresence>

4. レイアウトアニメーション（FLIP）

レイアウト変更を自動的にアニメーション:

<motion.div layout>
  {isExpanded ? <FullContent /> : <Summary />}
</motion.div>

特殊プロパティ: layoutId（共有要素トランジション）、layoutScroll（スクロール可能なコンテナ）、layoutRoot（固定位置）。

高度なパターンの場合（LayoutGroup、layoutId 動作組成）、references/core-concepts-deep-dive.md を読み込んでください。

5. スクロールアニメーション

// ビューポートトリガー
<motion.div
  initial={{ opacity: 0, y: 50 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true }}
>
  ビューポート内に入るとフェードイン
</motion.div>

// スクロールリンク（パララックス）
import { useScroll, useTransform } from "motion/react"
const { scrollYProgress } = useScroll()
const y = useTransform(scrollYProgress, [0, 1], [0, -300])
<motion.div style={{ y }}>パララックス効果</motion.div>

高度なスクロールパターンの場合（useScroll オフセット、useTransform イージング、パララックスレイヤー）、references/core-concepts-deep-dive.md を読み込んでください。

6. ジェスチャー

<motion.div drag="x" dragConstraints={{ left: -200, right: 200 }}>
  ドラッグしてください
</motion.div>

利用可能: whileHover、whileTap、whileFocus、whileDrag、whileInView、drag。

高度なドラッグコントロールの場合（モーメンタム、エラスティック、イベントハンドラー）、references/core-concepts-deep-dive.md を読み込んでください。

7. スプリングフィジックス

<motion.div
  animate={{ x: 100 }}
  transition={{ type: "spring", stiffness: 100, damping: 10 }}
/>

一般的なプリセット: バウンシー { stiffness: 300, damping: 10 }、スムーズ { stiffness: 100, damping: 20 }。

スプリングチューニングの場合（mass パラメータ、ビジュアライザー、プリセット）、references/core-concepts-deep-dive.md を読み込んでください。

---

インテグレーションガイド

Vite: bun add motion → import { motion } from "motion/react"（すぐに機能）

Next.js App Router: "use client" ディレクティブまたはクライアントコンポーネントラッパーが必須

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

Tailwind: ⚠️ transition-* クラスを削除（Motion アニメーションと競合）

Cloudflare Workers: 代わりに framer-motion v12.23.24 を使用（Motion は Wrangler ビルドに問題あり）

完全なインテグレーションガイドは（Next.js パターン、SSR、フレームワーク固有の問題）、references/nextjs-integration.md を読み込んでください。

---

パフォーマンス最適化

バンドルサイズ: LazyMotion を使用（34 KB → 4.6 KB）:

import { LazyMotion, domAnimation, m } from "motion/react"
<LazyMotion features={domAnimation}>
  <m.div>たった 4.6 KB！</m.div>
</LazyMotion>

大規模リスト: 50 個以上のアニメーション要素には仮想化（react-window、react-virtuoso）を使用。

完全な最適化ガイドは（ハードウェアアクセラレーション、メモリプロファイリング、本番ベンチマーク）、references/performance-optimization.md を読み込んでください。

---

アクセシビリティ

prefers-reduced-motion を尊重:

import { MotionConfig } from "motion/react"
<MotionConfig reducedMotion="user">
  <App />
</MotionConfig>

キーボード対応: whileFocus をキーボードトリガーアニメーション用に使用。

<motion.button whileFocus={{ scale: 1.1 }} tabIndex={0}>
  キーボード対応
</motion.button>

完全なアクセシビリティガイドは（ARIA パターン、スクリーンリーダー、AnimatePresence 回避策、テスト）、references/accessibility-guide.md を読み込んでください。

---

よくあるパターン

モーダルダイアログ（AnimatePresence + バックドロップ）:

<AnimatePresence>
  {isOpen && (
    <motion.dialog exit={{ opacity: 0 }}>コンテンツ</motion.dialog>
  )}
</AnimatePresence>

アコーディオン（高さアニメーション）:

<motion.div animate={{ height: isOpen ? "auto" : 0 }}>
  コンテンツ
</motion.div>

15 以上の本番パターンは（カルーセル、タブ、スクロール表示、パララックス、通知）、references/common-patterns.md を読み込んでください。

---

既知の問題と解決策

問題 1: AnimatePresence 終了が機能しない（最も一般的）

症状: コンポーネントが終了アニメーションなしで即座に消える。

解決策: AnimatePresence はマウント状態を保つ必須、条件をラップ（ラップされない）:

// ❌ 間違い
{isVisible && <AnimatePresence><motion.div>コンテンツ</motion.div></AnimatePresence>}

// ✅ 正解
<AnimatePresence>
  {isVisible && <motion.div key="unique">コンテンツ</motion.div>}
</AnimatePresence>

問題 2: Next.js "use client" 不足

症状: "motion is not defined" またはSSRエラーでビルド失敗。

解決策: "use client" ディレクティブを追加:

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

問題 3: Tailwind トランジション競合

症状: アニメーションが断続的または機能しない。

解決策: transition-* クラスを削除（Motion が CSS トランジションを上書き）:

// ❌ 間違い: <motion.div className="transition-all" animate={{ x: 100 }} />
// ✅ 正解: <motion.div animate={{ x: 100 }} />

問題 4: Cloudflare Workers ビルドエラー

症状: motion パッケージ使用時に Wrangler ビルド失敗。

解決策: 代わりに framer-motion v12.23.24 を使用（GitHub issue #2918）:

bun add framer-motion  # 同じ API、Workers で機能

問題 5: 大規模リストパフォーマンス

症状: 50～100 個以上のアニメーション要素で大幅な速度低下。

解決策: 仮想化を使用（react-window、react-virtuoso）。

5 つ以上の追加問題は（layoutScroll、layoutRoot、AnimatePresence + layoutId）、references/nextjs-integration.md または references/core-concepts-deep-dive.md を読み込んでください。

---

リファレンスを読み込む場合

Claude はユーザーニーズに基づいて以下のリファレンスを読み込みます:

references/core-concepts-deep-dive.md を読み込む場合:

• ユーザーがバリアント動作組成（staggerChildren、delayChildren、動的バリアント）について質問
• ユーザーが高度なレイアウトアニメーション（layoutId 共有トランジション、LayoutGroup）を必要
• ユーザーがスクロールリンクアニメーション（useScroll オフセット、useTransform イージング、パララックスレイヤー）を望む
• ユーザーが複雑なドラッグパターン（モーメンタム、エラスティック、イベントハンドラー、制約）を必要
• ユーザーがスプリングフィジックスチューニング（mass パラメータ、ビジュアライザー、カスタムプリセット）について質問

references/performance-optimization.md を読み込む場合:

• ユーザーがバンドルサイズを 4.6 KB 未満に削減したい（useAnimate ミニ、LazyMotion 比較）
• ユーザーが「アプリが遅い」、「ジャンキーなアニメーション」、「カクカク」、「パフォーマンス問題」と述べる
• ユーザーがリストに 50 個以上のアニメーション要素（仮想化必要）
• ユーザーがメモリプロファイリングまたは本番ベンチマークが必要

references/nextjs-integration.md を読み込む場合:

• ユーザーが Next.js で構築中（App Router または Pages Router）
• ユーザーが SSR エラー、"use client" エラー、またはハイドレーション問題に遭遇
• ユーザーがルートトランジションまたはページナビゲーションアニメーションについて質問
• ユーザーが Next.js 固有の回避策が必要（Reorder コンポーネント、AnimatePresence ソフトナビゲーション）

references/accessibility-guide.md を読み込む場合:

• ユーザーが「prefers-reduced-motion」またはアクセシビリティコンプライアンスについて質問
• ユーザーが ARIA インテグレーションパターン（ロール、ラベル、アナウンス）を必要
• ユーザーがスクリーンリーダー互換性を望む
• ユーザーがアクセシビリティ監査または WCAG コンプライアンスについて述べる
• ユーザーが AnimatePresence reducedMotion 回避策について質問（既知の問題 #1567）

references/common-patterns.md を読み込む場合:

• ユーザーが特定の UI パターン（モーダル、アコーディオン、カルーセル、タブ、ドロップダウン、トースト等）について質問
• ユーザーが本番用コピーペーストコード例を必要
• ユーザーが 15 以上の実世界のアニメーションパターンを見たい

references/motion-vs-auto-animate.md を読み込む場合:

• ユーザーが Motion と AutoAnimate ライブラリ間で選択中
• ユーザーが「シンプルなリストアニメーション」または「バンドルサイズ懸念」について述べる
• ユーザーが「どのアニメーションライブラリを使うべきか？」または「Motion は過剰か？」について質問
• ユーザーが機能比較または決定マトリックスを必要

---

テンプレート

このスキルには templates/ ディレクトリに 5 つの本番対応テンプレートが含まれます:

1. motion-vite-basic.tsx - 基本的な Vite + React + TypeScript セットアップ、よくあるアニメーション
2. motion-nextjs-client.tsx - Next.js App Router パターン、クライアントコンポーネントラッパー
3. scroll-parallax.tsx - スクロールアニメーション、パララックス、ビューポートトリガー
4. ui-components.tsx - モーダル、アコーディオン、カルーセル、共有下線付きタブ
5. layout-transitions.tsx - FLIP レイアウトアニメーションと共有要素トランジション

テンプレートをプロジェクトにコピーし、必要に応じてカスタマイズしてください。

---

リファレンス

このスキルには 4 つの包括的なリファレンスガイドが含まれます:

• motion-vs-auto-animate.md - 決定ガイド: Motion vs AutoAnimate を使用する場合
• performance-optimization.md - バンドルサイズ、LazyMotion、仮想化、ハードウェアアクセラレーション
• nextjs-integration.md - App Router vs Pages Router、"use client"、既知の問題
• common-patterns.md - 上位 15 パターン、完全なコード例

詳細ガイドについて references/ ディレクトリを参照。

---

スクリプト

このスキルには 2 つの自動化スクリプトが含まれます:

• init-motion.sh - フレームワーク検出機能付きのワンコマンドセットアップ（Vite、Next.js、Cloudflare Workers）
• optimize-bundle.sh - 既存の Motion コードを LazyMotion に変換してバンドル削減

自動化ツールについて scripts/ ディレクトリを参照。

---

公式ドキュメント

• 公式サイト: https://motion.dev
• GitHub: https://github.com/motiondivision/motion（30,200 以上のスター）
• サンプル: https://motion.dev/examples（300 以上のサンプル）

関連スキル: auto-animate（シンプルなリスト）、tailwind-v4-shadcn（スタイリング）、nextjs（App Router）、cloudflare-worker-base

Motion vs AutoAnimate: 詳細比較は references/motion-vs-auto-animate.md を読み込んでください。

---

トークン効率指標

トークン節約: ~83%（30k → 5k トークン）| エラー防止: 100%（29 以上のエラー）| 時間節約: ~85%（2～3 時間 → 20～30 分）

---

パッケージバージョン（検証日: 2025-11-07）

パッケージ	バージョン	ステータス
motion	12.23.24	✅ 最新安定版
framer-motion	12.23.24	✅ Cloudflare 向け別バージョン
react	19.2.0	✅ 最新安定版
vite	6.0.0	✅ 最新安定版

---

貢献

問題を見つけたか提案がありますか？

• Issue を開く: https://github.com/secondsky/claude-skills/issues
• テンプレートとリファレンスで詳細な例を参照

---

本番テスト済み: ✅ React 19 + Next.js 15 + Vite 6 + Tailwind v4 トークン節約: ~83% エラー防止: 100%（29 以上の文書化されたエラー防止） バンドルサイズ: 2.3 KB（ミニ）～34 KB（フル）、LazyMotion で 4.6 KB に最適化可能 アクセシビリティ: MotionConfig reducedMotion サポート 使用準備完了！ ./scripts/install-skill.sh motion でインストール