ss-motion

在此工作流之前，请先执行一次会话级别的 更新预检。

动效种子应用器

注册表优先的产物边界

当 .styleseed/project.json 和 .styleseed/artifacts/index.json 存在时，先解析请求的产物 ID，然后只读取 .styleseed/bundles/<artifact-id>.md 和 .styleseed/manifests/<artifact-id>.json。对于注册表项目，绝不要回退到全局旧版 bundle。仅当不存在注册表时，旧版项目才可使用 .styleseed/effective-rules.md。

不适用场景

• 通用的 framer-motion 文档或学习内容 → 使用 framer-motion 网站
• 非 React 动效（仅 CSS 过渡、GSAP）——此技能仅适用于 motion.X JSX
• 完整的滚动联动时间线或视差效果——不在此技能的范围内（此技能处理逐组件的种子/动效）。注意，这些效果允许用于营销/落地页/品牌页面（DESIGN-LANGUAGE §43 电影感层级）；但应使用滚动库实现，而非此技能。在应用/数据界面上仍然禁止使用。
• 调整现有的 FadeIn/FadeUp/Stagger 包装器——直接编辑 engine/components/ui/motion.tsx

氛围 → 种子映射

应用前，将用户的提示转换为五种种子之一。使用 engine/motion/index.ts 中的查找表：

用户可能会说的词	种子
有弹性、弹簧感、俏皮、充满活力、生动	Spring
流畅、丝滑、柔和、优雅、沉稳、连贯	Silk
爽快、迅速、即时、果断、利落、精准	Snap
轻盈、柔和、失重、梦幻、氛围感、飘逸	Float
有节奏、有冲击力、脉动、心跳、节拍	Pulse
“Toss 风格”、“Arc 风格”	Spring（遵循品牌默认值）
“Stripe 风格”、“Notion 风格”	Silk
“Linear 风格”、“Raycast 风格”、“Vercel 风格”	Snap

如果用户只说了一个品牌名称，使用 BRAND_DEFAULT_SEED 中该品牌的默认种子。如果用户明确指定种子名称（spring、silk 等），则照其指定使用。

推荐模式——使用场景 → 动效（当用户描述的是情境，而非氛围时）

如果用户描述的是事物的用途（“一个点赞按钮”、“一个模态框”、“加载状态”、“信息流中的项目”），而非感受，则根据使用场景映射表进行推荐（engine/motion/library.ts 中的 MOTION_BY_USECASE，从 @engine/motion 导出）：

使用场景	可选方案	原因
主按钮 / CTA 按压	spring · press	有触感、坚定——按压应当有“回弹”感
模态框 / 对话框 / 抽屉进入	silk · entrance	流畅；严肃/破坏性内容绝不要弹跳
下拉菜单 / 弹出层 / 菜单	snap · entrance	即时、精准——常用 UI 不应让人等待
Toast / 行内通知	spring · entrance	轻快友好的出现效果，不阻碍操作
列表 / 信息流项目出现	stagger-cascade	轻柔地安排出现顺序
功能卡片 / 营销卡片悬停	tilt-3d	在内容较少的营销页面上，可以增加深度感/亮点
仪表盘 / 数据卡片悬停	snap · hover	只做轻微抬升——让密集 UI 保持平静
点赞 / 收藏 / 互动反馈	like-burst	一次性的庆祝效果，奖励点击
在线 / 实时 / 录制状态圆点	pulse-beat	循环的心跳效果 =“活跃”
加载 / 骨架屏	shimmer	平静地展现方向性进度
成功 / 确认	pop-in	轻快地呈现“已完成”状态
开关 / 标签页 / 分段控件切换	toggle-flip	鲜明、易识别的切换效果
页面 / 路由切换	silk · entrance	流畅、简约，不喧宾夺主
数字 / 余额 / KPI / 价格展示	无	不要为实际信息添加动效——必须能立即读取

两条反规则优先于表格（若偏离，请说明）：

1. **每个产品只用一种种子。**如果项目已经在使用一种种子，就与之保持一致——不要引入第二种风格。
2. **绝不延迟呈现实际信息。**不要让余额、价格或搜索结果通过动效出现；动效用于表达可操作性，而非呈现内容。

命名动效关键词（鲜明动作）

种子设定的是 个性（淡入／缩放的感觉）。engine/motion/library.ts 中的动效库则添加了鲜明动作——翻转、幕布擦除、变形等，每种动作都对应一个独特的关键词。用户想要特定、易于辨认的动效，而不是泛泛的感觉时，优先使用关键词。

engine/motion/library.ts（从 @engine/motion 导出为 MOTION_LIBRARY / MOTION_BY_KEY）是唯一可信来源——每个关键词都带有自己的可运行 snippet。从中提取代码片段；切勿手写参数。

