Design & Motion · iart-ai/web-animation-skills

gsap-web

Name: gsap-web
Author: iart-ai/web-animation-skills

This skill should be used when the user asks to "build a scroll animation", "add ScrollTrigger", "pin a section while scrolling", "scrub an animation to scroll", "create a hero timeline", "do a horizontal scroll section", "split text and animate words", "animate a layout change with GSAP Flip", "sync ScrollTrigger with Lenis", "Lenis smooth scroll jittery", "ScrollTrigger markers drift", "ScrollTrigger pins break with Lenis/Locomotive", or "set up smooth scroll with GSAP pinning". Covers GSAP timelines, ScrollTrigger, SplitText, Flip, and Lenis/Locomotive smooth-scroll sync for code-driven web motion.

L3 Networked · Declare domain & key scopeV1 Commit-PinnedNetwork AccessWrite FileDual-pass Audit

Author iart-aiGitHub iart-ai/web-animation-skills ↗Stars 28License MIT（仓库根 LICENSE 为 MIT License, Copyright (c) 2026 iart.ai；.claude-plugin/plugin.json 的 license 字段同为 MIT）Commit b6dba3eb75

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Organize around a single master timeline: use a single playhead with relative position parameters and labels to choreograph multi-stage animations into an individually seekable unit.

skills/gsap-web/SKILL.md

Prefer one timeline over many independent tweens — it gives a single playhead, relative positioning, and easy reversal.

This is the exact prerequisite that enables subsequent ?t=N frozen-frame verification: only a single playhead allows deterministic seeking.

Drive scroll via the four core elements of ScrollTrigger (start/end/pin/scrub), emphasizing that scrubbed tweens must use ease: none for a linear 1:1 mapping with scroll progress.

skills/gsap-web/SKILL.md

start: "top top", // when trigger top hits viewport top

This section also covers the semantics of the four toggleActions callbacks, restricting markers to development mode, and performance cost considerations for ScrollTrigger.batch().

Lenis smooth scroll jitter, marker drift, and broken pins share a single root cause (two independent animation loops ticking separately); the solution is a unified loop where gsap.ticker drives Lenis and each Lenis scroll event updates ScrollTrigger.

skills/gsap-web/SKILL.md

lenis.on("scroll", ScrollTrigger.update); // 1. update ScrollTrigger on every Lenis scroll

Highlights the most common omission—unit conversion (gsap.ticker passes seconds, lenis.raf expects milliseconds, requiring * 1000)—and warns against running an extra custom rAF.

Use dedicated primitives for text reveals and layout transitions: SplitText (wait for font loading, apply overflow:hidden for line masks, invoke revert to restore DOM) and Flip (record state first, mutate DOM immediately, then animate the delta).

skills/gsap-web/SKILL.md

Always split AFTER web fonts load (`document.fonts.ready.then(...)`) to prevent wrong line breaks.

Both provide concrete failure modes detailing what goes wrong if not followed, rather than simply listing APIs.

Execute mandatory one-off teardown in SPAs and frameworks: use gsap.context() or ctx.revert() from useGSAP to clean up tweens, ScrollTrigger instances, and inline styles to prevent trigger leaks and ghost pin accumulation.

skills/gsap-web/SKILL.md

return () => ctx.revert(); // kills tweens, triggers, and reverts inline styles

Forms the unmount contract alongside Lenis cleanup via gsap.ticker.remove(update) and lenis.destroy().

2Core Capabilities

01Timeline orchestration (relative position parameters, labels, from/to/fromTo, quickTo for high-frequency tracking)

02Core ScrollTrigger mechanics (pinning with scrub, markers, toggleActions, batch, refresh)

03Single-loop synchronization for Lenis and Locomotive smooth scroll with ScrollTrigger (including scrollerProxy differences and four common bugs)

04SplitText reveal animations (line masking, font loading timing, autoSplit, revert)

05Flip layout transitions (grid/list switching, card expansion, cross-container reparenting)

06Easing quick reference (power/back/elastic/none/steps/CustomEase)

07Deliverable templates and freeze harness (CDN GSAP + master timeline + ?t=N, ready for standalone production use)

08Troubleshooting lookup table (symptom → root cause, covering Lenis synchronization issues in the field)

3External Dependencies

Kind	Dependency / Endpoint
package	gsap 及插件 ScrollTrigger / SplitText / Flip（正文口径：3.12+ 全部免费含商用）
network	交付模板从 cdnjs 取 GSAP（产物期引用，浏览器打开时拉取；执行期本 skill 不请求）
package	lenis（平滑滚动，与 ScrollTrigger 单循环同步；Locomotive 走 scrollerProxy 变体）
package	@gsap/react（useGSAP）与 React 清理路径
cli	npx / Playwright（宿主侧截图工具）与仓库根 scripts/ 助手（seek-shot.sh、contact-sheet.sh 依赖 ffmpeg）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Declare allowed domains and key scope

