@double-codeing/skill-figma-d2c

把 Figma 设计稿一键还原成可运行的 React/SCSS 代码,以 Claude Code Skill 形式分发。

内置:图层命名规范 + 设计稿体检(doctor)+ 单位换算 + 资产管理 + Figma REST API 兜底链。

特性

• 🎯 图层前缀语义:sub- 分块、bg- 背景图、bgc- 父级装饰、fixed- 视口固定等 11 类前缀,设计师统一规范
• 🩺 设计稿体检:命名规范 / 布局合理性 / 嵌套深度 / 颜色对比 / 资产体积等 30+ 条规则,生成前自动跑一遍
• 📐 严格单位换算:Figma 设计稿基准宽度 → 代码单位(px/vw/rem)
• 🖼️ 图片导出兜底链:REST API + use_absolute_bounds=true 主路径 → MCP download_assets 兜底 → 临时占位降级
• ⚡ sub-agent 并行:sub- 前缀的图层各派一个 sub-agent 并行处理,支持嵌套(深度 ≤ 3)
• 🔍 逐块视觉对比:生成后主 agent 对每个 sub-block 截图与代码渲染做单独对比

安装

# 在你的业务项目根目录下执行
npx @double-codeing/skill-figma-d2c init

init 会引导你完成 8 题交互式配置(项目框架、样式方案、单位换算等),并生成:

• skill-figma-d2c.config.json:项目配置
• .claude/skills/skill-figma-d2c/:主 SKILL(D2C 生成)
• .claude/skills/skill-figma-d2c-doctor/:体检 SKILL
• code-connect/mappings.json:Figma 组件 → 代码组件映射表
• static/、pages/(默认路径,可配置):图片资产 / 输出目录

前置依赖:Claude Code(最新版)+ 在 Claude Code 中安装 Figma 官方 MCP 插件并完成 OAuth 认证。详见 MCP 安装。

快速开始

1. 完成 init 交互

$ npx @double-codeing/skill-figma-d2c init

─── 阶段一:Figma MCP 安装提示 ──────────────────────
  ⚠️  init 脚本运行在终端进程里,无法直接验证 Claude Code 内的 MCP 状态。
  实际可用性会在 Claude 跑 SKILL 步骤 -1 时调 whoami 探针验证。

