motion

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

概要

Motion（パッケージ：motion、旧称 framer-motion）は、何千ものアプリケーションで本番環境に採用されている業界標準の React アニメーションライブラリです。GitHub で 30,200 以上のスターを獲得し、公式サンプルを 300 以上提供しています。宣言的な API により、最小限のコードで高度なアニメーションを作成できます。

主な機能：

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

推奨スタック：React 19、Next.js 16、Vite 7、Tailwind v4

---

このスキルを使うタイミング

✅ Motion を使う場合：

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

• ドラッグ＆ドロップインターフェース（ソート可能なリスト、カンバンボード、スライダー）
• 拡大・回転・色の変化を伴うホバー状態
• バウンスやスクイーズ効果を伴うタップ時のフィードバック
• モバイルで使いやすいコントロールのためのパンジェスチャー

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

• パララックスレイヤーを備えたヒーローセクション
• スクロールをトリガーにした表示（要素がビューポートに入るとフェードイン）
• スクロール位置に連動するプログレスバー
• スクロールに応じて変形する固定ヘッダー

レイアウトのトランジション：

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

高度な機能：

• SVG の線描画アニメーション
• シェイプ間のパスのモーフィング
• 自然なバウンスのためのスプリング物理
• オーケストレーションされたシーケンス（段階的な表示）
• 背景のぼかしを伴うモーダルダイアログ

バンドルの最適化：

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

❌ Motion を使わない場合：

• シンプルなリストアニメーション（代わりに auto-animate を使用：3.28 KB 対 34 KB）
• インタラクションのない静的なコンテンツ
• Cloudflare Workers（以前は framer-motion のエイリアスが必要でしたが、motion v12.43+ ではメインパッケージが Workers で動作します。詳しくは既知の問題を参照してください）
• 3D アニメーション（代わりに Three.js または React Three Fiber を使用）

---

インストール

最新の安定版

bun add motion  # preferred
# or: npm install motion
# or: yarn add motion

現在のバージョン：12.43.0（2026-08-03 に確認）

注：現在のパッケージ名は motion です。framer-motion は同じコードを再公開する非推奨のエイリアスです。引き続き利用でき、インストール時のエイリアスとしてメンテナンスされています（特に Cloudflare Workers のビルド回避策として有用です）。ただし、新しいプロジェクトでは motion をインストールしてください。

Cloudflare Workers 向けの代替方法：

# Use framer-motion if deploying to Cloudflare Workers
bun add framer-motion
# or: npm install framer-motion

パッケージ情報

• バンドルサイズ：
  • 完全版の motion コンポーネント：約 34 KB（圧縮・gzip 圧縮後）
  • LazyMotion と m コンポーネント：約 4.6 KB
  • useAnimate mini：2.3 KB（最小の React アニメーションライブラリ）
  • useAnimate hybrid：17 KB
• 依存関係：React 18+ または React 19+
• TypeScript：ネイティブサポートが含まれているため、@types パッケージは不要です

---

基本概念

1. motion コンポーネント

あらゆる HTML/SVG 要素をアニメーション可能なコンポーネントに変換します：

import { motion } from "motion/react"

// Basic animation
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  Content fades in and slides up
</motion.div>

// Gesture controls
<motion.button
  whileHover={{ scale: 1.1 }}
  whileTap={{ scale: 0.95 }}
>
  Click me
</motion.button>

Props：

• initial：開始時の状態（オブジェクトまたはバリアント名）
• animate：目標の状態（オブジェクトまたはバリアント名）
• exit：アンマウント時の状態（AnimatePresence が必要）
• transition：タイミングとイージングの設定
• whileHover、whileTap、whileFocus：ジェスチャー時の状態
• whileInView：ビューポートをトリガーにしたアニメーション
• drag：ドラッグを有効化（「x」、「y」、または両方の場合は true）
• layout：FLIP レイアウトアニメーションを有効化

2. バリアント（アニメーションのオーケストレーション）

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

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

<motion.div variants={variants} initial="hidden" animate="visible">
  Content
</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 }}
    >
      Modal content
    </motion.div>
  )}
</AnimatePresence>

重要なルール：

• AnimatePresence は常にマウントされた状態にする必要があります（条件分岐で囲まないでください）
• すべての子要素に一意の key プロパティを指定する必要があります
• 条件分岐を AnimatePresence で囲みます。逆ではありません

よくある間違い（終了アニメーションが再生されません）：

// ❌ Wrong - AnimatePresence unmounts with condition
{isVisible && (
  <AnimatePresence>
    <motion.div>Content</motion.div>
  </AnimatePresence>
)}

