界面动效生成技能

触发场景（何时应该使用本技能）

强烈推荐使用的情况（高匹配度）：

• 用户明确说：“帮我给这个按钮/卡片/列表加点击/进入/转场动效，并直接应用到代码里”
• 当前正在编辑 React/Next.js/TSX 组件文件，需要为 hover、press、mount、scroll reveal、shared element 等交互添加专业动效
• 项目已使用或计划使用 Framer Motion + Tailwind，Agent 需要自动安装依赖、修改 import、包装 motion 组件
• 需要把模糊的“加个丝滑动画”翻译成符合 Animation Vocabulary 的精确方案并落地到文件

可以尝试使用的情况：

• Vue/Svelte/HTML 项目，需要生成动效代码（自动应用能力会减弱，需要更多用户确认）
• 仅需要输出高质量动效提示词或 motion spec，不要求自动写入文件

明确不触发 / 不适合使用本技能的情况：

• 用户只想在 Figma、MasterGo、Sketch、图片或设计稿中“画”动效（本技能只操作代码文件）
• 项目是纯静态 HTML、无 package.json、或无法检测前端技术栈
• 需要实现复杂 Canvas/WebGL、Three.js、游戏物理、粒子系统等非 UI 微交互动画
• Monorepo 中需要跨多个子包/仓库修改，或目标文件为构建产物（dist、build、.next）
• 用户只想要“视觉演示”而非真实可维护的代码修改
• 没有明确批准 Dry-run 预览就要求直接修改文件（安全限制，永远不会自动执行）

适用性与限制（重要）

最佳适用环境：

• React 18 + TypeScript + Next.js / Vite
• 已安装或可安装 framer-motion + Tailwind CSS
• 源代码位于 src/components/、app/ 等标准位置，且文件可读写

支持但效果递减：

• 其他 JS 框架（Vue 3、Svelte）
• 纯 CSS / Vanilla JS 项目（仅生成代码，不自动修改）
• 已有部分动效库的项目（需手动适配）

硬性限制（本技能永远无法做到）：

• 修改 Figma / 设计工具中的图层或原型
• 操作非文本文件（图片、视频、Lottie JSON 除非生成代码引用）
• 绕过用户确认直接写入文件（Dry-run + 明确批准是强制流程）
• 保证修改后 100% 无类型错误或运行时问题（仅提供 Dry-run 提示）
• 支持需要运行时数据、复杂状态机、WebSocket 驱动的动画逻辑

使用建议：

• 第一次使用时，先让 Agent 只执行到 Dry-run 阶段，确认无误后再批准写入
• 大型项目建议先在小组件上测试
• 始终保留 Git 提交点，方便回滚

核心方法

始终使用文档定义的 11 类术语、提示词公式和验收清单，避免模糊描述（如“丝滑”“高级”）。

提示词公式

让 对象 在 触发时机 使用 动画模式，从 起始状态 到 结束状态，持续 时长，使用 缓动 / 弹簧参数，并满足 性能与可访问性约束。

11 类术语速查

动效实现与自动应用流程（核心）

当用户请求为界面添加动效时，遵循以下完整流程：

1. 使用专业术语澄清需求
   应用 11 类术语和提示词公式，明确动画模式、触发时机、时长、缓动/弹簧、性能约束。

