figma-dev-tools

🎨 Figma Dev Tools v1.4.21

Figma → 任意前端框架 设计到代码一键转换 MCP 服务器

English | 中文

打通 Figma 设计与前端研发的完整工具链，支持 🖥️ GUI 可视化配置向导、设计 Tokens 智能提取、高保真组件生成（React/Vue/Svelte/微信小程序/HTML 等）、资源自动下载、跨编辑器 MCP 集成、设计稿变更自动再生成（Watch） 与 现状代码差异对比（Compare）。专为 AI Agent 优化，解决 div soup、上下文爆炸、hex 写死、资源路径处理、Flex 布局变形、无障碍缺失、响应式适配、付费墙兜底等核心痛点。

✨ v1.4.20–v1.4.21 新能力

📜 版本历史

✨ 功能亮点

🚀 快速开始

📚 详细指南见 QUICKSTART.md（中文）/ QUICKSTART.en-US.md（英文）。

三步上手

① 启动 GUI 配置（推荐 ⭐）

npx figma-dev-tools gui

浏览器自动打开，按引导完成：语言选择 → Token 配置（自动验证）→ 编辑器检测一键安装 → 框架偏好 → 完成。

② 或零配置 npx 直接运行

npx -y figma-dev-tools --figma-api-key=your-figma-token-here

③ 或一键安装（长期使用）

npx figma-dev-tools install   # 自动检测 8 个编辑器并配置 MCP

获取 Figma Token

1. 登录 Figma → 右上角头像 → Settings → Account
2. Personal access tokens → Generate new token → 勾选 File content (Read only)
3. 复制 Token（⚠️ 只显示一次）

Token 可通过 GUI 界面输入（推荐）、figma-dev token set 安全存储、--figma-api-key 参数、.env 文件或 MCP env 配置传入。详见 QUICKSTART.md。

第一个示例

在 AI 编辑器中直接对话：

帮我用 figma-dev-tools 还原这个 Figma 设计稿：
https://www.figma.com/design/xxxxx/MyProject?node-id=23-11032
场景名：landing-page  组件名：HeroSection

AI 将自动执行：figma_lint_design → figma_parse_url → figma_get_metadata → figma_get_screenshot → figma_generate_jsx → figma_download_assets。

CLI 快速体验

figma-dev gui                    # GUI 配置面板
figma-dev info "<figma-url>"     # 查看文件信息
figma-dev lint "<figma-url>"     # 设计规范预检
figma-dev jsx "<figma-url>" --name HeroSection --scene landing-page
figma-dev vue "<figma-url>" --name HeroSection --vue-version 3
figma-dev svelte "<figma-url>" --name HeroCard --style tailwind   # Svelte 4（tailwind/unocss/css-modules）
figma-dev batch "<figma-url>" --prefix Landing --framework react
figma-dev structured "<figma-url>" --format json --output ./data.json
figma-dev sync "<figma-url>" --format oklch --output ./src/styles
figma-dev token set              # 安全存储 Token
figma-dev lang switch            # 切换中英文

🔧 MCP 工具参考

共 28 个 MCP 工具（v1.4.20，以冒烟测试枚举为发布闸门），按使用流程排列：

说明：动画/动效检测与交互逻辑提取不是独立 MCP 工具，由 animation-detector.ts、interaction-inferrer.ts 在代码生成管线内自动运行，结论以增强报告/注释形式随生成结果返回。

常用工具简要参数

{
  figmaUrl?: string;           // Figma 链接（可替代 fileKey+nodeId）
  fileKey?: string;
  nodeId?: string;
  componentName?: string;      // 组件名（如 HeroSection）
  sceneName?: string;          // 场景名（用于资源路径）
  maxDepth?: number;           // 默认 15（1-30）
  styleFormat?: 'tailwind' | 'unocss' | 'css-modules' | 'styled'
              | 'emotion' | 'less' | 'sass'
              | 'vanilla-extract' | 'panda';
  unocssAttributify?: boolean; // UnoCSS 归因模式，仅 styleFormat=unocss
  componentLibrary?: 'auto' | 'none' | 'shadcn-ui' | 'ant-design';
                               // v1.4.20：语义节点直接替换为库组件；auto 按依赖检测
  typescript?: boolean;        // 默认 true
  inference?: {                // 智能推断四项分项开关（默认全开）
    grid?: boolean;
    icons?: boolean;
    darkMode?: boolean;
    motion?: boolean;
  };
  skipEnhancements?: boolean;  // 跳过全部增强
  skipLintCheck?: boolean;
  tokenProfile?: string;
}

