GSAP & Framer Motion — スクロールアニメーションスキル

GitHub Copilot プロンプト、すぐに使えるコードレシピ、深い API リファレンスを備えた本番環境レベルのスクロールアニメーション。

デザインコンパニオン: このスキルは、スクロール駆動モーションの 技術的実装 を提供します。 創造的な哲学、デザイン原則、プレミアムな美学については、常に premium-frontend-ui スキルを参照してください。 このスキルがアニメーション化する 方法 と 時期 に関する創造的なガイダンスを定義します。 一緒に完全なアプローチを形成します。premium-frontend-ui が 何を なぜ アニメーション化するかを決定し、 このスキルが どのように 実装するかを提供します。

クイックライブラリセレクタ

必要な場合	使用
バニラ JS、Webflow、Vue	GSAP
ピン留め、水平スクロール、複雑なタイムライン	GSAP
React / Next.js、宣言的なスタイル	Framer Motion
whileInView エントランスアニメーション	Framer Motion
同じ Next.js アプリで両方を使用	リファレンスのノートを参照

完全なレシピと Copilot プロンプトについては、関連するリファレンスファイルを読んでください:

• GSAP → references/gsap.md — ScrollTrigger API、すべてのレシピ、React 統合
• Framer Motion → references/framer.md — useScroll、useTransform、すべてのレシピ

セットアップ (必ず最初に行う)

GSAP

npm install gsap

import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
gsap.registerPlugin(ScrollTrigger); // ScrollTrigger 使用前に必ず呼び出す

Framer Motion (Motion v12、2025)

npm install motion   # 2025 年中盤以降の新しいパッケージ名
# または: npm install framer-motion  — 従来のまま、同じ API で機能

import { motion, useScroll, useTransform, useSpring } from 'motion/react';
// レガシー: import { motion } from 'framer-motion'  — これも有効

ワークフロー

1. ユーザーの意図を解釈して、GSAP または Framer Motion のどちらが最適かを特定します。
2. references/ にある関連リファレンスドキュメントを読んで、詳細な API とパターンを確認します。
3. まだパッケージがインストールされていない場合は、必要なパッケージのインストールを提案します。
4. リクエストされた形式 (React コンポーネント、フック要件、またはバニラ JS) に準拠して、アニメーション構造のスキャフォルドを実装します。
5. 正しいツール (スクロール vs ビュー内の要素) を適用し、アクセシビリティオプションが存在し、フックが無限再レンダリングを引き起こさないことを確認します。

最も一般的なスクロールパターン 5 つ

クイックリファレンス — Copilot プロンプト付きの完全なレシピはリファレンスファイルに含まれています。

1. 入場時のフェードイン (GSAP)

gsap.from('.card', {
  opacity: 0, y: 50, stagger: 0.15, duration: 0.8,
  scrollTrigger: { trigger: '.card', start: 'top 85%' }
});

2. 入場時のフェードイン (Framer Motion)

<motion.div
  initial={{ opacity: 0, y: 40 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: '-80px' }}
  transition={{ duration: 0.6 }}
/>

3. スクラブ / スクロールリンク (GSAP)

gsap.to('.hero-img', {
  scale: 1.3, opacity: 0, ease: 'none',
  scrollTrigger: { trigger: '.hero', start: 'top top', end: 'bottom top', scrub: true }
});

4. スクロールリンク (Framer Motion)

const { scrollYProgress } = useScroll({ target: ref, offset: ['start end', 'end start'] });
const y = useTransform(scrollYProgress, [0, 1], [0, -100]);
return <motion.div style={{ y }} />;

5. ピン留めタイムライン (GSAP)

const tl = gsap.timeline({
  scrollTrigger: { trigger: '.section', pin: true, scrub: 1, start: 'top top', end: '+=200%' }
});
tl.from('.title', { opacity: 0, y: 60 }).from('.img', { scale: 0.85 });

重要なルール (常に適用)

• GSAP: ScrollTrigger 使用前に必ず gsap.registerPlugin(ScrollTrigger) を呼び出す
• GSAP scrub: 常に ease: 'none' を使用 — scrub がアクティブな場合、イージングは不自然に見える
• GSAP React: @gsap/react の useGSAP を使用、プレーンな useEffect は決して使用しない — ScrollTrigger を自動的にクリーンアップ
• GSAP デバッグ: 開発中は markers: true を追加; 本番環境では削除
• Framer: useTransform 出力は motion.* 要素の style プロップに配置される必要があり、プレーン div ではない
• Framer Next.js: motion フックを使用するファイルの先頭に常に 'use client' を追加
• 両方: transform と opacity のみをアニメーション化 — width、height、box-shadow は避ける
• アクセシビリティ: 常に prefers-reduced-motion をチェック — 各リファレンスファイルでパターンを参照
• プレミアムポーランド: premium-frontend-ui スキルの原則に従ってモーションタイミング、イージング曲線、控えめさを確保 — アニメーションは強化すべきで、決して圧倒されない

Copilot プロンプトのヒント

• Copilot に完全なセレクタ、ベース画像、スクロール範囲を前もって提供 — 曖昧なプロンプトは曖昧なコードを生成
• GSAP の場合、常に指定: セレクタ、start/end 文字列、scrub または toggleActions が必要かどうか
• Framer の場合、常に指定: どのフック (useScroll vs whileInView)、オフセット値、何を変換するか
• /fix で質問する場合、正確なエラーメッセージを貼り付け — Copilot の修正は実際のエラーがあるとはるかに優れている
• Copilot Chat で @workspace スコープを使用して、既存のコンポーネント構造を読む

リファレンスファイル

ファイル	内容
references/gsap.md	完全な ScrollTrigger API リファレンス、10 のレシピ、React (useGSAP)、Lenis、matchMedia、アクセシビリティ
references/framer.md	完全な useScroll / useTransform API、8 つのレシピ、バリアント、Motion v12 のノート、Next.js のヒント

関連スキル

スキル	関係
premium-frontend-ui	創造的な哲学、デザイン原則、美的ガイドライン — アニメーション化する 時期 と 理由 を定義