Figma2dsl

这个 skill 能干什么

把 figma 设计帧(节点树 JSON)还原成界面,两条并行产物、各司其职:

产物	生成脚本	性质	用途
<屏>.ui.json	figma_capture.py	全保真(每可见节点 + 全部样式,不折叠)	渲染真源:harness render.js / 实际 app / aigd 还原
<屏>.tree.html	figma_capture.py(同次)	全保真静态预览	眼比设计稿
<屏>.md(DSL)	figma_to_dsl.py	语义抽象(折叠+flat skin,有损是本职)	给人读 / AI 按意图生成 / KB 检索 / 喂 aigd

核心认知:折损不是 DSL 造成的,是"折叠+压扁"这套抽象选择。要完全还原画面走 .ui.json;要语义/意图走 DSL。唯一躲不掉的损失=矢量路径→栅格 PNG(与 DSL 无关,由 DOM 渲染目标决定)。

---

第0步 读真源(每次必做,用 Read)

• references/界面DSL规范-figma2dsl扩展.md — 增补规范(§0 双轨架构 + .ui.json schema + 坐标系/原图/parent/跳隐藏 + 样式字段)
• scripts/figma_capture.py — 全保真捕获(主路径)
• scripts/figma_to_dsl.py — DSL 转写(派生语义视图)
• scripts/ui_render.py — DSL→html 渲染校验(给 DSL 用)
• scripts/export_assets.py — 素材导出(figma REST)

第1步 准备输入

• nodes.json — figma 节点树(REST API /v1/files/<key>/nodes?ids=... 拉)
• frameId、屏名/NN、fileKey、outdir、_assets/s<NN>/ 素材目录

第2步 全保真捕获(主路径)

python scripts/figma_capture.py <nodes.json> <frameId> <sNN> <assetDir> <assetRelPrefix> <out_basepath>
# 产物: <out_basepath>.ui.json  +  <out_basepath>.tree.html

保留每节点:几何/旋转/不透明度/圆角/描边/阴影/模糊/填充(纯色含透明+渐变+图片)/文字(含字形描边)。关键规则:

• 资产感知折叠:矢量簇有导出 PNG 才整组折叠成图;缺 PNG 则不折叠、递归渲染可渲染形状子(白盒/椭圆/底色),纯矢量叶子各自透明。配 vector_leaf_count≤4 + has_renderable_shape 守卫,避免密集矢量装饰爆 div。
• 图片填充按 imageRef 命名(优先 <imageRef>.png,回退节点 id 名)→ 跨屏天然复用、可直接喂 figma 导出。
• 阴影方框修正:节点无圆角但带 DROP_SHADOW 时,继承铺满圆角子的圆角。

第3步 导素材

• 图片填充(底图/装饰/图标的位图):GET /v1/files/<key>/images 取 imageRef→URL 映射,下载存 <imageRef>.png。不卡节点渲染配额。
• 矢量节点渲染(图标/勾号等):export_assets.py 走 GET /v1/images?ids=...&format=png,有配额(429 时 Retry-After 可达数天)。
• 缺图:.ui.json 里 vec 元素回退透明(不平涂黑);img 回退无背景。

第3.5步 DSL 转写(可选,喂 KB/aigd)

python scripts/figma_to_dsl.py <nodes.json> <frameId> <NN> <屏名> <outdir> \
       [--prefix screen] [--brand figma] [--file-key KEY] [--meta meta.json]
# 产物: <outdir>/<prefix>-<NN>.md + .nodes.json

• 项目无关:file key 走 --file-key/环境变量 FIGMA_FILE_KEY;屏位元数据(用途/布局/标签/点评)走 --meta meta.json(项目私有数据放项目里,键=NN)。

第4步 渲染/校验

• 全保真:.ui.json 由 harness render.js 渲染(嵌套、绝对→父相对、逐节点真样式),Edge 无头截图眼比。
• DSL:python scripts/ui_render.py <屏>.md <屏>.html 渲染语义预览。

harness(可点可跑客户端)参考实现

已抽成同级 skill figma2html(runtime 引擎 + 自足 login 示例),要"可点可跑客户端"直接用它;模式要点:

• 架构 = 底屏 + 弹窗叠加(非一屏屏 swap):一个全屏底(底部 UI 只一份),弹窗用 render.js 的 subtreeOf(cap, 根id|根id数组) 抽面板子树叠加 + 半透明遮罩。状态(勾选/已选)才不跨屏串错。
• 字体内嵌:fonttools 子集化(只收集本界面用字)→ 几十 KB woff2 + @font-face → 离线可移植。
• 服务端:Node 零依赖(POST /api + SSE /events + 静态服务)即可。

硬约束

• UTF-8 无 BOM。
• FIGMA_TOKEN:只读进单条子进程、绝不进对话/文件/CHANGELOG;只验长度不验值;用完即删。
• 跳隐藏节点(visible:false / opacity≈0 / 0尺寸)。
• 不改 aigd 原件;本 skill 自带 bundle 副本。文法以规范页为准。
• figma_capture.py 主拷贝在同级 figma2html/scripts/,本处为镜像;tests/test_capture_parity.py 守两份逐字节一致(兄弟目录不存在时跳过)。
• 测试:python scripts/tests/run_all.py(改 figma_to_dsl / ui_render 后必跑,勿回归)。