{
  figmaUrl?: string;  fileKey?: string;  nodeId?: string;
  componentName?: string;  sceneName?: string;
  vueVersion?: 2 | 3;                     // 默认 3：script setup；2：Options API
  styleFormat?: 'tailwind' | 'unocss' | 'css-modules' | 'less' | 'sass';
  componentLibrary?: 'auto' | 'none' | 'element-plus' | 'ant-design-vue';
                                          // v1.4.20：语义节点直接替换为库组件
  unocssAttributify?: boolean;  typescript?: boolean;  // 默认 true
  inference?: { grid?: boolean; icons?: boolean; darkMode?: boolean; motion?: boolean };
  skipEnhancements?: boolean;  skipLintCheck?: boolean;
}

{
  figmaUrl?: string;  fileKey?: string;
  nodeId: string;              // 页面/大 Frame 根节点（必填）
  nodeIds?: string[];          // 显式区块 ID；省略=自动拆分
  componentNamePrefix?: string;// 如 'Landing' → LandingHeader/LandingHero
  framework?: 'react' | 'vue' | 'svelte'; // 默认 react
  vueVersion?: 2 | 3;  styleFormat?: string;
  componentLibrary?: 'auto' | 'none' | 'shadcn-ui' | 'ant-design'
                   | 'element-plus' | 'ant-design-vue'; // 按 framework 校验，跨框架触网前报错
  unocssAttributify?: boolean;
  inference?: { grid?: boolean; icons?: boolean; darkMode?: boolean; motion?: boolean };
  skipEnhancements?: boolean;
}

💡 其余工具的完整参数说明见 QUICKSTART.md 或 SKILL.md。

自定义组件库映射（v1.4.19）

在项目根放置 .figma-dev/components.json（draft-07 schema），可按 Figma 节点名/组件 key 指定导入的库组件（如 shadcn/ui、Ant Design、Element Plus）与 props 透传规则。详见 QUICKSTART.md。

组件库直接生成（v1.4.20，WBS-P2-11/12/13）

jsx/vue/batch 命令与 MCP 三工具新增 componentLibrary（CLI：--component-library），把语义节点直接替换为库组件标签与 import，不再只给建议：

• auto（默认）/none：auto 按项目真实依赖（package.json 三类 deps + shadcn 的 components/ui 目录/components.json）检测，无证据降级为原生标签并给出 warning；
• 保守门控：节点需 role+名称两类证据（置信度 ≥70/100），误替换恒为 0；Dialog/Tabs/Avatar 仅替换容器标签并输出手工调整警告，不自动展开多层 DOM；
• 跨框架/非法值在触网前报错（FDT-UI-LIB-FRAMEWORK-MISMATCH / FDT-UI-LIB-UNKNOWN）；Svelte 管线不适用该参数。

figma-dev jsx "<url>" --component-library shadcn-ui
figma-dev vue "<url>" --component-library element-plus
figma-dev batch "<url>" --framework vue --component-library auto

🧭 框架 × 样式支持矩阵

¹ 仅旧管线支持。不支持的组合会在触网前经 zod/注册表双重校验返回可读错误（如 Svelte 指定 styled 在触网前被拒）。微信小程序 figma-dev weapp 自 v1.4.20 起为正式能力（WXML/WXSS/JS/JSON 四件套）；uni-app/Taro 计划后续版本 experimental 接入。

💻 CLI 命令参考

npm install -g figma-dev-tools
figma-dev <command> [options]
# 或 npx 直接运行
npx figma-dev-tools <command> [options]

CLI 核心示例

# 🖥️ GUI 配置面板
figma-dev gui

# ⚛️ 生成 React + Tailwind 组件
figma-dev jsx "https://www.figma.com/design/xxx/yyy?node-id=23-11032" \
  --name HeroSection --scene landing-page

# 🟢 生成 Vue3 SFC（UnoCSS 归因模式）
figma-dev vue "https://www.figma.com/design/xxx/yyy?node-id=23-11032" \
  --name HeroSection --vue-version 3 --style unocss --attributify

