# 快速开始

从零安装 Fig2Code Skill，完成第一次「Figma 链接 → DSL」转换。

## 1. 前置条件

| 依赖 | 说明 |
| --- | --- |
| Node.js | ≥ 18；走代理建议 ≥ 21 |
| Figma 令牌 | 个人访问令牌，勾选 `file_content:read` + `file_metadata:read` |
| Agent 客户端 | Cursor / Codex / Claude Code / Trae 等（任选其一） |

在 [Figma → Settings → Security → Personal access tokens](https://www.figma.com/settings) 创建令牌。

## 2. 安装技能

将仓库复制到 Agent 的 skills 目录，**目录名保持 `fig2code`**：

```bash
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/` |

下文把技能路径记为 `<skill-dir>`（例如 `.cursor/skills/fig2code`）。

## 3. 配置密钥

在**业务项目根目录**（不是 skill 目录）创建环境文件：

```bash
cp <skill-dir>/.env.local.example .env.local
```

编辑 `.env.local`，填入真实令牌：

```env
FIGMA_API_KEY=figd_你的令牌
# 可选：有 --url 时可省略
# FIGMA_FILE_KEY=xxxx
# FIGMA_ASSETS_DIR=frontend/src/assets
# FIGMA_PROXY=http://127.0.0.1:7890
```

确保 `.env.local` 已在 `.gitignore` 中，勿提交。

## 4. 第一次转换

脚本一律在**项目根目录**执行。准备一条带 `node-id` 的 Figma 分享链接，例如：

`https://www.figma.com/design/XXXXXXXX/Name?node-id=7-3742`

### 步骤 A：拉取原始节点

```bash
node <skill-dir>/scripts/fetch-figma.mjs \
  --url "https://www.figma.com/design/XXXXXXXX/Name?node-id=7-3742" \
  --out docs/figma/raw
```

成功后会得到类似 `docs/figma/raw/<page>__7-3742.json` 的文件（`:` 会写成 `-`）。

### 步骤 B：生成标准 DSL

```bash
node <skill-dir>/scripts/extract-figma-dsl.mjs \
  docs/figma/raw/<page>__7-3742.json \
  docs/figma/dsl/<page>__7-3742.dsl.json
```

默认输出 **compact** DSL（省略与 CSS 默认值一致的字段）。需要全量字段时加 `--no-compact`。

### 步骤 C（可选）：切图与压缩

有图标 / 位图节点时：

```bash
node <skill-dir>/scripts/export-svg.mjs docs/figma/raw/<page>__7-3742.json \
  --url "<同上链接>" \
  --export "ICON/back=frontend/src/assets/raw/back.svg"

# 位图压缩需在前端目录先: npm i -D sharp
node <skill-dir>/scripts/optimize-assets.mjs
```

无切图节点可跳过。

### 步骤 D：生成代码

在 Agent 对话中提供同一条 Figma 链接，或直接让 Agent 读取 compact DSL，按 `references/layout-mapping.md` 逐字段翻译为项目已有技术栈的 HTML/CSS（或 Vue / React 等）。**不要**把整份 raw JSON 读进对话。

## 5. 自检（可选）

无网络验证脚本与链接解析是否正常：

```bash
node <skill-dir>/scripts/self-check.mjs
# 或: npm run self-check（在 skill 目录内）
```

## 下一步

- [使用示例](examples.md)：看 DSL → HTML 对照
- [API 说明](api.md)：各脚本参数
- [配置说明](config.md)：目录约定与环境变量
- [常见问题](faq.md)：401 / 429 / 精度等问题