nextjs-framer-motion-animations

Next.js で意図のあるモーションを使う

モーションは状態を説明したり、インタラクションを改善したりするために選び、すべてのページに必須のレイヤーとして追加しないでください。既存のデザイントークンとセマンティックなコントロールを維持してください。色、フォーカス、ホバーの小さなトランジションであれば、CSS を使うことで不要なクライアント JavaScript を避けられる場合があります。

境界を決める前に調査する

実際のコンポーネント、ルーター（App または Pages）、パッケージファイル／ロックファイル、インストール済みの Motion API、ビルド設定を確認してください。マウント、状態、フォーカス、スクロール、ナビゲーションを誰が管理しているかを特定します。ローカルな表示とルート遷移を区別してください。ファイル名やトークンのスキャナーでは、こうした関係性やビルド互換性を確認できません。

新規コードや最新化する Motion コードでは、motion/react を使用してください。Server Component では、サポートされている motion/react-client エントリーポイントによって Motion 要素を利用できますが、フックや任意のコールバックがサーバーセーフになるわけではありません。インタラクションやフックは最小限の Client Component に配置し、データ取得やシークレットはサーバー側に残します。サーバーでレンダリングされた子コンポーネントは、実装をクライアントバンドルに移さずにクライアントラッパーを通して渡せます。この境界を越える Props は、React の実際のシリアライズ要件を満たす必要があります。

既存の framer-motion プロジェクトでは、インストール済みのバージョンを確認し、移行を作業範囲に含めるか判断してください。移行を行う場合は、パッケージ、インポート、ロックファイル、テスト、変更された API をまとめて更新します。複数のランタイムを混在させたり、motion/react-m からの名前空間インポートを別のモジュールへ機械的に書き換えたりしないでください。このスキルには、互換性を保つための分岐処理も、自動インポート書き換え機能も含まれていません。

仕組みを選ぶ

必要なもの	まず使うもの	必須条件
小規模なローカルトゥイーン／ジェスチャー	motion 要素	セマンティックな要素と、無効化／フォーカス時の動作を維持する
連動する複数の子要素	variants と stagger	安定した識別性と、上限を定めた遅延時間を確保する
ローカルな削除	AnimatePresence	削除されたキー付き子要素を保持し、監視できる
レイアウト変更	layout / layout="position"	正しく測定し、識別性を維持する
ライブツリー内の共有要素	layoutId / LayoutGroup	一意で、意図的にスコープされた ID を使う
表示時のリビール	whileInView	正しいスクロールルートと段階的な表示を設定する
スクロール連動の値	useScroll とモーション値	正しいターゲット／コンテナーと、動きを減らす設定を使う
命令型シーケンス	useAnimate	ターゲットをスコープし、キャンセル／クリーンアップを行う
バンドルサイズに配慮が必要な領域	m を使った LazyMotion	使用するレイアウト／ドラッグ API を機能セットがカバーする
ルート／共有ビュー遷移	フレームワークがサポートする ViewTransition	pathname ラッパーではなく、実際の Next／React／ブラウザーの仕様に従う

実装上の判断についてはコンポーネントパターンを、ルート変更についてはルーターとの統合を確認してください。パッケージ全体でプロバイダーをひとつ使うことや、どのインタラクションにも同じアニメーション時間が適していることを前提にしないでください。

Presence とアプリケーションの状態

AnimatePresence 自体には永続的に保持されることが退出アニメーションに必要ですが、ルーターが所有するサブツリーを制御するには不十分です。ラッパーを pathname でキー付けしても、遷移元のルートコンテンツが変更されずに保持されるとは限りません。退出アニメーションのデモを動かすために、非公開のルーターコンテキストを固定したり、すべてのクリックを横取りしたり、すべてのナビゲーションを遅らせたりしないでください。サポートされているフレームワークのルート機構を使うか、入場のみの機能強化として正直に実装してください。

アニメーションのコールバックはトランザクションの境界ではありません。決済、削除、ナビゲーションの確認、その他のアプリケーションの結果を、アニメーションがたまたま完了したかどうかに依存させないでください。キャンセル、中断、再マウント、動きを減らす設定でも、同じ論理的な結果を維持する必要があります。

アクセシビリティとレンダリング

既存のツリーに適合する場合は MotionConfig reducedMotion="user" を使用し、スクロール、自動再生、独自のエフェクトについてはローカルで useReducedMotion に基づく判断を行います。Opacity のみのアニメーションや、独立した CSS／ビュー遷移の経路には、それぞれ独自の方針が必要です。Motion プロバイダーを 1 つ導入しても、あらゆる動きを一律に制御できるわけではありません。

実際のボタン、リンク、ダイアログを使用します。キーボード操作の経路、視認できるフォーカス、論理的な読み上げ順序、ドラッグ操作のみのインタラクションに相当する手段を維持します。退出後に見えなくなったコントロールを、フォーカス可能な状態のままにしたり、入力を妨げたりしてはいけません。見た目上のモーダルシェルは、フォーカス管理、Escape キーの動作、ラベル、背景の操作無効化の代わりにはなりません。

重要なテキストをサーバー側で常に非表示の状態でレンダリングし、ハイドレーションや交差監視が成功した場合にのみ表示する設計にしてはいけません。レイアウトボックスを安定させ、必要に応じてフォントや画像の読み込み、ビューポートの変化、JavaScript が無効な場合や失敗した場合の動作に対処します。適切な場合は transform／opacity を使用しますが、速度向上を主張する前に、実際のペイント、レイアウト、コンポジット、バンドルのコストを測定してください。

実際の変更を検証する

許可されている範囲で、プロジェクト既存の型チェック、lint、ビルドを実行します。スクリプト名が npm run lint/build だと思い込まないでください。ブラウザーで、素早い操作、戻る／進むナビゲーション、低速なデータ、操作の中断、動きの軽減、キーボード操作、共有レイアウトコンポーネントの複数インスタンスをテストします。コンソール／ハイドレーションエラー、スクロール位置の復元、フォーカス、アニメーションなしでも使えるフォールバックを確認します。ユニットテストのモックは、ブラウザーでのパフォーマンスやルーターのライフタイムを検証するものではありません。

パッチ、選択した境界／仕組み、実際に行った検証、残るブラウザーチェックを提示してください。以前の汎用スキャナー、生成プラン、全アセット用スキャフォルダー、およびそれらのゴールデン出力パックは削除されています。目的はヒューリスティックが推奨する出力を再現することではなく、実際の統合を示すことです。

参照元とメンテナンス

レビュー日：2026-09-13：Motion のインストール、 AnimatePresence、 Next のテンプレート、 Next のビュー遷移。 評価ケースには必須のチェック項目が記載されていますが、実行済みのテストではありません。