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 三屏夹具)

用法(管线)

1. capture(figma2html):figma 帧 → screen-*.ui.json ×N + 手写 flow.json + 导出图片素材。
2. 离线校验:python3 scripts/ui_check.py <flow.json> <capDir> —— 全部引用过了才进 Cocos; 顺手产出 assets-manifest.json(去重图片清单)。
3. 烘动效:python3 scripts/bake_motion.py <flow.json> <outdir> → motion.json (每条转场曲线 17 个采样点)。曲线一律在 python 侧解算,TS 侧只做线性插值 —— 换成 Creator 内置的 easing.quadOut 之流就是同名不同形,与其它五个后端手感分叉 (实测最大差 19.8 个百分点)。不烘也能跑,弹窗就是瞬时显隐。
4. 资产导入:manifest 里的图放进 assets/resources/<assetRoot>/(保持 _assets/... 路径、文件名 stem 不变); .ui.json / flow.json / motion.json 拷进工程任意 assets 目录(Creator 自动导成 JsonAsset,名为路径 stem 如 screen-login.ui)。
5. 挂组件:Canvas designResolution=cap.w×cap.h;根节点(锚(0,1)+Widget 左上对齐)挂 FigmaUI(单屏预览,拖 capAsset)或 FlowBinder(整流程,拖 flowAsset + capAssets[] + motionAsset)。
6. hook:域内语义(数据→行、选中回填、状态色)写一个组件,在其 onLoad 里 FlowBinder.registerHook({ register(app){ app.registerActions({send, selectServer, onGuardFail, ...}) }, init(app){ app.renderRows(...) } }) —— 语义与 figma2html 的 app.js/APPHOOK 一一对应,renderRows/openModal/setFlag/getNode 同名同义。
7. 冒烟:按 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 不复制不改写。