目標
Erlin の個人サイトのアニメーション手法:Next.js/React サイトに motion アニメーションライブラリを導入し、framer-motion からの移行、スクロールリビール / スタッガーグリッド / ページトランジション / ナビゲーションアニメーションを実装します。ただし、アニメーションでコンテンツを決して隠さないことが絶対条件です。重要な教訓:whileInView がトップページのプロジェクトカードを opacity:0 で固定してしまったことがあります(「プロジェクトカードが消えた」)。そのため、可視性のフォールバックが必要です。既に信頼できる実装がある場合はそれを保持し、Reveal はオプションの参考として使用し、whileInView を全面的に禁止するわけではありません。
実行手順
-
まずプロジェクト環境を判断する(手を動かす前に 30 秒かけて確認し、誤ったテンプレートを適用しないようにする):
- パッケージマネージャー:1 つの lockfile のみを認識:
pnpm-lock.yaml→ pnpm、package-lock.json→ npm、yarn.lock→ yarn、bun.lockまたはbun.lockb→ bun。複数の lockfile がある場合は処理を停止してユーザーに問い合わせる。lockfile がない場合はpackage.jsonのpackageManagerを読み取り、それでも判断できない場合は停止し、パッケージマネージャーを推測しない。以降のインストール、移行、lint、build コマンドはすべて確定したマネージャーに従う。 - Next/React のバージョン:実際の Next/React とアニメーションライブラリのバージョン、peer dependencies、公式の互換性情報を確認する。バージョンをハードコードしたり、クロスバージョンの API 完全互換性を宣言したりしない。
- ルーター構造(テンプレートを配置する前にプローブし、App Router をデフォルトにしない):
app/ディレクトリがある場合 → App Router、以下のルールに従ってテンプレートを選択。pages/のみの場合 → Pages Router、template.tsxの仕組みはなく、pages/_app.tsxまたは対象ページコンポーネント層でトランジションを実装し、その違いをユーザーに説明する。両方ない場合 → Next プロジェクトではないため、フレームワークのマウントポイントに相当する方法で実装する。App Router の場合:ロケールプレフィックス付きルート(app/[locale]/ディレクトリ)がある場合、テンプレートはapp/[locale]/template.tsxに配置。ロケールルートがない場合(クライアント側の言語切り替えなど)はapp/template.tsxに配置。Next でもナビゲーションのたびにテンプレートは再マウントされ、フェードインは正常に動作する。 - コンポーネントが現在サーバーコンポーネントかどうか:インタラクションが必要な motion 要素は最小限のクライアントコンポーネントに隔離する。サーバーロジックを含むコンポーネント全体をクライアントコンポーネントに変更しない。
- パッケージマネージャー:1 つの lockfile のみを認識:
-
既存の依存関係をそのまま使用する:既に
framer-motionが導入されており、要件を満たしている場合は引き続き使用し、新しいアニメーションを追加するためにデフォルトで移行しない。ユーザーから移行の要求があるか、現在の機能や互換性に本当に問題がある場合のみ、バージョンの違いを確認した上でプロジェクトのパッケージマネージャーを使用してmotionをインストールし、motion/reactのインポートと API を一つ一つ確認する。残存する依存関係がないことを確認してから古いパッケージを削除する。関連のないコメントやドキュメントを手当たり次第に変更しない。 -
アニメーションを実装する:必要に応じて Reveal を参考にする:テンプレートは
assets/reveal.tsxにあり、components/motion/reveal.tsxにコピーしてパスエイリアスを適応させる。設計のポイント(プロジェクトに合わせて適応):- 可視性のフォールバック:テンプレートは IntersectionObserver + 2.5 秒のタイムアウトを使用。2.5 秒は参考パラメータであり、ページと読み込み動作に応じて調整する。検証済みの whileInView やその他のメカニズムを使用して、observer、JavaScript、または hydration が失敗した場合でもコンテンツにアクセスできるようにする。
- SSR/hydration とプロジェクトの lint ルールに従って、reduced-motion と observer 欠落を処理する。hydration の不一致や不要な同期 effect 更新を避け、一度の lint 経験をすべての API の禁止事項と見なさない。
- reduced motion では最終状態を直接レンダリングする。
- 純粋な CSS トランジション(
cubic-bezier(0.22,1,0.36,1))を使用し、motion.div は使わない。アニメーションランタイムのオーバーヘッドゼロ。 Revealには className prop が組み込まれている:もともとdivのカード(glassカードなど)は、クラス名をそのまま Reveal に渡すことで、ネストを 1 層減らせる。article/sectionなどのセマンティックな要素には Reveal で外側をラップし、セマンティクスを維持する。
-
適用場所とスタッガー公式:
場所 方法 delay カードグリッド(トップページの複数ブロック) 各アイテムを RevealでラップMath.min(i * 0.08, 0.4)、長いグリッドの引き延ばしを防ぐために上限設定記事一覧(writing、latest-writing) 各行を Revealでラップi * 0.05~0.07、長いリストの引き延ばしを防ぐためにMath.min(i*0.05, 0.3)で上限設定プロジェクトの大きな画像行のテキスト列 Reveal固定 0.15、画像の視差とずらす本文/お問い合わせカード(about) 大きなブロックを Reveal2 番目のブロック 0.1ナビゲーションバー motion.headerで初期y:"-100%"からスライドイン、スクロール非表示は同じ transform を再利用— モバイルメニュー AnimatePresence+opacity/yトランジション、block/hidden切り替えを置き換え— ルート切り替え 新規 app/template.tsx(ロケールルートなしの場合)またはapp/[locale]/template.tsx(ロケールプレフィックス付き;Next はナビゲーションのたびに template を再マウント)でopacity+yフェードイン、0.35 秒— -
検証と納品:手順 1 で確認したパッケージマネージャーに従って:
pnpm lint && pnpm build # pnpm プロジェクト;build は成功必須(全站 SSG プロジェクトは SSG エクスポートを含む) npm run lint && npm run build # npm プロジェクトユーザーからコミットの許可がある場合のみ、プロジェクトのコミット慣例に従う。例:
feat(motion): 迁移 motion 库并新增全站动效。今回のタスクに関連するファイルのみをステージングする——リポジトリに関係のない未コミットの変更が混在していても、今回のコミットに巻き込まない。
判断ルール
- 使用する場面:Next.js サイトにアニメーション/モーションを追加する場合;
framer-motionをmotionパッケージに移行する場合(移行前に現在のバージョンの API を確認);ユーザーが「スクロールリビール」「スタッガー」「ページトランジション」「さらにアニメーション」を要求した場合。 - 対象外:SwiftUI、CSS-only、Remotion ビデオアニメーション。
- アニメーションデザインルール(失敗から学んだ教訓):
- LCP 要素(H1、hero)にはエントリーアニメーションを追加しない:
SkewRevealにはinstantprop があるか、初期状態を最終状態にしておく。そうしないと SSR のテキストがちらつく。 - すべてのアニメーションは
prefers-reduced-motionを尊重する:useReducedMotion()を使用し、reduced の場合は最終状態をレンダリング/リスナーを登録しない。 - 統一イージング
[0.22, 1, 0.36, 1](easeOutQuint スタイル)、持続時間 0.3–0.8 秒、控えめを優先。 - ホバーアニメーションは CSS トランジションで十分(例:
hover:-translate-y-1、group-hover:scale-105)、motion を導入する必要はない。 - クライアント側フィルタリング(タグフィルターなど)では、キーが変わらないリストアイテムはアニメーションを再生しない——これは期待される動作であり、新しく表示されるアイテムが自動的にトリガーされる。
- LCP 要素(H1、hero)にはエントリーアニメーションを追加しない:
- 既存コンポーネントの帰属:SkewReveal エントリー、Parallax 視差、Magnetic 磁気、MouseParallax はそのまま残し、新しいアニメーションは同じディレクトリに共存させる。プロジェクトに既に
.zcode/.agentsのアニメーションコンポーネントディレクトリ(例:components/motion/)がある場合、新しいコンポーネントは同じディレクトリに配置する。 - server/client の境界:サーバーコンポーネントは
Revealを直接レンダリングできる(これはクライアントコンポーネントだが、子コンポーネントとして使用する分には問題ない)。
アニメーションが完了する前に、視覚、アクセシビリティ、コンテンツの可視性を実際に確認する。このスキルは Next.js/React の motion 実装技術を扱う。RN/Expo やその他のスタックのアニメーションは同じ原則に従って直接実装し、このスキルのスクリプトに依存しない。
出力形式
Revealコンポーネントの配置:assets/reveal.tsxからcomponents/motion/reveal.tsxにコピーし、パスエイリアスを適応させる。- ルートトランジション:
app/template.tsx(ロケールルートなしの場合)またはapp/[locale]/template.tsx(ロケールプレフィックス付き)、opacity+yフェードイン 0.35 秒。 - コミットメッセージ:conventional commits + 中国語の説明。例:
feat(motion): 迁移 motion 库并新增全站动效。
例
ユーザーの質問
「サイトにスクロールリビールを追加し、ついでに framer-motion を motion に切り替えてください。」
ツールの応答
pnpm
pnpm add motion && pnpm remove framer-motion 成功、package.json にプロジェクト互換の motion バージョンが表示される。pnpm lint && pnpm build 全站 SSG は成功を維持。
sed
sed -i '' 's/from "framer-motion"/from "motion\/react"/g' <files> 実行後、すべてのインポートが motion/react を指すように更新される。今回の移行に関連し、実際に古くなった説明のみが更新される。
最終出力
components/motion/reveal.tsx(手動 IntersectionObserver + 2.5 秒フューズ)+ カード/リスト stagger + app/template.tsx ルートフェードイン。lint、build パス。実際の検証を報告。既存のコミット許可がある場合のみ、今回関連するファイルをコミット。
ゲート
- コンテンツの不可侵ライン:アニメーションでコンテンツを決して隠さない——SSR、reduced-motion、observer/スクリプト異常時でもコンテンツにアクセスできることを検証する。Reveal とタイムアウトパラメータは参考実装であり、API を機械的に無効化しない。
- アクセシビリティの不可侵ライン:すべてのアニメーションは
prefers-reduced-motionを尊重する。LCP 要素(H1、hero)にはエントリーアニメーションを追加しない。 - 検証:確認したパッケージマネージャーで
lint && buildを実行し、buildは成功を維持しなければならない(プロジェクトが全站 SSG の場合、SSG エクスポートも破壊されてはならない。SSR/ISR プロジェクトの場合は build が通ればよく、SSG 要件を偽装しない)。 - コミットの規律:今回のタスクに関連するファイルのみをステージングし、リポジトリ内の無関係な未コミット変更をコミットに巻き込まない。
- プログレッシブエンハンスメント:既に動作しているアニメーションコンポーネントを「スタイルを統一する」ために変更しない。要件とアクセシビリティの証拠に基づいて判断する。