---
name: figkit-motion
description: 界面动效的查阅层:59 条效果目录(什么时候用 / 什么时候别用 / 引擎无关的方法)+ 63 个参数令牌(值 / 值域后果 / 校准状态)+ 6 个共用算法(贝塞尔求解、弹簧解析解、动量投射、橡皮筋、速度采样、FLIP)。figkit 各后端共用它;要给界面加动效、或要判断某处该不该加动效时使用。它不产物、不吃 IR —— 需要落地实现时回到对应的 figma2* 后端。
---

# 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
时优先重估它们**。