Communitygithub.com

gsap-motion

GSAP 3 アニメーションアーキテクチャ:プラグインレジストリ(ScrollTrigger, SplitText, Flip, Observer, Draggable, Inertia, CustomEase, MorphSVG, DrawSVG — すべて公開パッケージで無料)、useGSAP による React 統合、レスポンシブ・モーション軽減分岐、タイムライン、スクロール連動ピン留め、テキストリビール、クリップパス・マスクトランジション、Flip レイアウトモーフ、水平スクロール、パララックス、マグネティック・カーソルエフェクト、ページトランジションに対応。GSAP や ScrollTrigger を使用するあらゆる場面、スクロール駆動・シネマティックアニメーション、ルート変更やリサイズ後にアニメーションがリーク・重複・カクつき・壊れる問題に。

gsap-motion とは?

gsap-motion は、React 環境で GSAP 3 のアニメーションを安全かつ効率的に構築するためのアーキテクチャと実装パターンを提供するスキルです。主に汎用の AI コーディングエージェント(Claude Code, Cursor, Codex など)向けに設計されています。 このスキルの核心は、GSAP の全プラグイン(ScrollTrigger, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, MorphSVGPlugin, DrawSVGPlugin など)が無料で利用できるという事実に基づいた、リークや競合のない実装ルールにあります。具体的には、`useGSAP` フックによるスコープ管理、`gsap.matchMedia` によるレスポンシブ・モーション軽減分岐、ScrollTrigger のクリーンアップルール、レイアウト変更後のリフレッシュ戦略など、90% の GSAP バグを未然に防ぐ 8 つのルールを定義しています。 また、`assets/` ディレクトリに配置可能なテンプレートファイル群(プラグインレジストリ、モーショントークン、テキストリビール、モーション軽減フック、実装例)が含まれており、すぐにプロジェクトに取り込める構成になっています。さらに、シネマティックヒーロー、テキストリビール、ピン留めスクロールストーリーテリング、水平スクロール、パララックス、Flip モーフ、マグネティックボタン、ページトランジションなど、豊富なレシピ集も提供します。 このスキルは、ルート変更後やリサイズ時にアニメーションがリーク・重複・カクつく問題を解決し、プロフェッショナルな Web サイト向けの高品質なアニメーションを実現するためのベストプラクティス集です。

対応~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jakyherr05-hash/Claude-code-skill/tree/HEAD/plugins/premium-web-studio/skills/gsap-motion

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

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

ドキュメント

GSAP モーションアーキテクチャ

