gsap-vanilla

GSAP Vanilla

マウント → 初期状態 → イントロ → 安定状態 → アウトロ → 最終状態 → アンマウント

ドキュメント全体を読み込む場合、マウントとアンマウントはブラウザーが担当し、その間の5つのフェーズはアニメーションが担当します。同一ドキュメント内でページを切り替える場合、ノードの置き換えはルーターが担当し、永続的なリソースは明示的にクリーンアップする必要があります。

求められている見た目と既存のプロジェクト規約を維持してください。必要に応じて GSAP／プラグインを追加し、依頼がない限り、選択済みのアニメーションライブラリを置き換えないでください。

このスキルでは、モーションを実行するタイミングを決めます。何を動かすか、またプレミアムや遊び心のある雰囲気にする方法については、animaxxing スキルがインストールされている場合はそちらも読み込んでください。レシピと雰囲気の見つけ方を解説するガイドを、このライフサイクルに組み込めます。

プロジェクトの現状を確認する

リポジトリの指示、既存のアニメーション、レイアウト、ナビゲーション、CSS、アクセシビリティの規約、チェック方法を確認してください。そのうえで、次の手順に進みます。

1. ページの生成方法を確認します。手書きの HTML、クライアントフレームワークを使わない静的ジェネレーター、UI フレームワークを使わない Vite などのバンドラー、Swup、Barba、Taxi などのトランジションライブラリのいずれかです。コンポーネントフレームワークがページをレンダリングしている場合、このスキルの対象外であることを伝え、そのフレームワークのスキルを使用してください。
2. GSAP の読み込み方法を確認します。npm インポート、インポートマップ、スクリプトタグのいずれかです。現在の方法を維持してください。
3. スクリプトの実行方法を確認します。インライン、defer、type="module" のいずれかです。これによって DOM が存在するタイミングと、スクリプト実行前にページが描画されるかどうかが決まります。
4. 対象ブラウザーを確認します。クロスドキュメントの View Transitions、pageswap と pagereveal、Navigation API、blocking="render" は、すべてのブラウザーで使えるわけではありません。記憶に頼らず、インストール済みのトランジションライブラリのドキュメントや型を確認し、ブラウザー API は機能検出してください。また、これらがすべて利用できない場合でもサイトが動作することを確認してください。

ナビゲーションモデルを選ぶ

ライフサイクルのコードを書く前に、ナビゲーションモデルを特定してください。ナビゲーションごとに担当する主体を1つに定めます。同一ドキュメント内のルーターでも、完全な再読み込みへのフォールバックが必要な場合があります。

• ドキュメント全体の読み込み。 リンクをたどるたびにドキュメント全体が置き換わります。リンクをたどる前にアウトロを再生し、新しいページの読み込み時にイントロを再生します。これがデフォルトで、ルーターは不要です。
• クロスドキュメントの View Transitions を使ったドキュメント全体の読み込み。 ブラウザーが古いページをスナップショットし、新しいページへアニメーションします。GSAP では、スナップショットのペアだけでは実現できない部分を補います。
• 同一ドキュメント内のナビゲーション。 スクリプトが次のページを取得してコンテンツをその場で置き換えるため、ブラウザーの共通部分、状態、タイムラインは維持されます。プロジェクトがすでにルーターを管理している場合や、ルーターを使う理由がある場合を除き、メンテナンスされているライブラリを使用してください。同一ドキュメント内のナビゲーションを参照してください。

エンジンを選ぶ

スナップショットのモーフィングやページのクロスフェードには、瞬時に切り替えるフォールバックを備えたクロスドキュメントの View Transitions を使用してください。ナビゲーションを制御するライブ DOM のアウトロ、中断可能なシーケンス、分割テキスト、スクロール連動のモーションには GSAP を使用してください。要素ごとにエンジンは1つにしてください。エンジンの併用を参照してください。

必要な箇所だけ読む