# 🧩 直接映射为 shadcn/ui 组件（auto 也可按当前项目依赖自动判定）
figma-dev jsx "https://www.figma.com/design/xxx/yyy?node-id=23-11032" \
  --name SignupForm --component-library shadcn-ui

# 📦 整页批量生成（语义区块拆分）
figma-dev batch "https://www.figma.com/design/xxx/yyy" \
  --prefix Landing --framework react --out ./src/components

# 🧠 关闭部分智能推断
figma-dev jsx "<figma-url>" --name HeroSection --no-smart-dark --no-smart-motion

# 🟠 生成 Svelte 4 组件
figma-dev svelte "<figma-url>" --name HeroCard --style tailwind

# 📱 生成微信小程序页面
figma-dev weapp "<figma-url>" --name GoodsList --page --unit rpx

# 🔄 启动 Watch 模式（Figma 变更自动再生成）
figma-dev watch start "<figma-url>" --framework react --out ./src/components

# 🪙 同步 W3C DTCG Tokens
figma-dev sync "<figma-url>" --output-format dtcg

# 🏢 企业内网自定义 CA
$env:FIGMA_CA_CERT_PATH="C:\certs\corporate-root-ca.pem"   # PowerShell
export FIGMA_CA_CERT_PATH=/etc/ssl/corp-ca.pem              # bash/zsh

# 📊 获取结构化数据（JSON 输出到文件）
figma-dev structured "<figma-url>" --format json --output ./data.json

# 🖼️ 批量下载资源
figma-dev assets "<figma-url>" --scene landing-page --nodes "23-11032,23-11050" --scale 2

# 🔐 Token 与语言
figma-dev token set -t figd_your_token_here
figma-dev lang set zh-CN
figma-dev -l en-US sync --help   # 英文帮助示例

🖥️ 支持的编辑器（8 个）

💡 运行 figma-dev gui 可自动检测已安装编辑器并一键配置。

MCP 配置模板

{
  "mcpServers": {
    "figma-dev-tools": {
      "command": "npx",
      "args": ["-y", "figma-dev-tools", "--figma-api-key=figd_your_token_here"]
    }
  }
}

Zed 需将 mcpServers 改为 mcp_servers。详见 QUICKSTART.md。

⚙️ 配置说明

环境变量（.env）

FIGMA_ACCESS_TOKEN=your-figma-token-here     # 必需：Figma Token
FIGMA_OAUTH_TOKEN=                           # 可选：OAuth Token（企业版）
FIGMA_API_BASE=https://api.figma.com        # 可选：自定义 API 端点
FIGMA_DEFAULT_SCALE=2                        # 可选：默认导出倍率（1-4）
FIGMA_DEFAULT_COLOR_FORMAT=oklch             # 可选：默认颜色格式
FIGMA_ASSETS_BASE_DIR=public                 # 可选：资源输出目录
FIGMA_CDN_PREFIX=/                           # 可选：CDN 前缀
FIGMA_DEFAULT_LANG=zh-CN                     # 可选：默认语言（zh-CN/en-US）
FIGMA_GUI_PORT=54321                         # 可选：GUI 端口
FIGMA_CA_CERT_PATH=/path/to/ca.pem          # 可选：企业自定义 CA 证书

Token 读取优先级

1. 命令行参数 --figma-api-key / -t / --token
2. GUI 界面配置并保存的 Token
3. 安全存储默认 Token（figma-dev token set）
4. MCP 工具调用时 tokenProfile 参数
5. MCP 配置 env.FIGMA_ACCESS_TOKEN
6. .env 文件 FIGMA_ACCESS_TOKEN
7. 系统环境变量 FIGMA_ACCESS_TOKEN

🏗️ 架构图

┌──────────────────────────────────────────────────────────────┐
│                        用户界面层                              │
│  ┌──────────────┐  ┌───────────────────────────────────────┐ │
│  │  💻 CLI 终端  │  │  🖥️ GUI 可视化配置面板 (v1.3.0)       │ │
│  │  22 个顶层命令 │  │  欢迎页→语言→Token→编辑器→框架→完成   │ │
│  └──────┬───────┘  └──────────────────┬────────────────────┘ │
└─────────┼─────────────────────────────┼──────────────────────┘
          └─────────────┬───────────────┘
                        │ stdio (MCP) / HTTP (GUI)
                        ▼