検証済みベースライン (2026-11-15)

  • [email protected] が npm で最新です。ライセンスは「Standard 'no charge' license」(gsap.com/standard-license) で、商用サイト(クライアントワークを含む)で無料で使用できます。唯一の禁止用途は、Webflow と競合するノーコードビジュアルアニメーションビルダーツールの構築です。すべてのプラグインは公開パッケージに同梱されています:ScrollTrigger, ScrollSmoother, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, CustomBounce, CustomWiggle, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin, ScrambleTextPlugin, ScrollToPlugin, Physics2D, PhysicsProps, GSDevTools など。
  • @gsap/[email protected] が useGSAP を提供します。
  • 新規プロジェクトの前に再確認: npm view gsap version license および ls node_modules/gsap/*.js。
  • ScrollSmoother または Lenis のいずれかを使用し、両方は使用しないでください。このスタジオでは Lenis を標準とします(lenis-scroll スキル参照)。

アーキテクチャ (assets/ を src/motion/ にコピー)

ファイル役割
assets/registry.tsプラグインを一度だけ登録し、プロジェクトの CustomEase を作成し、デフォルトを設定し、ScrollTrigger.config({ ignoreMobileResize: true }) を実行します。すべてのモジュールはここから gsap をインポートします。
assets/tokens.tsモーショントークン(duraton, ease, stagger)を ANIMATION_SPECIFICATION.md からミラーリング + prefersReducedMotion()
assets/lit.ts再利用可能なテキストプリミティブの例:SplitText を aria:'auto'、autoSplit、onSplit で使用し、トゥイーンを返します。リビールをブランドに合わせて調整します(lit、masked、 slid…)。
assets/useReducedMotion.tsDOM レベルでのスイッチ(例:ピンの代わりに静的ステップをレンダリング)のためのライブ prefers-reduced-motion フック
assets/examples/*.tsx参照デモからテスト済みのパターン:ピン留めスクラブシーケンス(Method)、Flip フィルター(ScheduleIndex)、quickTo 駆動インタラクティブ(TheHour)、一度だけリビール(Rooms)、ルートトランジションベール(Router)

これらのファイルは、このリポジトリの demo/ からの検証済み実装であり、Playwright スイート(ルート間のクリーンアップ、モーション軽減、スクロール同期)でテストされています。

React での GSAP バグの 90% を防ぐルール

  1. すべてのアニメーションは useGSAP(() => {...}, { scope: ref }) 内に記述します。このコンテキストは、アンマウント時にすべてのトゥイーン、ScrollTrigger、SplitText、matchMedia ブランチを元に戻します。イベントハンドラ内のアニメーションには contextSafe を使用します。
  2. モジュールスコープやプレーンな useEffect 内で ScrollTrigger を作成しないでください(元に戻さない場合)。クリーンアップ戦略として ScrollTrigger.killAll() を呼び出さないでください。
  3. セクションごとに一つの gsap.matchMedia() を motion/reduce(およびデスクトップ/モバイル)条件で使用します。初期の非表示状態はmotionブランチ内で設定します。これにより、no-JS およびモーション軽減ユーザーには最終コンテンツが表示されます。
  4. Strict Mode 対応: useGSAP は React 18/19 の二重呼び出しを処理します。リークチェックで確認:ScrollTrigger.getAll().length が、ページ遷移および戻った後にベースラインに戻っていること。
  5. レイアウト変更後にリフレッシュ: フォント読み込み後(document.fonts.ready.then(() => ScrollTrigger.refresh()))、リストフィルタリング後、ルートコンテンツマウント後。トリガーの値がレイアウトから計算される場合は、invalidateOnRefresh: true を使用します。
  6. 正しくピン留め: 内側のラッパーをピン留めし、pinSpacing を維持し、Web フォントに依存しない min-height: 100svh を設定し、Lenis で anticipatePin: 1 を使用します。エクスペリエンスごとに一つのピンを使用します。ピンを積み重ねるとユーザーが混乱します。
  7. 軽量なプロパティをアニメーション: transform、opacity、clip-path;小さなサブツリーでのみ CSS 変数を使用します。スクラブタイムラインでは width/height/top/left を避け、書き込みの前にレイアウトを読み取ります(GSAP は自身の書き込みをバッチ処理します)。
  8. will-change はアニメーション中のみ、そして少数のレイヤーにのみ適用します。

レシピ

references/recipes.md には、テスト済みまたは文書化されたパターンが含まれます:シネマティックヒーローシーケンス、SplitText リビール(文字/単語/行、マスク)、クリップパスおよびマスクトランジション、ピン留めスクラブストーリーテリング、水平スクロールセクション(containerAnimation)、パララックスレイヤー、Flip ステートモーフ、Observer 駆動ジェスチャーセクション、Draggable + Inertia カルーセル、マグネティックボタン、カーソルフォロワー、SVG モーフ/ドロー、WebGL への画像ディストーションハンドオフ、ページトランジション、WebGL カメラによる 3D スクロール。

references/react-lifecycle.md では、ルート変更、リサイズ、コンテンツ変更、デバッグリークについて説明しています。

目的のあるモーションチェックリスト(アニメーション前に)

  • このアニメーションは何を伝えますか(階層、因果関係、状態、ブランド素材)?何もなければ削除します。
  • それは印象的な瞬間ですか、それとも控えめであるべきですか?
  • モーション軽減時には代わりに何を表示しますか?(完全に理解可能である必要があります。)
  • モバイルでの表現は?(ホバーエフェクトにはタッチ用の代替が必要です;ピンは短くなります。)
  • ページはいくつの ScrollTrigger を作成しますか?仕様書にインベントリを書き、QA がアサートできるようにします。

関連スキル