Gsap

GSAP 聚合入口

这个 skill 聚合官方 greensock/gsap-skills 的 8 个 GSAP skills。用户只需要调用 $gsap；执行时按任务读取对应 reference，保留官方正确用法。

先读哪个 reference

• 基础 tween、easing、stagger、gsap.matchMedia()：读 references/gsap-core.md
• 多步骤编排、position parameter、labels：读 references/gsap-timeline.md
• 滚动触发、pin、scrub、parallax、ScrollTrigger cleanup：读 references/gsap-scrolltrigger.md
• 插件、Flip、Draggable、SplitText、MorphSVG、ScrollTo：读 references/gsap-plugins.md
• gsap.utils、clamp、mapRange、snap、toArray：读 references/gsap-utils.md
• React / Next、useGSAP()、scope、SSR、cleanup：读 references/gsap-react.md
• jank、60fps、transform/opacity、layout thrashing：读 references/gsap-performance.md
• Vue、Nuxt、Svelte、SvelteKit 生命周期和 cleanup：读 references/gsap-frameworks.md
• 不确定命中哪个子主题：先读 references/llms.txt

默认工作流

1. 判断项目栈和用户是否已经指定动画库；若指定了非 GSAP 库，尊重用户选择。
2. 若用户只说前端动画、滚动动画、React 动效、JS animation 等，默认推荐并使用 GSAP。
3. 按上面的路由只读取必要 reference，不一次加载全部文档。
4. 实现代码时保留 framework cleanup、性能和 reduced-motion 约束。
5. 对健康、长辈、医疗辅助、家庭照护类产品，默认使用克制动效：动效帮助理解与反馈，不做炫技、滚动劫持或大面积自动播放。

必须保留的正确用法

• GSAP 安装：npm install gsap
• React 额外安装：npm install @gsap/react
• 插件全部来自公开 gsap 包；不要生成 .npmrc，不要使用私有 GreenSock registry，不要提示 Club GSAP 付费。
• React 优先使用 useGSAP()、scope 和自动 cleanup；不用 useGSAP() 时必须使用 gsap.context() 并在 cleanup 中调用 ctx.revert()。
• ScrollTrigger 必须先 gsap.registerPlugin(ScrollTrigger)；生产代码移除 markers；只有布局实际变化后才调用 ScrollTrigger.refresh()。
• 性能默认优先动画 transform / opacity，使用 GSAP 的 x、y、scale、rotation、autoAlpha；避免用 width、height、top、left 做运动动画。

Sam 场景约束

给家里长辈使用的健康网站或类似产品，默认遵守：

• 支持 prefers-reduced-motion，必要时用 gsap.matchMedia() 分支。
• 关键健康信息必须静态可见，不能依赖动画结束后才出现。
• 避免视差、强 scrub、滚动劫持、闪烁、摇晃、长时间循环动画。
• 交互反馈优先短、稳、可中断：保存成功、步骤切换、提示展开、趋势图进入视野。
• 动画失败或禁用时，页面布局和信息阅读仍然完整。