• 見えないイントロ、初期化の失敗、インデックス作成、初回読み込みのパフォーマンスについては、初期化と復旧と、フレームワークとの統合を参照してください。
• 初回描画、スクリプトのタイミング、フォント、ナビゲーションの種類、プリレンダリング、bfcache、非表示のタブ、アウトロ中にページを離れる動作については、ページの読み込みとアンロードを参照してください。
• @view-transition、pageswap、pagereveal、タイプ、レンダリングのブロック、ブラウザーと GSAP 間の引き継ぎについては、ドキュメント間のナビゲーションを参照してください。
• Fetch と swap を使うルーター、リンクのインターセプト、履歴、スクロール、フォーカス、スクリプトの再実行、ライブラリを使うべき場合については、同一ドキュメント内のナビゲーションを参照してください。
• 5 つのフェーズ、GSAP のセットアップ、コンテキスト、表示と非表示、レイアウトの安定性、スクロール、テキスト、プラグインについては、ライフサイクルの実装を参照してください。
• ドキュメント間やスワップ中の Lenis、ScrollSmoother、またはイージングを加えたページスクロールについては、スムーズスクロール、ドキュメント単位のスクローラー、およびスワップルーターで 1 つのスクローラーを使う方法を参照してください。
• カーテン、初回訪問時のプリローダー、共有要素のモーフィングについては、トランジションの典型パターン、およびドキュメント全体と同一ドキュメント内の統合を参照してください。
• タッチ、ビューポートの変更、デバイスの予算については、デバイスと入力を参照してください。
• 作業完了と判断する前に、検証を参照してください。

このリポジトリと併せて、GSAP 公式スキルをインストールしてください。API の詳細には gsap-core を読み込み、必要に応じて関連するプラグインスキルのみを読み込んでください。

ルール

• セットアップが成功した場合は、見えないイントロを維持してください。失敗した場合は、現在の表示対象を復旧してください。非表示にするルールを追加する前に、初期化の契約に従ってください。
• GSAP は対象の DOM が存在してから実行してください。gsap.context を使い、セレクターの範囲をページまたはコンポーネントのルートに限定してください。所有対象がなくなるときは、すべてのトゥイーン、トリガー、分割、リスナーをクリーンアップしてください。
• 最終的なジオメトリは通常の CSS と安定したラッパーで確保し、レイアウト領域を二重に増やさずに、退出するコンテンツと入ってくるコンテンツを重ねてください。
• 最初の描画より前に初期値を設定してから表示してください。初期化が成功した場合、イントロの前に表示完了状態のコンテンツが一瞬見えることはなく、JavaScript がなくてもページが白紙になることはありません。
• 表示完了時に一時的なスタイルをクリアしてください。will-change はアニメーション中だけ使い、gsap-performance の静的なヒントを上書きします。
• デバイスの階層には機能クエリを使ってください。タッチ状態は解除され、コントロールはホバーなしでも動作するようにしてください。
• アウトロと終了状態の間は、退出するコンテンツを DOM 内に保持し、表示したままにしてください。リンクの遷移、ノードの削除、またはスワップは、終了時のコールバックからのみ実行してください。
• 戻る操作と進む操作では、アウトロを実行しないでください。履歴から開いた新しいドキュメントではイントロのみの経路を使い、bfcache から復元した場合はイントロを一切実行しないでください。
• プリレンダリングされたページでは初期状態をすぐに設定し、アニメーションの開始前に有効化を待ってください。
• ネイティブのリンク動作、フォーカス、スクロール位置の復元、JavaScript がなくても読みやすいことを維持してください。
• アニメーションのために unload または beforeunload リスナーを追加しないでください。これらは bfcache を無効にします。pagehide を使ってください。
• 視覚効果を減らす設定でも同じ表示完了状態に到達し、すべての完了コールバックを実行してください。
• 割り込みと連続クリック時の動作を定義し、完了時にナビゲーションの待機を必ず 1 回だけ解除してください。
• 可能であれば、再読み込み、戻る、進む、バックグラウンドタブからのクリックも含め、実際のブラウザーで検証してください。