For Administrators

Least privilege keys, retain request logs

Evidence & Triggers (File Paths & Excerpts)

网络端点: Declared external network access: Zero outbound requests during execution; the deliverable template examples/standalone-template.html loads gsap 3.13.0 from cdnjs (runtime asset dependency, not execution-time egress)
本地工作目录: File I/O and artifact outputs: Zero disk writes within the skill directory; outputs 1 self-contained .html deliverable or user-project module written directly by the agent

Audit Notes: Grading is based strictly on the skill's own directory (skills/gsap-web/ = SKILL.md + 0-byte README.md + 2 reference docs + examples/{hero-timeline.js, standalone-template.html}, verified via find): no executable entry point directly executed by the agent (both examples are sample snippets and templates intended to be copied into deliverables, with no shebang or CLI usage), no credential reading, no disk writes, and zero outbound network traffic during execution. The entire directory contains only two URLs, both in the cdnjs script tags (GSAP 3.13.0) of examples/standalone-template.html; per Batch 4 guidelines, these count as artifact-level references that do not trigger an execution-time access rating and are listed purely as endpoints. The import gsap from 'gsap' in examples/hero-timeline.js represents user project dependencies (commented as npm i gsap @gsap/react), which likewise does not constitute outbound network activity by this skill.

5Second-Pass Verification

[unlocatable] GSAP 3.12+ 全部插件免费含商用这一许可声明是否可在源码内核实 — SKILL.md 首段声明 As of GSAP 3.12+, every plugin (ScrollTrigger, SplitText, Flip, MotionPath, MorphSVG, Draggable, Observer) is 100% free, including for commercial use. 但仓库内只有自身 MIT LICENSE，没有上游许可文件或链接，属外部事实声明，源码内不可复核，按文档声明记录。
[ok] Lenis 同步的乘 1000 单位换算与不要再开 rAF 是否前后一致 — SKILL.md 三段互相印证：接线代码 gsap.ticker.add((t) => lenis.raf(t * 1000))、Critical 段明写 ticker 传秒而 raf 要毫秒、Common bugs 段把 leftover requestAnimationFrame(raf) loop 列为抖动根因；references 的调试清单第 1、2 条同样指向这两点。
[ok] examples 里的两个文件是否真的可直接用 — hero-timeline.js 头注释给出所需 markup 与 CSS 前提（.line 需 overflow:hidden），并内置 document.readyState 自动启动；standalone-template.html 除 cdnjs GSAP 外无外部依赖，自带 ?t=N 冻结与 window.__ready，与 SKILL.md 的输出契约逐条对应。
[discrepancy] Packaged helper 的路径基准 — SKILL.md 写 scripts/seek-shot.sh anim.html 0 1.5 3，但 scripts/ 在仓库根而非本 skill 目录（目录内只有 examples/ 与 references/），单装形态下该相对路径不成立；好在 examples/standalone-template.html 自带 harness，可自给自足。

6Verdict & Scenarios

The only skill that unifies cross-library timing issues (GSAP ticker vs. Lenis rAF) into a single root cause, a single canonical wiring pattern, and a symptom-to-cause diagnostic table.

Most complete delivery and verification loop: template HTML includes built-in ?t=N freezing, window.__ready, and duration output.

Treats framework unmount contracts as mandatory (revert via context/useGSAP, ticker.remove with lenis.destroy).

Shares performance best practices with 60fps-animation (mutate only transform/opacity, remove will-change promptly, prefer batch over per-element triggers).

Best for: Best for: 1) Scroll-driven storytelling (pinning with scrub, parallax, horizontal scroll, progress-driven motion) and hero or landing pages with complex choreography; 2) Text line-reveal implementations or layout transitions (grid-to-list toggling, card expansions); 3) Projects using or adopting Lenis/Locomotive for smooth scrolling requiring correct synchronization with ScrollTrigger; 4) Zero-build delivery templates equipped with a freeze harness for instant screenshot-based verification.

Not for: Not suitable for: 1) Interfaces needing only a couple of simple hovers or basic entrances (use micro-interaction for micro-interactions); 2) Projects strictly forbidding third-party animation libraries in favor of platform-native capabilities (use 60fps-animation); 3) Accessibility-first tier degradation requirements (this skill only provides a basic reduced-motion gate; granular tiers belong in accessible-animation); 4) Throwaway single-use pages where framework unmount lifecycles do not need handling.

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload gsap-web.tar.gz

sha256: 1c57c75354a29de0…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit b6dba3eb75.