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.ts | DOM レベルでのスイッチ(例:ピンの代わりに静的ステップをレンダリング)のためのライブ prefers-reduced-motion フック |
assets/examples/*.tsx | 参照デモからテスト済みのパターン:ピン留めスクラブシーケンス(Method)、Flip フィルター(ScheduleIndex)、quickTo 駆動インタラクティブ(TheHour)、一度だけリビール(Rooms)、ルートトランジションベール(Router) |
これらのファイルは、このリポジトリの demo/ からの検証済み実装であり、Playwright スイート(ルート間のクリーンアップ、モーション軽減、スクロール同期)でテストされています。
React での GSAP バグの 90% を防ぐルール
- すべてのアニメーションは
useGSAP(() => {...}, { scope: ref })内に記述します。このコンテキストは、アンマウント時にすべてのトゥイーン、ScrollTrigger、SplitText、matchMedia ブランチを元に戻します。イベントハンドラ内のアニメーションにはcontextSafeを使用します。 - モジュールスコープやプレーンな
useEffect内で ScrollTrigger を作成しないでください(元に戻さない場合)。クリーンアップ戦略としてScrollTrigger.killAll()を呼び出さないでください。 - セクションごとに一つの
gsap.matchMedia()をmotion/reduce(およびデスクトップ/モバイル)条件で使用します。初期の非表示状態はmotionブランチ内で設定します。これにより、no-JS およびモーション軽減ユーザーには最終コンテンツが表示されます。 - Strict Mode 対応:
useGSAPは React 18/19 の二重呼び出しを処理します。リークチェックで確認:ScrollTrigger.getAll().lengthが、ページ遷移および戻った後にベースラインに戻っていること。 - レイアウト変更後にリフレッシュ: フォント読み込み後(
document.fonts.ready.then(() => ScrollTrigger.refresh()))、リストフィルタリング後、ルートコンテンツマウント後。トリガーの値がレイアウトから計算される場合は、invalidateOnRefresh: trueを使用します。 - 正しくピン留め: 内側のラッパーをピン留めし、
pinSpacingを維持し、Web フォントに依存しないmin-height: 100svhを設定し、Lenis でanticipatePin: 1を使用します。エクスペリエンスごとに一つのピンを使用します。ピンを積み重ねるとユーザーが混乱します。 - 軽量なプロパティをアニメーション: transform、opacity、clip-path;小さなサブツリーでのみ CSS 変数を使用します。スクラブタイムラインでは width/height/top/left を避け、書き込みの前にレイアウトを読み取ります(GSAP は自身の書き込みをバッチ処理します)。
will-changeはアニメーション中のみ、そして少数のレイヤーにのみ適用します。
レシピ
references/recipes.md には、テスト済みまたは文書化されたパターンが含まれます:シネマティックヒーローシーケンス、SplitText リビール(文字/単語/行、マスク)、クリップパスおよびマスクトランジション、ピン留めスクラブストーリーテリング、水平スクロールセクション(containerAnimation)、パララックスレイヤー、Flip ステートモーフ、Observer 駆動ジェスチャーセクション、Draggable + Inertia カルーセル、マグネティックボタン、カーソルフォロワー、SVG モーフ/ドロー、WebGL への画像ディストーションハンドオフ、ページトランジション、WebGL カメラによる 3D スクロール。
references/react-lifecycle.md では、ルート変更、リサイズ、コンテンツ変更、デバッグリークについて説明しています。
目的のあるモーションチェックリスト(アニメーション前に)
- このアニメーションは何を伝えますか(階層、因果関係、状態、ブランド素材)?何もなければ削除します。
- それは印象的な瞬間ですか、それとも控えめであるべきですか?
- モーション軽減時には代わりに何を表示しますか?(完全に理解可能である必要があります。)
- モバイルでの表現は?(ホバーエフェクトにはタッチ用の代替が必要です;ピンは短くなります。)
- ページはいくつの ScrollTrigger を作成しますか?仕様書にインベントリを書き、QA がアサートできるようにします。