codify-design-to-code（将设计编码为代码）

Codify Dev - 设计转代码

核心原则

截图看布局，骨架定边界，JSON 取样式。三者协同，缺一不可。 结构先行，样式后填。 你看不到渲染结果，所有布局正确性只能靠推理。先用截图和骨架确定正确的 DOM 结构，再用 JSON 填充精确样式值。结构错了，样式再精确也白费。

协同：截图 + 骨架 → 理解意图、确定 DOM 结构；骨架 + JSON → 精确实现；截图 + JSON → 验证还原。

工作流程

准备：设置工作目录

每次任务开始时先执行，用节点 ID 隔离临时文件，避免并发冲突：

SKILL_DIR="/path/to/skill"                    # 替换为 skill 目录实际路径
NODE_ID="节点ID"                               # 替换为实际节点 ID
FILE_KEY="文件Key"                             # 替换为实际文件 Key
WORK_DIR="$TMPDIR/codify-${NODE_ID//:/–}"     # 每个节点独立目录
mkdir -p "$WORK_DIR"

SKILL_DIR 通常为当前 skill 文件所在目录，如 /Users/xxx/project/skill。

Step 0. 获取截图，建立视觉基准

截图是第一步，不可跳过。 在读骨架和 JSON 之前先看截图，用于：

• 识别所有视觉元素（装饰图形、渐变、光晕等）
• 建立视觉基准，后续所有 JSON 解读都以截图为参照

node "$SKILL_DIR/scripts/download-screenshot.cjs" \
  --nodeId "$NODE_ID" \
  --fileKey "$FILE_KEY" \
  --output "$WORK_DIR/screenshot.png"

截图下载后立即读取图片，记录：

1. 页面整体布局和层次
2. 所有视觉装饰元素（光晕、阴影、渐变、图标）
3. 文字样式的视觉重量和颜色
4. 哪些元素突出了其父容器的边界（如图标超出卡片顶部、阴影溢出容器等）

Step 1. 获取骨架，理解结构

curl -s -X POST http://127.0.0.1:13580/get_design \
  -H "Content-Type: application/json" \
  -d "{\"node_id\": \"$NODE_ID\", \"file_key\": \"$FILE_KEY\", \"mode\": \"skeleton\"}"

对照截图阅读骨架，重点关注：

• 整体层级和布局方向
• 与截图对应的视觉元素是否都在骨架中有对应节点
• 组件边界和重复结构

骨架标记见 design-schema.md，拆分规则见 codegen-rules.md。

判断复杂度，选择路径

判断标准不是绝对的：如果骨架虽然层级多但节点重复度高（大量 ×N），仍可走快速路径。关键是你能否在一次生成中准确记住所有节点的精确样式值。如果不确定，选分块路径。

Step 2A. 快速路径：一次性获取 JSON + 生成

适用于简单 UI（少量节点、浅层级）。

获取完整 JSON 并保存：

curl -s -X POST http://127.0.0.1:13580/get_design \
  -H "Content-Type: application/json" \
  -d "{\"node_id\": \"$NODE_ID\", \"file_key\": \"$FILE_KEY\"}" \
  > "$WORK_DIR/design.json"

# 读取（小型节点直接格式化输出）
cat "$WORK_DIR/design.json" | python3 -m json.tool

识别并下载所有资源：

JSON 返回的数据中有两类资源需要下载，它们的发现机制不同：

1. assets 数组中列出的矢量资源：JSON 末尾的 assets 数组明确列出了所有 ICON / VECTOR 类型节点，可直接按 nodeId 批量下载为 SVG
2. 主结构中的位图资源：RECTANGLE / IMAGE 类型且带有 object-fit 属性的节点是位图填充节点，不会出现在 assets 数组中，需要从主结构中识别后单独下载为 PNG

建立节点→用途的映射：下载前，必须将每个资源节点的 nodeId 映射回主 JSON 结构树中，通过该节点在结构树中的位置（父子层级、相邻节点）来确定它的 UI 角色（如关闭按钮、装饰图标等）。不要凭节点的 type 或 name 猜测用途。

node "$SKILL_DIR/scripts/download-assets.cjs" --fileKey "$FILE_KEY" --nodes '[
  {"nodeId":"<nodeId>","outputPath":"$WORK_DIR/icon-name.svg","format":"svg"}
]'

⚠️ 关键规则：ICON / IMAGE 节点必须下载实际资源文件，代码中直接引用文件路径。不要跳过下载自己画 SVG，也不要用占位符，也不要用 Unicode 字符近似替代。

然后跳到 Step 4. 生成代码。

Step 2B. 分块路径：制定分块计划

适用于复杂 UI（深层级、多节点）。

根据骨架结构，将设计拆分为 3-6 个独立区块。每个区块对应骨架中一个带 ID 的子树。

分块原则：

1. 每块对应截图中一个视觉区域
2. 每块的 JSON 数据量在一次上下文中可完整消化
3. 块之间通过容器布局关系组合，互不依赖内部细节

记录分块计划（示例）：

Block A: 25:05110  → 卡片容器 + 装饰光晕 + 关闭按钮
Block B: 25:05123  → 盾牌图标 + 标题
Block C: 25:05133  → 步骤图标列（左侧）
Block D: 25:05134  → 步骤内容列（右侧）

Step 3. 分块路径：逐块执行

对每个 Block 重复以下三步，完成一个块后再开始下一个：

3.1 获取该块的 JSON

curl -s -X POST http://127.0.0.1:13580/get_design \
  -H "Content-Type: application/json" \
  -d "{\"node_id\": \"子节点ID\", \"file_key\": \"$FILE_KEY\"}" \
  > "$WORK_DIR/block-A.json"

