Communitygithub.com

erlinerd/erlin-skills

Next.js/React サイトに motion アニメーションライブラリを導入し、framer-motion からの移行、スクロールリビール、スタッガーグリッド、ページトランジション、ナビゲーションアニメーションを実装します。SwiftUI、CSS-only、Remotion ビデオアニメーションは対象外です。

erlin-skills とは?

このスキルは、Next.js/React サイト向けに motion アニメーションライブラリ (framer-motion の後継) を導入・移行し、スクロールリビール、スタッガーグリッド、ページトランジション、ナビゲーションアニメーションなどのアニメーション効果を実装するためのものです。なぜこれが便利かというと、これらのアニメーションを「コンテンツを決して隠さない」という原則の下で安全に実装できるからです。主なプラットフォームは Next.js (App Router / Pages Router) と React です。仕組みとしては、まずプロジェクトのパッケージマネージャー、Next/React のバージョン、ルーター構造を自動検出し、既存の framer-motion を必要に応じて motion に移行します。その後、IntersectionObserver ベースの Reveal コンポーネント(assets/reveal.tsx テンプレート)を使ってスクロールリビールやスタッガーアニメーションを適用し、ページトランジションは App Router の template.tsx にフェードイン効果を追加します。すべてのアニメーションは prefers-reduced-motion を尊重し、SSR やハイドレーション失敗時もコンテンツが常に表示されるように可視性フォールバックが組み込まれています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

目標

Erlin の個人サイトのアニメーション手法:Next.js/React サイトに motion アニメーションライブラリを導入し、framer-motion からの移行、スクロールリビール / スタッガーグリッド / ページトランジション / ナビゲーションアニメーションを実装します。ただし、アニメーションでコンテンツを決して隠さないことが絶対条件です。重要な教訓:whileInView がトップページのプロジェクトカードを opacity:0 で固定してしまったことがあります(「プロジェクトカードが消えた」)。そのため、可視性のフォールバックが必要です。既に信頼できる実装がある場合はそれを保持し、Reveal はオプションの参考として使用し、whileInView を全面的に禁止するわけではありません。

実行手順

  1. まずプロジェクト環境を判断する(手を動かす前に 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 要素は最小限のクライアントコンポーネントに隔離する。サーバーロジックを含むコンポーネント全体をクライアントコンポーネントに変更しない。
  2. 既存の依存関係をそのまま使用する:既に framer-motion が導入されており、要件を満たしている場合は引き続き使用し、新しいアニメーションを追加するためにデフォルトで移行しない。ユーザーから移行の要求があるか、現在の機能や互換性に本当に問題がある場合のみ、バージョンの違いを確認した上でプロジェクトのパッケージマネージャーを使用して motion をインストールし、motion/react のインポートと API を一つ一つ確認する。残存する依存関係がないことを確認してから古いパッケージを削除する。関連のないコメントやドキュメントを手当たり次第に変更しない。

  3. アニメーションを実装する:必要に応じて 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 で外側をラップし、セマンティクスを維持する。
  4. 適用場所とスタッガー公式:

    場所方法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 秒—
  5. 検証と納品:手順 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 には instant prop があるか、初期状態を最終状態にしておく。そうしないと 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 を導入する必要はない。
    • クライアント側フィルタリング(タグフィルターなど)では、キーが変わらないリストアイテムはアニメーションを再生しない——これは期待される動作であり、新しく表示されるアイテムが自動的にトリガーされる。
  • 既存コンポーネントの帰属: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 要件を偽装しない)。
  • コミットの規律:今回のタスクに関連するファイルのみをステージングし、リポジトリ内の無関係な未コミット変更をコミットに巻き込まない。
  • プログレッシブエンハンスメント:既に動作しているアニメーションコンポーネントを「スタイルを統一する」ために変更しない。要件とアクセシビリティの証拠に基づいて判断する。

関連スキル