# fig2code-skill

**Repository Path**: rtsthcom/fig2code-skill

## Basic Information

- **Project Name**: fig2code-skill
- **Description**: Fig2Code Skill — 将 Figma 设计稿精准转换为 HTML 代码的技能包。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-25
- **Last Updated**: 2026-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fig2Code — Figma 设计稿精准转 HTML 技能包

从 Figma 设计稿稳定还原前端代码的 Agent Skill：解析 Figma 链接 → 拉取节点数据 → 翻译为标准 DSL → 生成 HTML / 前端代码。不绑定技术栈，技术栈跟随目标项目已有代码。

| | |
| --- | --- |
| Skill 名称 | `fig2code`（对外展示名：**Fig2Code Skill**） |
| GitHub | [fig2code-skill](https://github.com/rtsthcom/fig2code-skill) |
| Gitee | [fig2code-skill](https://gitee.com/rtsthcom/fig2code-skill) |
| npm | [`@rtsthcom/fig2code-skill`](https://www.npmjs.com/package/@rtsthcom/fig2code-skill) |

[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?style=flat-square)](#前置要求)
[![Figma API](https://img.shields.io/badge/Figma%20API-REST%20%2B%20MCP-F24E1E?style=flat-square)](#取数通道)
[![npm](https://img.shields.io/badge/npm-%40rtsthcom%2Ffig2code--skill-CB3837?style=flat-square)](https://www.npmjs.com/package/@rtsthcom/fig2code-skill)
[![License](https://img.shields.io/badge/license-MIT-3178C6?style=flat-square)](#license)

## 安装

将本仓库（或 npm 包内容）复制到 Agent 的 skills 目录，目录名保持 `fig2code`：

```bash
# 从 Gitee（国内推荐）
git clone https://gitee.com/rtsthcom/fig2code-skill.git
cp -r fig2code-skill <skills-root>/fig2code

# 从 GitHub
git clone https://github.com/rtsthcom/fig2code-skill.git
cp -r fig2code-skill <skills-root>/fig2code

# 或从 npm
npm pack @rtsthcom/fig2code-skill
# 解压后把包内容放到 <skills-root>/fig2code
```

常见 `<skills-root>`：

| 客户端 | 项目级 | 全局 |
| --- | --- | --- |
| Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
| Codex | `.codex/skills/` | `~/.codex/skills/` |
| Claude Code | `.claude/skills/` | — |
| Trae | `.trae/skills/` | `~/.trae/skills/` |
| Trae Work | `.trae/skills/` | `~/.trae-cn/skills/` |

## 特性

- **REST 为权威主路径**：以节点 REST JSON 作为 DSL 唯一输入，不依赖 MCP、不靠截图或记忆脑补。
- **MCP 可选 + 智能降级**：MCP 仅做预览与连通确认；触发 `429` 频次限制时自动切回 REST，流程不中断。
- **确定性翻译**：`raw → 标准 DSL → 前端代码` 逐字段映射（见 `references/layout-mapping.md`），不推断。
- **无损 compact**：DSL 默认 compact，仅省略与 CSS 默认值一致的字段；`--no-compact` 可保留全量。位图压缩保留 PNG 回退，SVG 原样复制。
- **过程可见**：长任务脚本输出机器可读 `PROGRESS` 与人类可读进度条，支持并发与 `429` 退避重试。

## 前置要求

| 依赖 | 说明 |
| --- | --- |
| Node.js | ≥ 18；走代理建议 ≥ 21（内置 `node:undici` 的 `ProxyAgent`），否则 `npm i undici` |
| Figma 令牌 | 项目根 `.env.local` 写入 `FIGMA_API_KEY`，需勾选 `file_content:read` + `file_metadata:read` |
| sharp | 仅压缩位图时需要，在前端目录 `npm i -D sharp` |

## 快速开始

脚本一律在**项目根目录**执行，`<skill-dir>` 替换为技能实际安装路径。

```bash
# 1. 配置密钥
cp .env.local.example .env.local   # 填入真实 FIGMA_API_KEY

# 2. 取数（REST，关键路径）
node <skill-dir>/scripts/fetch-figma.mjs --url "<figma链接>" --out docs/figma/raw

# 3. 生成标准 DSL（默认 compact）
node <skill-dir>/scripts/extract-figma-dsl.mjs \
  docs/figma/raw/<page>__<id>.json docs/figma/dsl/<page>__<id>.dsl.json

# 4. 切图（无切图节点可跳过）
node <skill-dir>/scripts/export-svg.mjs docs/figma/raw/<page>__<id>.json \
  --url "<链接>" --export "ICON/back=frontend/src/assets/raw/back.svg"

# 5. 压缩位图
node <skill-dir>/scripts/optimize-assets.mjs
```

生成代码时读 **compact DSL**，按 `references/layout-mapping.md` 逐字段翻译，不要 Read 整份 raw JSON。

## 配置变量

`.env.local` 支持的变量，完整模板见 `.env.local.example`：

| 变量 | 必填 | 说明 |
| --- | --- | --- |
| `FIGMA_API_KEY` | 是 | Figma 个人访问令牌 |
| `FIGMA_FILE_KEY` | 否 | 文件 key；有 `--url` / `--file-key` 时可不写 |
| `FIGMA_ASSETS_DIR` | 否 | 切图根，默认 `frontend/src/assets` |
| `FIGMA_PROXY` | 否 | 内网代理（MCP 与 REST 脚本均读取） |

## 取数通道

| 通道 | 角色 | 说明 |
| --- | --- | --- |
| REST 脚本 | **默认主路径** | `fetch-figma.mjs` 的节点 JSON 是 `extract-figma-dsl.mjs` 的合法输入 |
| Figma MCP | 可选预览 / 连通确认 | 不用于取值；`design_context` 不得作为 DSL 输入 |

截图仅用于视觉校对，默认不拉取、不读取。

## 常用脚本

| 脚本 | 用途 |
| --- | --- |
| `fetch-figma.mjs` | 批量拉取原始节点数据（`--url` / `--ids` / `--manifest`） |
| `fetch-screenshots.mjs` | 校对设计稿时的 Frame 截图（默认不跑） |
| `extract-figma-dsl.mjs` | raw JSON → 标准 DSL（默认 compact，`--no-compact` 全量） |
| `outline.mjs` | raw JSON 树形大纲（`--focus` 聚焦、`--text-only`） |
| `node-info.mjs` / `subtree.mjs` | 按节点名回查填充 / 圆角 / 子树 |
| `extract-paths.mjs` | 提取 `fillGeometry` 矢量 path（需 `--geometry paths`） |
| `audit-opacity.mjs` | 核对 paint 级透明度是否都还原为 `rgba()` |
| `export-svg.mjs` | 按节点名导出 SVG / PNG / JPG |
| `optimize-assets.mjs` | `raw/` → `icons/` + `images/`（sharp） |
| `parse-figma-url.mjs` | 分享链接 → `{ fileKey, nodeId }` |
| `self-check.mjs` | 无网络自检（链接解析 / 命名 / 进度格式） |

完整命令、参数与故障排查见 `references/tooling.md`。

## 目录结构

```
fig2code/                     # 安装到 skills 后的目录名（Skill 名称：fig2code）
├── SKILL.md                  # 技能定义与执行流程
├── README.md                 # 本文件
├── package.json              # npm：@rtsthcom/fig2code-skill
├── agents/openai.yaml        # 对外展示名：Fig2Code Skill
├── LICENSE
├── .env.local.example        # 密钥配置模板
├── mcp/                      # MCP 配置模板（Framelink / Figma 官方 remote）
├── references/               # 翻译规则、工具索引、DSL schema、压缩参数等
└── scripts/                  # 取数 / 提取 / 切图 / 自检脚本
```

## 安全

- `FIGMA_API_KEY` 只从环境变量 / `.env.local` / 密钥库读取，禁止硬编码进代码或 MCP 配置模板。
- `.env.local` 与 `temp/` 必须加入 `.gitignore`，不得提交。

## 参考文档

| 文件 | 内容 |
| --- | --- |
| `SKILL.md` | 触发条件、前置、取数通道、执行流程 |
| `references/tooling.md` | 工具索引、命令、产物命名、MCP、故障排查 |
| `references/layout-mapping.md` | Figma 字段 → 代码翻译表 |
| `references/figma-dsl-schema.json` | DSL 结构定义 |
| `references/asset-rules.md` | 切图格式 / 倍率 / 命名 / 存放 |
| `references/compression.md` | 压缩参数 |
| `mcp/README.md` | MCP 配置模板与接入步骤 |

## 免责声明

本项目非 Figma 官方出品，与 Figma, Inc. 无任何关联或背书关系。`Figma` 是 Figma, Inc. 的商标，本项目仅作描述性引用。

## License

本项目采用 [MIT License](LICENSE) 开源协议。