cat "$WORK_DIR/block-A.json" | python3 -m json.tool

读取 JSON 时必须做到：

1. 子节点 customStyle 全量读取：不只读顶层节点，对每一个子节点都读取 customStyle，尤其关注：

- margin-top / margin-bottom / margin-right / margin-left：决定元素间距，是布局精确度的关键 - padding：决定容器内边距 - align-items / justify-content：决定对齐方式

1. 布局模式判断：遇到并排/堆叠结构，明确区分：

- 左列是弹性伸缩（flex:1）还是固定尺寸堆叠（固定 height + margin-bottom）？ - 判断依据：子节点是否有固定 width/height + margin-bottom，如有则用固定尺寸，不用 flex:1 估算

1. JSON 必须读完：如数据较大需分段读取，须确认读到最后一段才进入下一步

3.2 下载该块涉及的资源

资源的发现和识别规则：

• 矢量资源：从 JSON 末尾的 assets 数组中，筛选出 nodeId 属于当前块子树的条目，批量下载为 SVG
• 位图资源：在当前块的 JSON 结构中，查找带 object-fit 属性的 RECTANGLE / IMAGE 节点，单独下载为 PNG

命名依据结构位置而非猜测：资源文件的命名应基于该节点在结构树中的 UI 角色（通过父子层级和相邻节点判断），而不是基于节点的 type 或 name 字段。

node "$SKILL_DIR/scripts/download-assets.cjs" --fileKey "$FILE_KEY" --nodes '[
  {"nodeId":"<nodeId>","outputPath":"$WORK_DIR/icon-xxx.svg","format":"svg"}
]'

⚠️ 关键规则：ICON / IMAGE 节点必须下载实际资源文件，代码中直接引用文件路径。不要跳过下载自己画 SVG，也不要用占位符，也不要用 Unicode 字符近似替代。

3.3 记录该块的关键样式

读完 JSON 和下载资源后，在继续下一个块之前，用简要注释记录该块的核心信息：

• 容器布局方式（flex 方向、padding、gap）
• 关键节点的 customStyle 摘要（字号、颜色、间距等）
• 该块涉及的资源文件列表

目的是确保每块的 JSON 数据被充分消化，而不是在最终生成时回头翻找。

所有块处理完成后，进入 Step 4 生成代码。

Step 4. 生成代码

阅读 codegen-rules.md。

代码生成分两步：先确定结构，再填充样式。

4.1 先写 DOM 结构骨架

基于截图和骨架，先输出纯 DOM 结构（含语义化的 class 名和注释，但不含具体样式值）。这一步只关注：

• 容器嵌套关系是否合理
• 需要绝对定位的元素，其定位参考（position: relative 的祖先）是否正确
• 需要裁切（overflow: hidden）的容器，其子元素是否都在边界内——如有元素需要突出容器边界，该元素必须放在裁切容器外部
• 重复结构是否使用循环
• 设计稿的层级与 DOM 层级的映射是否合理（设计稿层级不一定要 1:1 映射到 DOM，合理调整以符合 CSS 布局需要）

4.2 再填充精确样式

结构确认后，从 JSON 的 customStyle 中提取所有精确值填充到代码中：

• 所有尺寸、颜色、间距直接来自 JSON，不估算
• ICON / IMAGE 节点直接引用已下载的资源文件路径，不手绘近似 SVG
• 以截图为参照校验每个区块的视觉效果
• 输出格式和资源引用方式遵循项目规范（见 codegen-rules.md）

Step 5. 视觉验证（可选但强烈推荐）

如果生成的是可直接在浏览器运行的代码（HTML 文件、本地可启动的应用等），使用 Playwright 截图与设计稿截图进行对比验证。最多进行 2 轮修正。

5.1 截图渲染结果

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={"width": 375, "height": 812})
    page.goto('file:///path/to/output.html')
    page.wait_for_load_state('networkidle')
    page.screenshot(path='$WORK_DIR/render-result.png', full_page=True)
    browser.close()

需要 Playwright 环境。如不可用，跳过此步进入完成前回顾。

5.2 逐区域对比

不要泛泛地看"像不像"，要逐区域精确对比。 将页面分为 3-5 个视觉区域（与分块计划对应），每个区域单独检查：

1. 位置：元素在区域内的水平/垂直位置是否与设计稿一致？居中、偏左、还是固定偏移？
2. 尺寸：元素的宽高比例是否正确？有没有被拉伸或压缩？
3. 层叠：元素之间的前后遮挡关系是否正确？有没有被裁切、被遮挡？
4. 间距：元素之间的间距是否合理？太紧或太松？

5.3 聚焦修正

发现差异后，每次只修一个问题，修完立刻重新截图验证。不要一次改多处——同时改多个地方，无法判断哪个改动造成了新问题。

修正优先级：

1. 结构性问题（元素缺失、层级错误、被裁切） → 修 DOM 结构
2. 位置问题（偏移、对齐方向错误） → 修定位和布局属性
3. 细节问题（间距、字号、颜色微调） → 修具体样式值

完成前回顾

生成代码后（如已做视觉验证则在验证通过后），对照截图逐项检查：

• 截图中的所有视觉元素是否都已实现（包括装饰光晕、阴影等）
• 骨架中的关键节点是否都有对应代码
• JSON 是否已完整读完（包括最后的 assets 字段）
• 所有资源是否已下载，代码中引用的是已下载的文件路径，无手绘近似、无占位符
• 左右并排结构的对齐是否基于 JSON 的固定尺寸，而非估算
• 动态数据是否通过接口/Props 传入（非硬编码）
• 重复结构是否使用数组循环
• 资源引用方式是否与项目已有代码一致

常见错误

参考文档

错误处理

见 api.md 错误格式与错误码。