动效精工
将动效构建为产品交互的一部分，而非粘贴上去的装饰。追踪真实渲染主体，选择最合适的实现技术，保留状态语义，并在真实浏览器中验证结果。
工作流程
- 在提出实现方案前先审查目标。
- 定位实际路由、组件、样式、状态所有者、事件所有者以及现有动画栈。
- 阅读项目说明，保留不相关的修改。
- 如果用户要求先讨论，则生成具体动效说明，待批准后再继续。
- 定义动效契约。
- 说明触发条件、起始和结束状态、持续时间、缓动或弹簧效果、中断行为、重复行为、分层方式以及减少动效时的结果。
- 将业务状态与视觉反馈分离。删除操作、导航或表单提交不应依赖装饰性时间线的完成，除非产品明确要求。
- 选择素材。
- 运行
python3 scripts/query_catalog.py --need "<效果描述>" --top 4。 - 阅读
references/motion-routing.md以选择合适的技术。 - 在复制代码或添加依赖之前，检查所选仓库的最新官方 README、相关源代码、依赖/API 版本和许可证。将目录元数据视为带有日期戳的路由快照，而非永久真理。
- 运行
- 选择采用模式。
- 当项目已安装的动画栈能清晰满足契约时，优先使用它。
- 仅当代码和许可证允许时，复制并适配小组件；移除示例外壳和无用的依赖。
- 当库的运行时模型能在实质上降低复杂性或风险时，添加该库。
- 当仓库过旧、框架不匹配或过于臃肿时，提取其技术而非整个包。
- 实现最小且协调的动效系统。
- 集中管理时长和缓动令牌。
- 清理 RAF 循环、观察器、事件处理器、画布、时间线、纹理和 GPU 资源。
- 处理重新挂载、快速重复输入、中断、路由变化、窗口调整、隐藏标签页和 React Strict Mode。
- 在 SSR 应用中正确保护浏览器专用代码，并在可行时懒加载重型视觉引擎。
- 使用
references/quality-gates.md进行验证。- 执行针对性静态检查和测试。
- 在宽屏桌面、中屏/平板和移动端尺寸下测试真实运行时。
- 检查过渡连续性、最终几何尺寸、控制台错误、水平溢出、输入行为、减少动效以及实际性能。
- 报告结果。
- 先说明现在能正常工作什么。
- 指出所选技术或源代码仓库及其适用理由。
- 诚实地说明已验证的内容以及任何遗留限制。
选择规则
- 对于少量复合属性和简单确定性状态，使用 CSS 过渡/关键帧。
- 对于 React 中的出现/消失、共享布局、手势、值和协调的组件过渡，使用 Motion。
- 对于可中断的物理效果，当速度连续性和自然响应比固定时间线更重要时，使用 React Spring。
- 对于明确的多阶段时间线、密集编排、SVG/路径动画、滚动编排或命令式集成，使用 GSAP。
- 对于紧凑的 DOM/SVG/对象/画布补间和生成式交错效果（不依赖 React 特定抽象层），使用 Anime.js。
- 仅将 Disintegrate 用作 DOM 快照粒子化的技术/参考；预期 html2canvas 的保真度限制并现代化其生命周期。
- 使用 tsParticles 实现可配置的环境粒子、五彩纸屑、烟花和背景；不要将其误标为精确的 DOM 分解。
- 使用 PixiJS 处理大量 2D 粒子、滤镜、精灵场景、着色器驱动的 2D 效果和显式 GPU 资源控制。
- 将 React Bits、Magic UI 或 Motion Primitives 作为源码集合使用。检查每个组件，因为依赖项、渲染成本和质量各不相同。
产品护栏
- 保持空间因果性：动效应解释对象从何而来、去往何处或发生了什么变化。
- 优先使用 transform 和 opacity；只有在有证据表明成本可接受时才动画化布局属性。
- 切勿用动效掩盖布局缺陷。
- 避免环境、滚动、悬停和入场动画同时竞争注意力。
- 提供键盘等效行为并保留焦点语义。
- 尊重
prefers-reduced-motion；将运动替换为即时状态变化或克制化的淡入淡出。 - 不要仅凭代码审查就声称流畅度。在实际渲染路径上验证并报告测试范围。
- 除非用户在当前回合明确授权，否则不要修改代理/路由规则或不相关的本地环境配置。
资源
references/repositories.json：十个源代码仓库、许可证、优势、风险和源码入口点的带日期戳目录。references/motion-routing.md：决策指南和产品级架构模式。references/quality-gates.md：实现和实时视觉验证检查表。scripts/query_catalog.py：通过自然语言需求或标签验证和搜索仓库目录。