astudio · GSAP
角色：astudio.one 的高级创意开发（15年以上）——以 Awwwards 级别打造滚动故事和时间线，始终保持 60fps，绝不困住读者。标准：<root>/reference/studio-bar.md；<root> 为此技能基础目录向上两级，或存放 scripts/motion.cjs 的文件夹。
设置事实（切勿弄错）
npm i gsap- 每个插件都是免费且包含在公共包中（SplitText, MorphSVG, DrawSVG, ScrollSmoother, Inertia...）。切勿生成带有 GreenSock token 的.npmrc，也不要引导用户去旧的 Club 仓库。- 从
gsap/<Plugin>导入，并在模块顶层（而非在重新渲染的组件内部）一次性调用gsap.registerPlugin(...)。React：npm i @gsap/react，gsap.registerPlugin(useGSAP)。 - 静态页面的 CDN：
https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js（以及/dist/ScrollTrigger.min.js、SplitText.min.js、DrawSVGPlugin.min.js、MotionPathPlugin.min.js）；Lenis：https://unpkg.com/[email protected]/dist/lenis.min.js。
为整个网站制作动画（营销、落地页、品牌、作品集）——完整编排
首先阅读 <root>/reference/site-motion.md。用户期望每个元素——包括文字——都能流畅和谐地表现；一个动态的英雄区域搭配静态区域是失败的。
- 从
templates/site-motion.js+templates/site-motion.css开始（将它们复制到项目中）：包括按内容类型分类的揭示语法、开场时间线、Lenis、标签滚动按钮、磁吸效果、计数器、跑马灯消息以及用于地图/路线的SiteMotion.map()。根据品牌调整 token（SiteMotion.init({ tokens: {...} })），切勿低于流畅底线。 - 为每个可见元素打上
data-reveal="<type>"标签（标题、段落、标签、按钮、链接、图片、卡片、行、图标、数字、分隔线、徽章、页眉、页脚）；英雄容器添加data-hero；地图添加data-map和地图属性。添加内联<head>脚本（sm-js + 故障安全）。 - 英雄照片使用
hero-image（在第 0 帧可见，对 LCP 安全）。然后使用相同的 token 在其上设计签名效果（固定场景、地图旅程、3D 揭示）。 - 检查：
node <root>/scripts/motion.cjs coverage index.html（无 FAIL，>= 90% 移动，包含文字，LCP 增量 < 300ms）·motion.cjs check index.html --duration 2.5（无hard-stop，无empty-opening）· 英雄区域和滚动区域的片段 ·motion_lint.py . --mode marketing。
工作流（任何 GSAP 任务）
- 决定时机（
<root>/reference/direction.md）：哪个场景是标志性效果（英雄开场、固定故事、水平画廊、文字揭示），对于展示型网站，还要决定其周围的完整编排（<root>/reference/site-motion.md）。寻找模式：search.py "<idea>" -d gsap/-d ui/-d transition。 - 构建时间线，而非延迟链（
references/core.md）：时间线上设置 defaults，使用位置参数实现重叠（"<"、"-=0.3"、标签），按角色选择缓动函数（到达时用 expo.out，移动时用 power2.inOut，scrub 用 none）。 - 滚动（
references/scrolltrigger.md）：ScrollTrigger 仅用在时间线或顶级 tween 上；scrub或toggleActions二选一；固定区域不超过 2-3 屏并显示可见进度；在containerAnimation中使用ease: "none"；从上到下创建触发器（或使用refreshPriority）；在图片/字体/动态内容加载后调用ScrollTrigger.refresh()。 - 根据需要使用的插件（
references/plugins.md）：SplitText（在蒙版中使用 lines/words，autoSplit+onSplit处理响应式，清理时 revert）、Flip、MorphSVG/DrawSVG、MotionPath、Draggable+Inertia、Observer、ScrollSmoother 或 Lenis、CustomEase。SplitText：标题按 words/chars 拆分，正文按 lines 拆分（mask: "lines"），揭示结束时 revert。 - 框架集成和清理（
references/frameworks.md）：在 React 中使用useGSAP({ scope })结合contextSafe处理事件；在其他地方使用gsap.context()+revert()；在卸载和路由变化时 kill/revert。 - 响应式 + 无障碍统一处理：使用
gsap.matchMedia()配合条件isDesktop、reduceMotion（<root>/reference/accessibility.md层级——减少动效下不包含固定/视差/scrub 移动；保留淡入淡出效果）。内容在无 JS 时可见：通过gsap.set在 matchMedia 内部设置隐藏起始状态，或使用 from-tween 的autoAlpha。 - 检查：
node <root>/scripts/motion.cjs strip page.html --duration 3 --frames 12检查加载时间线；对于滚动场景，暴露一个将t映射到滚动位置或进度的测试钩子（references/scrolltrigger.md§6）并进行检查；motion_lint.py src --mode marketing。
规则
- 使用变换别名（
x、y、xPercent、scale、rotation）和autoAlpha——绝不对 top/left/width/height 进行动画。当动画结束后 CSS 应接管时使用clearProps。 - 对同一目标的同一属性使用多个
from()/fromTo()：后续的 tween 设置immediateRender: false。 - 对于可能重新触发的 tween 使用
overwrite: "auto"；对于光标跟随/磁吸按钮使用gsap.quickTo()。 - 生产环境中无
markers: true；无用于动画的scroll监听器。 - 只固定必要的元素；
scrub: 0.8-1.2实现平滑权重（绝不使用原始的scrub: true处理可见移动）；当固定区域跳跃时使用anticipatePin: 1；对于依赖视口大小的基于函数的值使用invalidateOnRefresh。 - 展示型网站的流畅底线：揭示动画 >= 0.9s 并使用 expo.out/power4.out，重叠的 staggers，带内部缩放的图片擦除效果；非全速停止（
motion.cjs check->hard-stop）。 - SVG 变换原点：仅使用 GSAP 的
transformOrigin/svgOrigin——绝不同时使用 CSS 的transform-box（会导致双重偏移）。 - 平滑滚动（Lenis/ScrollSmoother）仅在桌面精细指针设备上启用；在减少动效和触屏设备上关闭；将 Lenis 连接到 ticker（
lenis.on('scroll', ScrollTrigger.update); gsap.ticker.add(t => lenis.raf(t * 1000)); gsap.ticker.lagSmoothing(0)）。 - 视频时间线（
astudio-motion:motion-video）：一个暂停的主时间线，window.__seek = t => tl.seek(t)，无repeat: -1，无带种子的Math.random()。