figma2cocos — figma IR → Cocos Creator 3.x
这个 skill 干什么
figma2html 已把 figma 帧变成 .ui.json(像素真值)+ flow.json(声明的交互)。本 skill 是这套 IR 的
Cocos 落地端:
- TS 运行时解释器(
runtime/):FigmaUI 组件读 JsonAsset(cap)动态建节点树(Graphics/Label/Sprite);
FlowBinder 读 flow.json 组装"底屏常驻 + 弹窗叠加 + 事件 + guard + 列表克隆 + checkbox",域内语义走
FigmaAppHook(对齐 assemble.js 的 APPHOOK)。
- python 离线校验器(
scripts/ui_check.py):不开 Cocos 就能测的部分——IR/flow 引用完整性 + 资产清单。
分工:capture / flow 编写规范 → figma2html;HTML 落地 → figma2html;Cocos 落地 → 本 skill。
内容
runtime/ parse-css.ts(rgba/渐变/radius四角/border/shadow 解析,纯函数)
figma-ui.ts(@ccclass FigmaUI:cap→节点树;buildSubtree=弹窗抽子树;paintRect 复用)
flow-binder.ts(@ccclass FlowBinder:flow→层/事件/guard/列表/勾选;FigmaAppHook 注册口)
references/ mapping.md(IR→Creator 映射全表 + 坐标转换推导 + known-loss 表 + 集成冒烟清单)
scripts/ ui_check.py(离线校验:caps 可载入、el id 引用完整、列表模板行、assets-manifest.json)
bake_motion.py(flow.json → motion.json:转场缓动解成采样点,TS 侧只插值)
motion.py(figma2html 主拷贝的**逐字节镜像**,tools/conformance 逐字节守)
tests/(run_all.py 发现式 runner + test_ui_check.py + test_runtime_source.py;
fixtures/=figma2html login 三屏夹具)
用法(管线)
- capture(figma2html):figma 帧 →
screen-*.ui.json ×N + 手写 flow.json + 导出图片素材。
- 离线校验:
python3 scripts/ui_check.py <flow.json> <capDir> —— 全部引用过了才进 Cocos;
顺手产出 assets-manifest.json(去重图片清单)。
- 烘动效:
python3 scripts/bake_motion.py <flow.json> <outdir> → motion.json
(每条转场曲线 17 个采样点)。曲线一律在 python 侧解算,TS 侧只做线性插值 ——
换成 Creator 内置的 easing.quadOut 之流就是同名不同形,与其它五个后端手感分叉
(实测最大差 19.8 个百分点)。不烘也能跑,弹窗就是瞬时显隐。
- 资产导入:manifest 里的图放进
assets/resources/<assetRoot>/(保持 _assets/... 路径、文件名 stem 不变);
.ui.json / flow.json / motion.json 拷进工程任意 assets 目录(Creator 自动导成 JsonAsset,名为路径 stem 如 screen-login.ui)。
- 挂组件:Canvas designResolution=cap.w×cap.h;根节点(锚(0,1)+Widget 左上对齐)挂
FigmaUI(单屏预览,拖 capAsset)或 FlowBinder(整流程,拖 flowAsset + capAssets[] + motionAsset)。
- hook:域内语义(数据→行、选中回填、状态色)写一个组件,在其
onLoad 里
FlowBinder.registerHook({ register(app){ app.registerActions({send, selectServer, onGuardFail, ...}) }, init(app){ app.renderRows(...) } })
—— 语义与 figma2html 的 app.js/APPHOOK 一一对应,renderRows/openModal/setFlag/getNode 同名同义。
- 冒烟:按
references/mapping.md §6 清单逐项核(几何对照截图、事件逐个点验)。
硬约束
- 坐标转换是本 skill 的命门:IR 是 y 向下/左上原点的绝对 px,Creator 是 y 向上/锚点系。
约定 = 每节点锚 (0,1),
child.position = (dx, -dy);旋转节点换锚 (0.5,0.5) 补偿。改动前必读 references/mapping.md §2/§3。
- TS 验证等级(2026-07-31 复跑):三件 runtime TS 已过 严格类型编译门(tsc --noEmit 对 Cocos 官方
@cocos/creator-types 3.8.3 engine 声明,含 @ccclass 装饰器路径;故意错用 API 会被抓=门有牙)。这道门已经进仓、也进 CI:cd tools/cocos-typecheck && npm ci && python3 check.py(它连"门有牙"那半句一起验:种一个必然的类型错误,tsc 必须报出来)。此前它只在作者本机存在 —— 声明是真的,但没人能复现。Creator 内实机运行仍未验证,交付态 = 源码 + 集成说明(mapping.md 顶部有声明);python 侧
python3 scripts/tests/run_all.py 必须全绿才算校验器可用。
- 动效不许在 TS 侧解曲线:烘焙归
scripts/bake_motion.py,flow-binder.ts 只做线性插值。
采样点一致只保证关键帧上一致,插值模式不对齐照样各算各的(godot/unity 都在这儿栽过)。
位移/缩放只贴 flow.modals[*].panel,贴到弹窗层上遮罩会跟着滑/缩 —— 数值看不出来,
实机截图才抓得到。这两条有源码级守卫(tests/test_runtime_source.py)。
- 引擎 vs hook 边界不破:runtime 只管结构与机制,任何"某个项目的某块颜色/数据"都进 hook,不进引擎。
- 项目无关、可移植;中文文档、英文标识符;UTF-8 无 BOM。
- 上游 IR 契约(字段、已知限制如实例内 rot=0)以 figma2html
references/ 为准,本 skill 不复制不改写。
1---2name: figma2cocos3description: 把 figma2html 管线产的 IR(.ui.json 像素快照 + flow.json 交互声明)落到 Cocos Creator 3.x —— TS 运行时解释器(组件加载 ui.json 动态建节点树 + flow 绑定器)+ python 离线校验器(引用完整性 + 资产清单)。要在 Cocos 工程里还原 figma 界面与交互(底屏+弹窗/守卫/列表/勾选)时使用;capture 本身归 figma2html。4---56# figma2cocos — figma IR → Cocos Creator 3.x78## 这个 skill 干什么910figma2html 已把 figma 帧变成 **`.ui.json`(像素真值)+ `flow.json`(声明的交互)**。本 skill 是这套 IR 的11**Cocos 落地端**:1213- **TS 运行时解释器**(`runtime/`):`FigmaUI` 组件读 JsonAsset(cap)动态建节点树(Graphics/Label/Sprite);14 `FlowBinder` 读 flow.json 组装"底屏常驻 + 弹窗叠加 + 事件 + guard + 列表克隆 + checkbox",域内语义走15 `FigmaAppHook`(对齐 assemble.js 的 APPHOOK)。16- **python 离线校验器**(`scripts/ui_check.py`):不开 Cocos 就能测的部分——IR/flow 引用完整性 + 资产清单。1718分工:**capture / flow 编写规范 → figma2html**;**HTML 落地 → figma2html**;**Cocos 落地 → 本 skill**。1920## 内容2122```23runtime/ parse-css.ts(rgba/渐变/radius四角/border/shadow 解析,纯函数)24 figma-ui.ts(@ccclass FigmaUI:cap→节点树;buildSubtree=弹窗抽子树;paintRect 复用)25 flow-binder.ts(@ccclass FlowBinder:flow→层/事件/guard/列表/勾选;FigmaAppHook 注册口)26references/ mapping.md(IR→Creator 映射全表 + 坐标转换推导 + known-loss 表 + 集成冒烟清单)27scripts/ ui_check.py(离线校验:caps 可载入、el id 引用完整、列表模板行、assets-manifest.json)28 bake_motion.py(flow.json → motion.json:转场缓动解成采样点,TS 侧只插值)29 motion.py(figma2html 主拷贝的**逐字节镜像**,tools/conformance 逐字节守)30 tests/(run_all.py 发现式 runner + test_ui_check.py + test_runtime_source.py;31 fixtures/=figma2html login 三屏夹具)32```3334## 用法(管线)35361. **capture**(figma2html):figma 帧 → `screen-*.ui.json` ×N + 手写 `flow.json` + 导出图片素材。372. **离线校验**:`python3 scripts/ui_check.py <flow.json> <capDir>` —— 全部引用过了才进 Cocos;38 顺手产出 `assets-manifest.json`(去重图片清单)。393. **烘动效**:`python3 scripts/bake_motion.py <flow.json> <outdir>` → `motion.json`40 (每条转场曲线 17 个采样点)。**曲线一律在 python 侧解算**,TS 侧只做线性插值 ——41 换成 Creator 内置的 `easing.quadOut` 之流就是同名不同形,与其它五个后端手感分叉42 (实测最大差 19.8 个百分点)。不烘也能跑,弹窗就是瞬时显隐。434. **资产导入**:manifest 里的图放进 `assets/resources/<assetRoot>/`(保持 `_assets/...` 路径、文件名 stem 不变);44 `.ui.json` / `flow.json` / `motion.json` 拷进工程任意 assets 目录(Creator 自动导成 JsonAsset,名为路径 stem 如 `screen-login.ui`)。455. **挂组件**:Canvas designResolution=cap.w×cap.h;根节点(锚(0,1)+Widget 左上对齐)挂46 `FigmaUI`(单屏预览,拖 capAsset)或 `FlowBinder`(整流程,拖 flowAsset + capAssets[] + motionAsset)。476. **hook**:域内语义(数据→行、选中回填、状态色)写一个组件,在其 `onLoad` 里48 `FlowBinder.registerHook({ register(app){ app.registerActions({send, selectServer, onGuardFail, ...}) }, init(app){ app.renderRows(...) } })`49 —— 语义与 figma2html 的 `app.js`/`APPHOOK` 一一对应,`renderRows/openModal/setFlag/getNode` 同名同义。507. **冒烟**:按 `references/mapping.md §6` 清单逐项核(几何对照截图、事件逐个点验)。5152## 硬约束5354- **坐标转换是本 skill 的命门**:IR 是 y 向下/左上原点的绝对 px,Creator 是 y 向上/锚点系。55 约定 = 每节点锚 (0,1),`child.position = (dx, -dy)`;旋转节点换锚 (0.5,0.5) 补偿。改动前必读 `references/mapping.md §2/§3`。56- **TS 验证等级(2026-07-31 复跑)**:三件 runtime TS 已过 **严格类型编译门**(tsc --noEmit 对 Cocos 官方 `@cocos/creator-types` 3.8.3 engine 声明,含 @ccclass 装饰器路径;故意错用 API 会被抓=门有牙)。**这道门已经进仓、也进 CI**:`cd tools/cocos-typecheck && npm ci && python3 check.py`(它连"门有牙"那半句一起验:种一个必然的类型错误,tsc 必须报出来)。此前它只在作者本机存在 —— 声明是真的,但没人能复现。**Creator 内实机运行仍未验证**,交付态 = 源码 + 集成说明(mapping.md 顶部有声明);python 侧57 `python3 scripts/tests/run_all.py` 必须全绿才算校验器可用。58- **动效不许在 TS 侧解曲线**:烘焙归 `scripts/bake_motion.py`,`flow-binder.ts` 只做**线性**插值。59 采样点一致只保证关键帧上一致,插值模式不对齐照样各算各的(godot/unity 都在这儿栽过)。60 位移/缩放**只贴 `flow.modals[*].panel`**,贴到弹窗层上遮罩会跟着滑/缩 —— 数值看不出来,61 实机截图才抓得到。这两条有源码级守卫(`tests/test_runtime_source.py`)。62- 引擎 vs hook 边界不破:runtime 只管结构与机制,任何"某个项目的某块颜色/数据"都进 hook,不进引擎。63- 项目无关、可移植;中文文档、英文标识符;UTF-8 无 BOM。64- 上游 IR 契约(字段、已知限制如实例内 rot=0)以 figma2html `references/` 为准,本 skill 不复制不改写。
ProdaZhang