2. 探索项目结构，定位目标组件
   使用 Glob、Grep 等工具搜索相关文件，遵循以下优先级规则：

   • 高优先级：当前在 IDE 中打开或最近查看/编辑的文件
   • 中优先级：src/components/、components/、app/ 下的文件
   • 低优先级：pages/、根目录下的零散组件
   • 搜索策略：先用 Glob 匹配 **/*{Button,Card,List,Modal,Page}*.{tsx,jsx,ts,js}，再用 Grep 按组件名精确过滤
   • 多候选处理：若找到 2 个以上候选文件，必须先列出文件路径和简要说明，让用户确认目标文件后再继续读取和修改。

3. 确定具体目标元素与修改点
   分析需求对应哪个元素（按钮、卡片列表、模态、路由转场等），决定是添加 motion props、包装 motion 组件、还是实现 layout animation。

4. 读取目标文件
   读取候选文件内容，理解现有结构、导入、样式系统（Tailwind / CSS Modules / styled-components 等）。

5. 检测技术栈与依赖

   • 读取项目根目录的 package.json，识别包管理器（pnpm / npm / yarn）和已安装动画相关依赖（framer-motion、@react-spring/web、gsap 等）。
   • 若缺少必要依赖，在 Dry-run 阶段明确提示安装命令：
     • pnpm：pnpm add framer-motion
     • npm：npm install framer-motion
     • yarn：yarn add framer-motion
   • 同时检查是否已配置 Tailwind 或其他样式方案。

6. 生成适配实现方案
   根据检测到的技术栈输出精准代码：

   • React + Framer Motion：使用 motion.div、whileTap、animate、layout
   • Tailwind + CSS：添加 transition 类或 @keyframes
   • 纯 HTML/JS：添加 style + requestAnimationFrame 或 CSS animation
   • 始终优先 transform + opacity

7. Dry-run 预览与用户确认（关键安全步骤）
   在实际写入文件前，必须输出以下内容供用户确认：

   • 将要修改的文件完整路径列表
   • 每个文件的修改摘要（例如：“添加 import + 将 button 包装为 motion.button + 增加 whileTap”）
   • 可能的副作用提示（如类型变化、需要安装依赖）
   • 提供两个选项：A. 确认修改并继续；B. 仅生成代码，不写入文件

8. 应用修改到项目文件
   仅在用户明确批准后执行：

   • 精确插入 import（如 import { motion } from 'framer-motion'）
   • 将目标 JSX/HTML 元素替换为 motion 版本或添加动画 props
   • 必要时添加 state、事件处理或 layout 属性
   • 注入 reduced-motion 逻辑（@media (prefers-reduced-motion: reduce)）

9. 运行设计验收清单（见下节）并确认修改。

10. 输出总结：说明使用了哪些术语、修改了哪些文件、为什么这样设计。

设计验收清单（必查）

• 动效是否有明确目的（反馈/引导/解释关系/感知性能）
• 用户能否从动效理解元素来源、去向或状态变化
• 高频操作的动效是否短、轻、克制（< 300ms）
• 是否优先使用 transform 与 opacity，避免 layout thrashing
• 是否尊重 prefers-reduced-motion
• 转场是否保持 spatial consistency
• 弹簧动画是否可打断并自然接续手势
• 动效是否增强任务完成，而非抢夺注意力

输出要求

• 代码示例必须包含 reduced-motion 处理
• 规格说明需包含时长、缓动、触发条件、性能约束
• 提示词需直接可用于 AI 生成工具
• 始终说明“为什么用这个动效”（purposeful）
• 当执行自动应用时，必须先读取目标文件，再提出精确的编辑修改
• 所有动效实现必须包含 reduced-motion 处理（详见 reference.md 第1节）

常见错误与回退处理

• 多候选文件冲突：列出所有候选，让用户选择目标文件。
• 文件只读或权限不足：提示用户手动修改，或生成 .patch 文件供用户应用。
• TypeScript 类型错误：在 Dry-run 阶段明确标注可能需要调整的类型定义。
• 缺少依赖：在 Dry-run 阶段给出精确的 pnpm add / npm install 命令。
• 用户拒绝写入：立即切换为“仅输出代码 + 修改说明”模式，不再尝试写入。
• 动效导致布局抖动：优先推荐 transform + opacity，避免动画 width/height/left/top。

技术栈实现参考

详细的各框架代码模式、Reduced Motion 完整实现、依赖检测清单见 reference.md。

示例 1：按钮按压反馈（自动应用到项目）

输入：为主按钮添加点击 press feedback

流程示例：

1. 探索项目 → 发现 src/components/Button.tsx 和 src/components/PrimaryButton.tsx
2. 读取目标文件 src/components/Button.tsx
3. 检测到已使用 Tailwind + Framer Motion
4. 应用修改：添加 whileTap + spring transition，并确保 reduced-motion 处理

最终修改结果（已写入文件）：

// src/components/Button.tsx
import { motion } from 'framer-motion'

export function Button({ children, ...props }) {
  return (
    
      {children}
    
  )
}

使用的术语：Press feedback、Spring、Interruptible、Reduced Motion

示例 2：列表逐项进入（自动应用到项目）

输入：卡片列表进入视口时依次出现

流程示例：

1. 搜索 **/*Card*.tsx、**/*List*.tsx
2. 定位到 src/components/FeatureList.tsx
3. 读取文件后，使用 scroll reveal + stagger 模式
4. 包装每个卡片为 motion.div，添加 viewport trigger 和 stagger

最终修改结果（已写入文件）：

// src/components/FeatureList.tsx
import { motion } from 'framer-motion'

const cardVariants = {
  hidden: { opacity: 0, y: 12 },
  visible: { opacity: 1, y: 0 }
}

{mockData.map((item, index) => (
  
    ...
  
))}

使用的术语：Scroll Reveal、Stagger、Ease-out

示例 3：缩略图转场详情（自动应用到项目）

输入：点击缩略图平滑展开为详情页

流程示例：

1. 找到 src/app/gallery/[id]/page.tsx 和缩略图组件
2. 实现 shared element transition（使用 Framer 的 layout + AnimatePresence 或原生 View Transitions）
3. 保持 spatial consistency

最终修改结果（已写入文件）：

// 缩略图组件
 navigateToDetail(id)}
/>

// 详情页

使用的术语：Shared Element Transition、Layout Animation、Spatial Consistency

参考来源

完整词汇表与判断依据见原 Notion 文档：Animation Vocabulary 动画术语整理

好的 UI 动画不是装饰，而是给变化装上路标：让用户知道发生了什么、从哪里来、要到哪里去。

补充：Reduced Motion 与技术栈检测（方向4+5 强化）

• 所有动效代码必须在 Dry-run 阶段展示 reduced-motion 处理（全局 CSS 或 useReducedMotion hook）。
• 技术栈检测：读取 package.json → 判断包管理器 → 输出精确安装命令 → 在 reference.md 中查找对应实现模式。