figkit-motion — 动效目录

这个 skill 干什么

figkit 的各个后端把 figma 稿变成能跑的界面,转场那部分它们已经会播了 (见下「figkit 已内置」)。但一个真实的界面还需要几十种别的动效:列表要能拖、 滚到头要有橡皮筋、领奖要有东西飞进背包、命中要顿一下。那些不该由 figkit 替你决定挂在哪个 元素上,所以它给的是方法和参数,由你在自己的引擎里实现。

这就是本 skill:一本查得动的动效目录。

routing.md    该不该动(闸门四关)· 场景 → 效果查找表 · 反查缺口 · 性能 · 无障碍 · 十条铁律
catalog.md    59 条效果:别名 / 类 / 用 / 别用 / **引擎无关的方法** / 约束 / 令牌
              + 每条的 <details> 里附 web 参考实现(figma2html 后端可直接抄)
algorithms.md 6 个跨效果共用的算法(其中 2 个 figkit 已实现在 motion.py 里)
tokens.json   ★ 63 个令牌的**数值真源**:值 / 用途 / 值域**后果** / 校准状态 / 别名
scripts/      token_check.py(令牌契约)+ tests/

它不是运行时库。 没有代码要你 import,没有产物要你构建。

怎么查

1. 要给某处加动效 → routing.md §1 过闸门(「不加」是正当答案)→ §2 查表 → catalog.md 找到那条 → 照 方法 段在你的引擎里实现 → 值从 tokens.json 取。
2. 要判断已有界面缺什么 → routing.md §3 六类接缝反查。
3. 策划说「那个抖动的参数」 → grep tokens.json 的 aliases。
4. 要自己插值(引擎 tween / canvas / shader) → algorithms.md。

figkit 已内置的部分

motion.py 的 PRESET 是本目录 13 个令牌的副本,apply_defaults() 用它替你补掉四处: 弹窗开合、按压、列表逐项入场、guard 失败抖动。目录里这几条标着 ✅ figkit 已内置 —— 别在引擎侧重做一遍,改值改 flow.json(每条都带 "source": "preset:base",看得见、能改能删)。

优先级永远是 figma 原稿 > 项目覆盖 > 本目录的默认值。目录只在 figma 什么都没说时才发言。

两处值不许漂:tools/conformance 有一条测试拿 tokens.json 与 motion.py PRESET 逐条比 (值 + 校准分档)。改了一边不改另一边,测试会红。

硬约束

• 散文里一个裸数字都不许有,只许写 {motion.x}。有裸数字,读的人就抄裸数字 —— 于是令牌改了,抄走的那份不会跟着改。token_check.py 守这条。
• calibration 必填,三档:tuned(调过手感)/ inherited(抄来的,没针对游戏 UI 校准)/ untested(编的,一次都没跑过)。它的全部意义是把「我们决定过这个值」和「我们还没管这个值」 分开 —— 没有它,两者在表里长得一模一样,而后者是坑。63 条里只有 12 条是 tuned。
• range 要写后果,不是「建议范围」。 「别用内置 ease-out,太弱」会被违反(没有代价); 「差 19.8 个百分点,出在起步段」不会。
• 方法段是引擎无关的。 具体 API 只许出现在 <details> 的 web 参考实现里。
• 别让目录膨胀成「游戏里所有会动的东西」。 镜头语言(推拉 / 跟随)、粒子、 骨骼动画都不在本档边界内 —— 真要做该另起一档。

出处

方法与参数取自一份真实项目的动效规范,已去掉项目专属编排与评审流程。值的来源分三档写在 calibration 里 —— 其中 inherited 的那批多来自面向工具型 web UI 的推荐值,换到游戏 UI 时优先重估它们。