gsap-framer-scroll-animation

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

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

デザインの補完スキル： このスキルでは、スクロールに連動するモーションの技術的な実装を扱います。 アニメーションをどのように、いつ使うべきかを導くクリエイティブな考え方、デザイン原則、プレミアムな美しさについては、必ずpremium-frontend-uiスキルも参照してください。 2つを組み合わせることで、包括的なアプローチが実現します。premium-frontend-ui が何を、なぜ行うかを決め、このスキルがどのように実現するかを示します。

ライブラリのクイック選択

必要なもの	使用するもの
Vanilla JS、Webflow、Vue	GSAP
ピン留め、横スクロール、複雑なタイムライン	GSAP
React / Next.js、宣言的なスタイル	Framer Motion
whileInView による登場アニメーション	Framer Motion
同じ Next.js アプリで両方を使用	references の注記を参照

詳しいレシピと 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); // MUST call before any ScrollTrigger usage

Framer Motion（Motion v12、2025）

npm install motion   # new package name since mid-2025
# or: npm install framer-motion  — still works, same API

import { motion, useScroll, useTransform, useSpring } from 'motion/react';
// legacy: import { motion } from 'framer-motion'  — also valid

ワークフロー

1. ユーザーの意図を解釈し、GSAP と Framer Motion のどちらが適しているか判断します。
2. 詳細な API とパターンについて、references/ 内の該当するリファレンスドキュメントを読みます。
3. 必要なパッケージがまだ導入されていない場合は、インストールを提案します。
4. 指定された形式（React コンポーネント、フックの要件、Vanilla JS）に沿って、アニメーション構造の骨組みを実装します。
5. 適切なツール（スクロール連動か、ビューポート内の要素か）を適用し、アクセシビリティに関するオプションを設定するとともに、フックによる無限再レンダリングを防ぎます。

よく使われる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：使用前に必ず gsap.registerPlugin(ScrollTrigger) を呼び出します
• GSAP のスクラブ：必ず ease: 'none' を使用します — スクラブ中のイージングは不自然に感じられます
• GSAP React：@gsap/react の useGSAP を使い、通常の useEffect は使用しません — ScrollTrigger が自動的にクリーンアップされます
• GSAP のデバッグ：開発中は markers: true を追加し、本番環境に移行する前に削除します
• Framer：useTransform の出力は通常の div ではなく、motion.* 要素の style prop に渡します
• 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 と whileInView のどちらか）、offset の値、変換する対象を必ず指定します
• /fix を使う際は、正確なエラーメッセージを貼り付けます — 実際のエラーがあると、Copilot の修正精度は大幅に向上します
• Copilot Chat では @workspace スコープを使い、既存のコンポーネント構造を読み込ませます

リファレンスファイル

ファイル	内容
references/gsap.md	ScrollTrigger API の完全なリファレンス、10個のレシピ、React（useGSAP）、Lenis、matchMedia、アクセシビリティ
references/framer.md	useScroll / useTransform API の完全なリファレンス、8個のレシピ、variants、Motion v12 の注記、Next.js のヒント

関連スキル

スキル	関連性
premium-frontend-ui	クリエイティブな理念、デザイン原則、美的ガイドライン — アニメーションを いつ、なぜ 使うかを定義します