─── 阶段二:交互式配置 ──────────────────────────────
  [1/8] 项目框架: ● react  rn
  [2a/8] 样式方式: ● stylesheet  tailwind  inline
  [2b/8] 预处理语法: ● scss  less  css
  [2c/8] 是否启用 css-modules: ● No  Yes
  [3/8] 合并模式: ● component  flat
  [4/8] 图片输出目录 [static/]:
  [5/8] 图片 base URL [http://127.0.0.1:8080/]:
  [6/8] 代码输出目录 [pages/]:

─── 阶段三:单位换算规则 ────────────────────────────
  [单位1/4] 设计稿基准宽度 (px) [375]:
  [单位2/4] 代码使用的单位: ● px  vw  rem
  [单位3/4] 代码 px 基准宽度 [750]:
  [单位4/4] Figma Personal Access Token []:

可重复运行:再次跑 init 会自动沿用 config 里已有的值,只对缺失字段弹交互。想强制重填某项就删掉 config 对应字段。

2. 把设计稿链接发给 Claude

把这份设计稿转成代码:https://figma.com/design/abcXyz?node-id=138-1797

Claude 会自动:

1. 调 whoami 探针确认 MCP 可用
2. 跑 doctor 体检(命名规范、布局结构、节点数)
3. 拉取图层树,按 sub- 前缀拆分 sub-agent 并行生成
4. 通过 Figma REST API 导出图片(带 use_absolute_bounds=true 严格按 bbox)
5. 逐 sub-block 视觉对比设计稿与生成代码
6. 输出完整可运行的 React + SCSS 文件

图层命名规范(给设计师看)

完整规范见 docs/design-guide.md。速查表:

| 前缀 | 含义 | 生成效果 | |------|------|---------| | sub- | 独立模块 | 单独 sub-agent 处理,生成独立组件 | | block- | 独立布局块 | HTML/CSS 隔离的容器,不可点击 | | img- | 整块图片 | 整层导出为 <img>,不递归 | | bg- | 背景图 | 写父元素 background-image,不递归 | | bgc- | 父级背景与盒级装饰 | 写父元素 fills / strokes / cornerRadius / box-shadow,不递归 | | font- | 强制文字 | 生成文字节点 | | btn- | 可点击区域 | 包裹可点击容器 | | scrollx- / scrolly- | 横向/纵向滚动 | overflow + 隐藏滚动条,继续递归子层 | | fixed- | 视口固定定位 | position: fixed,依赖 Figma constraints | | x- | 忽略 | 完全不生成代码 |

修饰前缀可叠加:

| 组合 | 效果 | |------|------| | sub-img-qa | 独立模块 + 整块图片 | | btn-img-banner | 可点击 + 整块图片 | | fixed-btn-back-top | 固定定位 + 可点击按钮 | | sub-scrollx-cards | 独立模块 + 横向滚动 |

禁止叠加:

• scrollx- 不能和 img- / bg- / bgc- / btn- / x- 共存
• scrollx- 不能和 scrolly- 共存
• fixed- 不能和 bg- / bgc- / x- 共存(不生成节点,fixed 无处可挂)

配置文件 skill-figma-d2c.config.json

完整字段说明见主 SKILL templates/skills/skill-figma-d2c/SKILL.md §0。关键字段:

{
  "project": {
    "framework": "react",         // react | rn
    "styleFormat": "scss"         // scss / scss-modules / less / less-modules / css / css-modules / tailwind / inline
  },
  "figma": {
    "token": "figd_xxx"           // Figma Personal Access Token,用于 REST API 导出图片
  },
  "merge": { "mode": "component" }, // component | flat
  "unit": {
    "figmaBase": 375,             // 设计稿基准宽度
    "outputUnit": "px",           // px | vw | rem
    "outputBase": 750,            // 输出基准
    "scale": 2                    // 换算倍数
  },
  "images": {
    "assetsDir": "static/",
    "imageBaseUrl": "http://127.0.0.1:8080/",
    "preserveEffectIds": []       // 例外清单:哪些 nodeId 导出时不带 use_absolute_bounds
  },
  "layers": {
    "sub": "sub-",
    "fixed": "fixed-",
    // ...11 类前缀,可重命名
  },
  "output": { "dir": "pages/" },
  "health": {
    "enabled": true,              // 是否启用前置体检
    "blockOnError": true,         // 体检 grade=F 时是否阻塞生成
    "thresholds": { /* 9 项阈值 */ },
    "rules": {}                   // 可针对单条规则改 level / 关闭
  }
}

命令清单

# 在业务项目根目录下使用
npx @double-codeing/skill-figma-d2c init      # 交互式初始化(推荐)
npx @double-codeing/skill-figma-d2c install   # 仅复制模板文件,不交互
npx @double-codeing/skill-figma-d2c help      # 显示帮助

前置依赖:Figma MCP

Figma 官方 MCP 需要在 Claude Code 中手动安装,init 脚本无法替你装。

安装步骤

1. 打开 Claude Code
2. 进入 Settings → Extensions,搜索 Figma
3. 找到 Figma 官方插件,点击安装
4. 按提示完成浏览器 OAuth 认证

可用性验证

跑 SKILL 时 Claude 会在步骤 -1 调 mcp__plugin_figma_figma__whoami 探针。四种结果会分别给出独立提示:

| 探针结果 | 含义 | 处理 | |---------|------|------| | 成功 | MCP 已装、已认证、工作正常 | 继续 | | Tool not found | MCP 完全没装 | 提示按上面 4 步安装 | | Unauthorized | 装了但未 OAuth | 提示完成浏览器认证 | | Permission denied | 装了但当前账号无该稿权限 | 提示更换账号或邀请 |

设计稿体检(Doctor)

health.enabled: true 时(默认),主 SKILL 在生成代码前会自动跑一次设计稿体检:

• NAM 系列:命名规范(NAM001-NAM014)
• LAY 系列:布局合理性(LAY001-LAY013)
• STR / STY / AST / FEA:嵌套深度 / 颜色对比度 / 资产体积 / 整体规模

体检完毕输出 grade(A/B/C/D/F)+ 阻塞决策。grade=F && blockOnError=true 时会停下来等用户确认。

报告自动写入 {output.dir}/.d2c-health-{nodeName}-{timestamp}.md。

体检规则完整定义见 docs/d2c-health-check-spec.md。

项目结构

skill-figma-d2c/
├── bin/install.js                    ← npx 入口(init / install / help 三命令)
├── templates/
│   ├── skills/
│   │   ├── skill-figma-d2c/SKILL.md       ← 主 D2C 流程(~1100 行执行手册)
│   │   └── skill-figma-d2c-doctor/SKILL.md ← 体检流程
│   ├── skill-figma-d2c.config.json   ← 配置文件模板
│   └── code-connect/mappings.json    ← Figma 组件映射模板
├── docs/
│   ├── design-guide.md               ← 给设计师的命名规范指南
│   └── d2c-health-check-spec.md      ← 体检规则源(含 P0/P1/P2 优先级)
└── package.json

故障排查

| 现象 | 入口 | |------|------| | 切出来的图带画板背景色 / 光晕外扩 | /v1/images API 必须带 use_absolute_bounds=true(主 SKILL §4.4) | | 切图把 bg- 和 bgc- 揉成一张图 | bgc- 嵌在 bg- 子树内是错误结构(doctor NAM013 / 主 SKILL §bg- 内嵌 bgc- 的处理) | | 列表项被切成静态图 | sub-scrolly- 必须递归子层,不能整体导出(主 SKILL §scrollx-/scrolly- 自检 4 行) | | Figma token 过期 / 缺失生成失败 | 自动走 L1→L2→L3 兜底链(主 SKILL §4.4.1) | | position: fixed 元素跟着祖先滚动 | 祖先链有 transform / filter / blur 导致 fixed 退化(doctor LAY013) | | doctor.run() 函数找不到 | SKILL.md 是 LLM 操作手册(自然语言),不是可执行代码——任何 doctor.run({...}) 都是伪代码(主 SKILL 顶部「执行模型说明」) |

License

MIT