关键词	动作	用户想要……时使用
toggle-flip	3D Y 轴卡片翻转	开关在两个面之间翻转
toggle-slide	滑动堆叠切换	当前值滑出，下一个值滑入
toggle-morph	药丸形 ⇄ 圆形变形	控件在切换时改变形状
toggle-curtain	从上到下的 clip-path 擦除	面板像幕布一样揭开
reveal-blur	从 blur(12px)→0 逐渐清晰	内容聚焦并归位
reveal-rise	遮罩 clip-path 文本上升	标题／文本上移进入视野
reveal-unfold	从顶边沿 Y 轴缩放	手风琴面板／面板展开
pop-in	从 0 弹簧式过冲	徽章／勾选标记弹跳出现
press-squish	缩小 + 倾斜	按钮点击时有果冻般的触感
tap-ripple	从点击处扩散的径向波纹	Material 风格的按压反馈
pulse-beat	循环缩放脉冲	实时／录制／心跳指示器
wiggle	快速水平抖动	错误／无效输入反馈
shimmer	骨架屏加载扫光	加载占位符
stagger-cascade	子元素依次淡入并上移	列表逐项进入视野

应用关键词：

1. 从 engine/motion/library.ts 中读取准确方案——找到 key 匹配的条目，原样复制其 snippet（它已经过校准且可以运行）。
2. 只根据用户的 JSX 调整元素／内容；保留 transition 值。
3. 如果关键词需要状态（切换、波纹），按代码片段所示接入 useState。如果是单次揭示动效，递增 key 即可重新播放。
4. 告诉用户你应用了哪个关键词，方便他们在其他地方复用并保持一致；同时引导他们前往 /motion 预览并复制其他动效。

如果用户描述了一种动作，但没有完全匹配的关键词，就使用种子设定 + 上下文。如果用户提到不存在的关键词，请从表格中推荐最接近的真实关键词——绝不虚构关键词。

上下文检测

根据提示词推断以下五种上下文之一：

• “悬停时”／“鼠标悬停时” → hover
• “按下时”／“点击时” → press
• “出现时”／“挂载时”／“进入时” → entrance
• “离开时”／“关闭时”／“退出时” → exit（需要 <AnimatePresence>）
• “布局变化时”／“FLIP”／“重新排列时” → layout

如果有歧义，默认使用 entrance。如果存在多种合理的上下文（例如，按钮同时需要 hover 和 press），则同时应用。

应用步骤

应用种子：$0 · 上下文：$1 · 目标：$ARGUMENTS

1. 读取目标文件：使用给定路径（如果未提供路径，则询问用户要处理哪个文件）。定位用户提到的 JSX 元素——通常是 <button>、<div>、<Card> 或类似元素。

2. 确认导入路径。组件文件必须能够导入：

   • 从 "framer-motion" 导入 motion（使用 exit 时还需导入 AnimatePresence）
   • 从 "@engine/motion" 导入所选种子——如果项目不使用 @engine/* 别名，则使用相对于 engine/motion 的路径

3. 将目标标签替换为 <motion.X>，并展开种子的配置：

   // hover example
   <motion.button {...spring.hover}>Save</motion.button>
   
   // press + hover combined
   <motion.button {...spring.press} {...spring.hover}>Save</motion.button>
   
   // entrance (mount)
   <motion.div {...silk.entrance}>...</motion.div>
   
   // exit (requires AnimatePresence wrapper somewhere up the tree)
   <AnimatePresence>
     {open && <motion.div {...silk.entrance} {...silk.exit} />}
   </AnimatePresence>
   
   // layout (FLIP)
   <motion.div {...snap.layout}>...</motion.div>
   

4. 不要将参数内联写入 JSX。种子的核心作用是让值来自同一个来源。切勿将 { type: "spring", stiffness: 300, damping: 18 } 展开写入 JSX——始终展开配置。

5. 在长时间运行的界面中，遵循 prefers-reduced-motion 设置。对于一次性互动（悬停／按压），framer-motion 已会进行节流。对于长期存在页面中的挂载／退出／布局序列，请从 @engine/motion 导入 usePrefersReducedMotion 和 REDUCED_TRANSITION，并在启用减少动态效果时覆盖过渡设置。

6. 验证：重新读取文件，确认 JSX 仍能解析（括号匹配、motion 标签已闭合；如果使用了 exit，则 AnimatePresence 仍在）。

7. 告知用户应用了哪个种子和上下文，并推荐一个他们接下来可能需要的相关上下文（“还想加上 press，让它更有可点击的感觉吗？”）。

用户描述含糊时的默认处理

• 未提供文件 → 询问“哪个文件？”
• 未提供风格词 → 询问“有什么风格词、品牌或种子名称吗？”
• 风格是“自然”或“像真正的应用” → 默认使用 Silk（五种种子中最稳妥的选择）
• 元素是 CTA 按钮 → 同时应用 press

禁止事项

• 不要编造新的种子名称。总共只有五种。
• 不要通过此技能修改 engine/motion/seeds/*.ts——这些参数是人工校准的。只有在单独明确提出要求时，才能添加新种子。
• 不要引入第三方动画库（gsap、anime.js）。StyleSeed 仅针对 framer-motion。
• 不要通过此技能添加滚动联动、视差或无限动画——此技能用于逐组件应用种子／动效。（根据 DESIGN-LANGUAGE §43 Cinematic tier，营销／落地页／品牌页面允许使用滚动联动／视差／3D 效果——请直接使用滚动库实现；应用／数据界面仍然禁止。）除了骨架屏脉冲效果外，所有场景都禁止无限循环动画。