┌──────────────────────────────────────────────────────────────┐
│              figma-dev-tools MCP Server v1.4.19               │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │  figma-url  │→│ figma-client │→│ node-processor        │ │
│  │  URL 解析    │  │ REST API+缓存 │  │ 层级精简+语义标注     │ │
│  └─────────────┘  └──────────────┘  └──────────────────────┘ │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │code-gen     │  │style-renderer│  │ 付费墙兜底 (v1.4.4)   │ │
│  │JSX/Vue 生成  │  │9 套样式注册表 │  │ BrowserPool+Cache    │ │
│  └─────────────┘  └──────────────┘  └──────────────────────┘ │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │token-store  │  │ i18n 中英双语 │  │ GUI 服务器 (v1.3.0)   │ │
│  │🔐 安全存储   │  │ zh-CN/en-US  │  │ 静态资源+Express     │ │
│  └─────────────┘  └──────────────┘  └──────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

📋 项目结构

figma-dev-tools/
├── bin/figma-dev.js           # CLI 入口
├── mcp-standalone.mjs         # 零配置 MCP 入口
├── gui/                       # GUI 可视化配置面板
│   ├── index.html / app.js / styles.css
├── src/
│   ├── index.ts               # MCP 服务器入口
│   ├── types.ts               # 类型定义
│   ├── i18n/                  # 国际化（zh-CN/en-US）
│   ├── cli/index.ts           # CLI 命令定义
│   ├── services/
│   │   ├── figma-client.ts    # Figma REST API 客户端 + 加密缓存
│   │   ├── node-processor.ts  # 节点树精简 + 语义标注 + 层级修复
│   │   ├── design-context.ts  # 渐进式上下文服务
│   │   ├── token-matcher.ts   # 多级 Token 匹配
│   │   ├── tailwind-mapper.ts # Tailwind 属性映射
│   │   ├── code-generator.ts  # JSX 代码生成
│   │   ├── vue-generator.ts   # Vue SFC 代码生成
│   │   ├── style-renderers/   # v1.4.19：9 套样式注册表
│   │   ├── flex-fixer.ts      # Flex 布局修复
│   │   ├── a11y-enhancer.ts   # 无障碍增强
│   │   ├── design-system.ts   # 设计系统对齐
│   │   ├── responsive-inferrer.ts # 响应式推断
│   │   ├── design-linter.ts   # 设计规范检查
│   │   ├── browser-fallback.ts # 付费墙浏览器兜底 (v1.4.4)
│   │   ├── screenshot-cache.ts # 截图缓存 (v1.4.4)
│   │   ├── ocr-service.ts     # OCR 文本提取 (v1.4.14)
│   │   ├── asset-downloader.ts # 资源下载（SVGO 优化）
│   │   ├── svg-sprite-generator.ts # SVG Sprite 生成
│   │   ├── token-store.ts     # Token 安全存储
│   │   ├── tokens-extractor.ts # Tokens 提取
│   │   ├── code-formatter.ts  # Prettier 代码格式化
│   │   └── file-writer.ts     # 文件写入
│   └── utils/                 # 工具函数（URL 解析、颜色转换、安全防护等）
├── dist/                      # 编译输出
├── .env.example               # 环境变量模板
├── FIGMA-DESIGN-GUIDELINES.md # Figma 设计规范指南
├── QUICKSTART.md              # 快速开始指南
├── SKILL.md                   # AI Agent 使用指南
└── LICENSE                    # MIT 许可证

❓ FAQ

🆚 竞品对比

vs 商业工具

vs 开源 / 官方工具

差异化优势

• 付费墙兜底：独有的 BrowserFallbackService，API 付费墙失败时自动 Playwright 截图保底
• 还原度校验闭环：figma_verify_fidelity 像素 diff + 差异热力图 + 量化评分（0-100%）
• 框架无关结构化数据：figma_get_structured_data 输出标准 JSON，支持任意框架
• 开源 + 免费 + 全功能：MIT 许可，无需付费席位即可使用全部 23 个 MCP 工具

📜 License

MIT © figma-dev-tools contributors