// ✅ Correct - AnimatePresence stays mounted
<AnimatePresence>
  {isVisible && <motion.div key="unique">Content</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. スクロールアニメーション

// Viewport-triggered
<motion.div
  initial={{ opacity: 0, y: 50 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true }}
>
  Fades in when entering viewport
</motion.div>

// Scroll-linked (parallax)
import { useScroll, useTransform } from "motion/react"
const { scrollYProgress } = useScroll()
const y = useTransform(scrollYProgress, [0, 1], [0, -300])
<motion.div style={{ y }}>Parallax effect</motion.div>

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

6. ジェスチャー

<motion.div drag="x" dragConstraints={{ left: -200, right: 200 }}>
  Drag me
</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 }。

スプリングの調整（質量、ビジュアライザー、プリセット）については、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.43.0 を使用してください（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>Only 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}>
  Keyboard accessible
</motion.button>

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

---

よくあるパターン

モーダルダイアログ（AnimatePresence + 背景）：

<AnimatePresence>
  {isOpen && (
    <motion.dialog exit={{ opacity: 0 }}>Content</motion.dialog>
  )}
</AnimatePresence>

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

<motion.div animate={{ height: isOpen ? "auto" : 0 }}>
  Content
</motion.div>

本番環境向けの 15 種類以上のパターン（カルーセル、タブ、スクロール時の表示、視差、通知）については、references/common-patterns.md を読み込んでください。

---

既知の問題と解決策

問題 1：AnimatePresence の終了アニメーションが動作しない（最もよくある問題）

症状：終了アニメーションなしで、コンポーネントが瞬時に消えます。

解決策：AnimatePresence は常にマウントされた状態にし、条件分岐を囲んでください（条件分岐で囲まないでください）：

// ❌ Wrong
{isVisible && <AnimatePresence><motion.div>Content</motion.div></AnimatePresence>}

// ✅ Correct
<AnimatePresence>
  {isVisible && <motion.div key="unique">Content</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 トランジションを上書きします）：

// ❌ Wrong: <motion.div className="transition-all" animate={{ x: 100 }} />
// ✅ Correct: <motion.div animate={{ x: 100 }} />

問題 4：Cloudflare Workers のビルドエラー

症状：motion パッケージを使用すると、Wrangler のビルドに失敗します。

解決策：代わりに framer-motion v12.43.0 を使用してください（GitHub の issue #2918）：

bun add framer-motion  # Same API, works with 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、dynamic variants）について質問している
• 高度なレイアウトアニメーション（layoutId による共有トランジション、LayoutGroup）が必要
• スクロール連動アニメーション（useScroll の offsets、useTransform の easing、パララックスレイヤー）を希望している
• 複雑なドラッグパターン（モメンタム、弾性、イベントハンドラー、制約）が必要
• スプリング物理の調整（mass パラメーター、ビジュアライザー、カスタムプリセット）について質問している

次の場合は references/performance-optimization.md を読み込みます：

• バンドルサイズを 4.6 KB 未満に減らしたい（useAnimate mini、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 と AutoAnimate の使い分け
• performance-optimization.md - バンドルサイズ、LazyMotion、仮想化、ハードウェアアクセラレーション
• nextjs-integration.md - App Router と 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+ stars)
• サンプル: https://motion.dev/examples (300+ examples)

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

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

---

トークン効率の指標

トークン削減：約83％（30k → 5k トークン） | エラー防止：100％（29件以上のエラー） | 時間短縮：約85％（2～3時間 → 20～30分）

---

パッケージのバージョン（2026-08-03 確認済み）

パッケージ	バージョン	ステータス
motion	12.43.0	✅ 最新の安定版
framer-motion	12.43.0	✅ motion の非推奨エイリアス（Cloudflare Workers の回避策）
react	19.2.0	✅ 最新の安定版
vite	7.3.0	✅ 最新の安定版

---

貢献

問題を見つけた場合や提案がある場合は、以下をご利用ください。

• イシューを作成：https://github.com/secondsky/claude-skills/issues
• 詳細な例については、テンプレートとリファレンスをご覧ください

---

推奨スタック：✅ React 19 + Next.js 16 + Vite 7 + Tailwind v4 トークン削減：約83％ エラー防止：100％（文書化された29件以上のエラーを防止） バンドルサイズ：2.3 KB（mini）～34 KB（full）。LazyMotion を使用すると4.6 KBまで最適化できます アクセシビリティ：MotionConfig の reducedMotion サポート すぐに使用できます！ /plugin install motion@claude-skills でインストールしてください