🎨 Figma Dev Tools v1.4.10

Figma → Cualquier framework frontend: servidor MCP de conversión de diseño a código con un solo clic

English | 中文

Cadena de herramientas completa que conecta el diseño de Figma con el desarrollo frontend, compatible con 🖥️ asistente de configuración visual GUI, extracción inteligente de Tokens de diseño, generación de componentes de alta fidelidad (React/Vue/Svelte/HTML, etc.), descarga automática de recursos, integración MCP entre editores. Optimizado para AI Agent, resolviendo problemas clave como div soup, explosión de contexto, hex fijos, manejo de rutas de recursos, deformación de Flex layout, falta de accesibilidad, adaptación responsiva, respaldo ante muros de pago, etc.

✨ v1.4.4 Respaldo ante muros de pago + Restauración de alta fidelidad + Optimización de rendimiento

Respaldo y restauración principales

Optimización de rendimiento (nuevo en v1.4.4)

Comparativa de rendimiento (antes y después de la optimización v1.4.4)

Configuración de optimización de rendimiento (opcional, compatible con versiones anteriores)

// 通过 BrowserFallbackService 配置
const service = new BrowserFallbackService({
  navigationTimeout: 20000,    // 导航超时（毫秒）
  renderTimeout: 10000,        // 渲染等待超时（毫秒）
  screenshotTimeout: 5000,     // 截图操作超时（毫秒）
  waitStrategy: 'hybrid',      // 等待策略：hybrid/conservative/aggressive
  maxRetries: 2,               // 最大重试次数
  retryBaseDelay: 500,         // 重试初始延迟（毫秒）
  enableScreenshotCache: true, // 启用截图缓存
  screenshotCacheTtl: 3600000, // 缓存有效期（毫秒，默认 1 小时）
  browserIdleTimeout: 60000,   // 浏览器空闲超时（毫秒，默认 60 秒）
});

Related MCP server: Figma MCP Server

📜 Resumen del historial de versiones

✨ Destacados de funciones

🚀 Inicio rápido

📚 ¿Quieres una guía rápida concisa y sincronizada con la versión? Consulta QUICKSTART.md (chino) / QUICKSTART.en-US.md (inglés). A continuación se detalla.

Modo cero: Configuración visual GUI (recomendado para principiantes ⭐)

Sin necesidad de recordar ningún comando, completa toda la configuración a través de la interfaz gráfica del navegador:

# 直接启动 GUI 配置面板
npx figma-dev-tools gui

# 或全局安装后
figma-dev gui

Al iniciar, se abrirá automáticamente el navegador (puerto predeterminado 54321, si está ocupado, intenta automáticamente 54322/54323), sigue los pasos guiados:

1. Página de bienvenida - Conoce las funciones de figma-dev-tools

2. Selección de idioma - Cambio bilingüe chino/inglés

3. Configuración de Token - Introduce el Token de Figma, verificación de validez en tiempo real

4. Detección de editores - Detecta automáticamente 8+ editores instalados, selecciona e instala la configuración MCP con un clic

5. Preferencia de framework - Elige el framework habitual (React/Vue/HTML)

6. Página de finalización - Configuración exitosa, proporciona enlaces a tutoriales de uso

💡 También puedes iniciar el modo GUI con el comando del asistente:

figma-dev wizard --gui
figma-dev init --gui

Modo uno: Ejecución directa con npx sin configuración (el más rápido)

Sin necesidad de instalación, inicia el servidor MCP con un solo comando:

# 直接通过 npx 运行，传入 API Key
npx -y figma-dev-tools --figma-api-key=your-figma-token-here

En la configuración MCP del editor, usa:

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

Modo dos: Instalación con un clic (recomendado para uso a largo plazo)

# npm
npx figma-dev-tools install

# pnpm
pnpm dlx figma-dev-tools install

# yarn
yarn dlx figma-dev-tools install

# bun
bunx figma-dev-tools install

El script de instalación automáticamente:

• Detecta los editores AI instalados (Trae/VS Code/Cursor/Windsurf/Claude Desktop/Zed/Cline/Roo Code, etc., 8+)

• Detecta automáticamente el gestor de paquetes (npm/pnpm/yarn/bun)

• Descarga/compila la herramienta

• Configura los ajustes MCP del editor correspondiente (Zed usa el campo mcp_servers)

• Genera la plantilla .env.example

💡 Forma aún más sencilla: ejecuta figma-dev gui para usar la interfaz gráfica y detectar e instalar la configuración del editor con un clic.

Modo tres: Instalación como dependencia del proyecto

# npm
npm install figma-dev-tools --save-dev

# pnpm
pnpm add figma-dev-tools -D

# yarn
yarn add figma-dev-tools --dev

# bun
bun add figma-dev-tools -d

Modo cuatro: Instalación desde el código fuente local

# 克隆或复制 figma-dev-tools 目录到项目中
cp -r figma-dev-tools/ your-project/tools/
cd your-project/tools/figma-dev-tools
npm install   # 或 pnpm install / yarn install / bun install
npm run build # 或 pnpm build / yarn build / bun run build

1. Obtener un Figma Access Token

1. Inicia sesión en Figma

2. Haz clic en el avatar en la esquina superior derecha → Settings → Account

3. Busca Personal access tokens → Generate new token

4. Introduce un nombre, marca File content (Read only)

5. Copia el Token generado (⚠️ solo se muestra una vez)

💡 Al usar la configuración GUI, pega directamente el Token en la interfaz del navegador para verificarlo y guardarlo automáticamente.

2. Configurar el Token

Método A: Configuración visual GUI (recomendado v1.3.0+)

figma-dev gui

En la interfaz del navegador, introduce el Token, verifica su validez en tiempo real y se almacena de forma segura automáticamente.

Método B: Almacenamiento seguro (recomendado v1.3.2+)

# 交互式保存 Token 到系统密钥链
figma-dev token set

# 或直接通过参数
figma-dev token set -t figd_your_token_here

Método C: Mediante parámetros de línea de comandos

npx figma-dev-tools --figma-api-key=your-figma-token-here
# 或短参数
npx figma-dev-tools -t your-figma-token-here

Método D: Mediante archivo .env

Crea un archivo .env en el directorio figma-dev-tools/:

FIGMA_ACCESS_TOKEN=your-figma-token-here

Método E: Configuración env en MCP

Añade en la configuración MCP del editor:

{
  "mcpServers": {
    "figma-dev-tools": {
      "command": "node",
      "args": ["<path>/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token-here"
      }
    }
  }
}

3. Primer ejemplo Figma → Código

React + Tailwind (recomendado, versión mejorada v1.4.0):

En el editor AI (como Trae), conversa directamente:

帮我用 figma-dev-tools 还原这个 Figma 设计稿：
https://www.figma.com/design/xxxxx/MyProject?node-id=23-11032

场景名：landing-page
组件名：HeroSection

La IA ejecutará automáticamente el siguiente flujo mejorado (v1.3.2):

1. figma_lint_design - Verificación previa de estándares de diseño (opcional, señala problemas)

2. figma_parse_url - Analiza el enlace

3. figma_get_metadata - Obtiene una visión general de la estructura de la página

4. figma_get_screenshot - Obtiene la referencia visual

5. figma_generate_jsx Genera código TSX con un clic (incluye corrección de Flex, mejora de a11y, alineación con sistema de diseño, inferencia responsiva)

6. figma_download_assets - Descarga recursos de imagen (optimización automática SVGO)

Otros frameworks (Vue/Svelte/HTML, etc.):

Usa la herramienta figma_get_structured_data para obtener la estructura JSON independiente del framework:

帮我用 figma_get_structured_data 获取这个 Figma 节点的结构化数据，然后生成 Vue 组件：
https://www.figma.com/design/xxxxx/MyProject?node-id=23-11032

Experiencia rápida con CLI

# 🖥️ 启动 GUI 可视化配置面板（v1.3.0 新，小白推荐）
npx figma-dev-tools gui

# 查看文件信息
npx figma-dev info "https://www.figma.com/design/xxxxx/MyProject?node-id=23-11032"

# 设计规范预检（v1.3.2 新）
npx figma-dev lint "https://www.figma.com/design/xxxxx/MyProject?node-id=23-11032"

# 生成 React 组件（增强版）
npx figma-dev jsx "https://www.figma.com/design/xxxxx/MyProject?node-id=23-11032" \
  --name HeroSection --scene landing-page

# 获取框架无关结构化数据（v1.1.0 新）
npx figma-dev structured "https://www.figma.com/design/xxxxx/MyProject?node-id=23-11032" \
  --format json --output ./hero-structured.json

# 同步 Design Tokens
npx figma-dev sync "https://www.figma.com/design/xxxxx/MyProject" \
  --format oklch --output ./src/styles

# 语言设置（v1.3.2 新）
npx figma-dev lang switch  # 交互式切换中英文
npx figma-dev lang set zh-CN

# Token 安全管理（v1.3.2 新）
npx figma-dev token set     # 保存 Token 到密钥链
npx figma-dev token list    # 列出已保存 Token

🔧 Referencia de herramientas MCP

Total de 19 herramientas MCP, ordenadas por flujo de uso:

Parámetros detallados de las herramientas

figma_generate_jsx (v1.4.0 mejorado, el más usado)

{
  figmaUrl?: string;           // Figma 链接（可替代 fileKey+nodeId）
  fileKey?: string;            // Figma 文件 Key
  nodeId?: string;             // 目标节点 ID
  componentName?: string;      // 组件名（如 HeroSection）
  sceneName?: string;          // 场景名（用于资源路径，如 landing-page）
  maxDepth?: number;           // 节点树最大遍历深度，默认 15（1-30）
  framework?: 'react' | 'vue'; // 目标框架，默认 react（v1.4.0 新增 vue）
  styleFormat?: 'tailwind' | 'unocss'; // 样式方案，默认 tailwind（v1.4.0 新增 unocss）
  skipEnhancements?: boolean;  // 是否跳过 v1.2.0 增强（Flex/a11y/设计系统/响应式）
  skipLintCheck?: boolean;     // 是否跳过设计规范检查提示
  accessToken?: string;        // 可选，优先用环境变量
}

Salida mejorada en v1.4.0:

• Código TSX completo de React + TypeScript + Tailwind (formateado con Prettier)

• 🔧 Informe de corrección Flex: lista de problemas de diseño corregidos automáticamente (deformación de iconos, truncamiento de texto, etc.)

• ♿ Informe de mejora de accesibilidad: etiquetas semánticas, texto alternativo, atributos ARIA añadidos

• 🎨 Sugerencias del sistema de diseño: sugerencias de coincidencia de variables de color/espacio/radio/sombra

• 📱 Sugerencias responsive: inferencia de puntos de corte, sugerencias de prefijos sm/md/lg

• ⚠️ Lista de tokens que requieren extensión @theme

• 🖼️ Lista de recursos a descargar (nodeId, nombre, tipo)

• 🧩 Indicaciones de componentes reutilizables

• Estadísticas de nodos simplificados

• ✅ Indicación de puntuación de normas de diseño (si es inferior a 80, se recomienda corregir primero)

figma_lint_design (nuevo en v1.3.2, preinspección de calidad de conversión a código)

{
  figmaUrl?: string;           // Figma 链接
  fileKey?: string;            // Figma 文件 Key
  nodeId?: string;             // 目标节点 ID（可选，默认检查整个文件）
  maxDepth?: number;           // 最大检查深度，默认 15（1-30）
  accessToken?: string;        // 可选
}

Elementos a verificar:

• Uso correcto de Auto Layout

• Normas de nomenclatura de capas

• Uso de cuadrícula de 4px/8px en espacios/tamaños/radios

• Reutilización de componentes

• Tamaño mínimo de clic para accesibilidad (48×48px)

• Profundidad de anidamiento

• Consistencia de estilos de texto

• Normas de uso de color

Salida:

• Puntuación de calidad de 0 a 100

• Clasificación de errores/advertencias/sugerencias

• Lista de problemas desglosada por categoría

• Sugerencias de corrección específicas

• Ver: FIGMA-DESIGN-GUIDELINES.md

figma_create_icon_sprite (nuevo en v1.3.2, generación de sprite SVG)

{
  svgDir: string;              // 包含 SVG 文件的目录
  outputPath: string;          // sprite.svg 输出路径
  typesPath?: string;          // 可选，TypeScript 类型文件路径
  prefix?: string;             // symbol id 前缀，默认 "icon-"
  removeFill?: boolean;        // 是否移除 fill 以便 CSS color 控制，默认 true
}

figma_get_structured_data (nuevo en v1.1.0, soporte para múltiples frameworks)

{
  figmaUrl?: string;           // Figma 链接（可替代 fileKey+nodeId）
  fileKey?: string;            // Figma 文件 Key
  nodeId: string;              // 目标节点 ID（必需）
  maxDepth?: number;           // 最大节点树深度，默认 15（1-30）
  accessToken?: string;        // 可选，优先用环境变量
}

Contenido de salida:

• Estructura JSON completa e independiente del framework, cada nodo contiene:

  • id / name - Identificador del nodo

  • role - Rol semántico (button/card/image/text/icon/section, etc.)

  • type - Tipo de nodo de Figma (FRAME/TEXT/RECTANGLE/GROUP/INSTANCE, etc.)

  • size - { width, height }

  • layout - Propiedades de diseño Flex (display/flexDirection/justifyContent/alignItems/gap/padding, etc.)

  • styles - Propiedades de estilo (color/backgroundColor/borderRadius/shadow/fontSize/fontWeight, etc.)

  • text - Contenido de texto (solo nodos TEXT)

  • asset - Información del recurso (nodos de imagen: tipo, formato, URL de descarga)

  • children - Array de nodos hijos

• Resumen de vista previa: rol semántico, tipo de nodo, tamaño, número total de nodos, número de colores, número de recursos, número de nodos de texto

• structuredContent - Árbol completo de nodos estructurados, se puede recorrer directamente para generar código de cualquier framework

Frameworks aplicables:

• ✅ React / Next.js / Remix (mejor con generate_jsx)

• ✅ Vue 2/3 / Nuxt

• ✅ Svelte / SvelteKit

• ✅ HTML / CSS nativo

• ✅ Angular

• ✅ SolidJS

• ✅ Qwik

• ✅ Astro

• ✅ Cualquier framework frontend

figma_download_assets

{
  figmaUrl?: string;
  fileKey: string;
  sceneName: string;           // 对应 public/<场景>/ 目录
  assetNodeIds: string[];      // 从 generate_jsx 获取的 nodeId 列表
  projectRoot?: string;        // 项目根目录，默认自动检测
  scale?: number;              // 导出倍率 1-4，默认 2
  svgFormat?: 'svg' | 'png';   // 矢量格式，默认 svg
  optimizeSvg?: boolean;       // 使用 SVGO 优化 SVG，默认 true
}

figma_extract_tokens

{
  figmaUrl?: string;
  fileKey: string;
  nodeId?: string;             // 可选，仅提取该节点下的 tokens
  colorFormat?: 'hex' | 'rgb' | 'oklch' | 'hsl';  // 默认 oklch（Tailwind v4 推荐）
  spacingUnit?: 'px' | 'rem';  // 默认 px
  tokenPrefix?: string;        // Token 名称前缀
}

💻 Referencia de comandos CLI

# 全局安装后使用
npm install -g figma-dev-tools
figma-dev <command> [options]

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

# 🖥️ v1.3.0 新：启动 GUI 可视化配置面板
npx figma-dev-tools gui

# 传入 API Key
npx figma-dev-tools --figma-api-key=your-token <command>
npx figma-dev-tools -t your-token <command>

# 切换语言（v1.3.2 新）
npx figma-dev-tools -l zh-CN <command>

Ejemplos de CLI:

# 🖥️ 启动 GUI 可视化配置面板（v1.3.0 新，小白推荐）
figma-dev gui

# 指定端口启动 GUI
figma-dev gui --port 3000

# 通过向导命令启动 GUI 模式
figma-dev wizard --gui
figma-dev init --gui

# 📌 查看当前版本号（v1.4.8 新增）
figma-dev -v

# 🔄 检查并更新到最新版本（v1.4.8 新增，自动处理 EBUSY 文件占用）
figma-dev --update

# 设计规范预检（v1.3.2 新）
figma-dev lint "https://www.figma.com/design/xxx/yyy?node-id=23-11032"

# 一键生成 Hero 区 React 组件（增强版）
figma-dev jsx "https://www.figma.com/design/xxx/yyy?node-id=23-11032" \
  --name HeroSection \
  --scene landing-page \
  --depth 8

# 获取框架无关结构化数据（JSON 格式输出到文件）
figma-dev structured "https://www.figma.com/design/xxx/yyy?node-id=23-11032" \
  --depth 8 \
  --format json \
  --output ./hero-data.json

# 批量下载资源（自动 SVGO 优化）
figma-dev assets "https://www.figma.com/design/xxx/yyy?node-id=23-11032" \
  --scene landing-page \
  --nodes "23-11032,23-11050,23-11080" \
  --scale 2

# 生成 SVG Sprite（v1.3.2 新，需先下载图标）
# 通过 MCP 工具 figma_create_icon_sprite 调用

# 保存 Token 到系统密钥链（v1.3.2 新）
figma-dev token set -t figd_your_token_here

# 切换到中文界面（v1.3.2 新）
figma-dev lang set zh-CN

🖥️ Editores compatibles (8+)

💡 La forma más sencilla de configurar: ejecuta figma-dev gui Inicia la interfaz gráfica, detecta automáticamente todos los editores instalados en tu equipo. Marca los editores que desees configurar y la instalación se completará con un clic, sin necesidad de buscar manualmente las rutas de los archivos de configuración.

Plantilla de configuración MCP

Formato estándar (Trae/VS Code/Cursor/Windsurf/Claude Desktop/Cline/Roo Code):

{
  "mcpServers": {
    "figma-dev-tools": {
      "command": "node",
      "args": ["<path-to-figma-dev-tools>/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token-here"
      }
    }
  }
}

Formato Zed (ten en cuenta que el nombre del campo es mcp_servers):

{
  "mcp_servers": {
    "figma-dev-tools": {
      "command": "node",
      "args": ["<path-to-figma-dev-tools>/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-figma-token-here"
      }
    }
  }
}

Método npx sin configuración (sin instalación local):

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

💡 Usa npx figma-dev-tools install o figma-dev gui para detectar automáticamente los editores y completar las rutas correctas. Zed usará automáticamente el campo mcp_servers.

⚙️ Instrucciones de configuración

Variables de entorno (.env)

Copia .env.example a .env y complétalo:

# 必需：Figma Personal Access Token
# 获取地址：https://www.figma.com/developers/api#access-tokens
FIGMA_ACCESS_TOKEN=your-figma-token-here

# 可选：Figma OAuth Token（企业版使用）
FIGMA_OAUTH_TOKEN=

# 可选：自定义 Figma API 端点（企业代理）
FIGMA_API_BASE=https://api.figma.com

# 可选：默认导出倍率（1-4，默认 2）
FIGMA_DEFAULT_SCALE=2

# 可选：默认颜色格式（hex/rgb/oklch/hsl，默认 oklch）
FIGMA_DEFAULT_COLOR_FORMAT=oklch

# 可选：资源输出基础目录（默认 public）
FIGMA_ASSETS_BASE_DIR=public

# 可选：资源 CDN 前缀（默认 /）
FIGMA_CDN_PREFIX=/

# v1.3.2 新增：默认语言（zh-CN/en-US）
FIGMA_DEFAULT_LANG=zh-CN

# v1.3.0 新增：GUI 默认端口（默认 54321）
FIGMA_GUI_PORT=54321

Prioridad de configuración MCP

Prioridad de lectura del Token:

1. Parámetro de línea de comandos --figma-api-key / -t / --token

2. Token configurado y guardado mediante la interfaz GUI (nuevo en v1.3.0, se guarda automáticamente en almacenamiento seguro)

3. Token predeterminado en almacenamiento seguro (nuevo en v1.3.2, guardado con figma-dev token set)

4. Parámetro accessToken proporcionado al invocar la herramienta MCP

5. env.FIGMA_ACCESS_TOKEN en la configuración MCP

6. FIGMA_ACCESS_TOKEN en el archivo .env

7. Variable de entorno del sistema FIGMA_ACCESS_TOKEN

🏗️ Diagrama de arquitectura

┌──────────────────────────────────────────────────────────────────────────────────┐
│                         用户界面层                                                 │
│  ┌──────────────┐  ┌──────────────────────────────────────────────────────────┐  │
│  │  💻 CLI 终端  │  │  🖥️ GUI 可视化配置面板 (v1.3.0)                           │  │
│  │  命令行交互   │  │  ┌──────┐ ┌──────┐ ┌───────┐ ┌────────┐ ┌──────────┐   │  │
│  │              │  │  │欢迎页│→│语言选│→│Token配│→│编辑器检│→│ 完成页    │   │  │
│  │              │  │  │      │ │择    │ │置验证 │ │测一键装│ │ 教程链接  │   │  │
│  └──────┬───────┘  │  └──────┘ └──────┘ └───────┘ └────────┘ └──────────┘   │  │
│         │          └──────────────────────────┬─────────────────────────────┘  │
│         │                                     │ 端口 54321/54322/54323          │
└─────────┼─────────────────────────────────────┼────────────────────────────────┘
          │                                     │
          └─────────────────┬───────────────────┘
                            │ HTTP (GUI) / stdio (MCP)
                            ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│                      figma-dev-tools MCP Server v1.4.10                           │
│     🖥️ GUI | 🌍 i18n | ♿ a11y | 🔧 Flex Fix | 📱 Responsive | 🔒 XSS | 🗂️ Hierarchy │
│                                                                                   │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────────────────────────┐ │
│  │  figma-url  │───▶│figma-client  │───▶│           Figma REST API            │ │
│  │  解析器      │    │ API 客户端    │    │            (figma.com)              │ │
│  └─────────────┘    └──────┬───────┘    └─────────────────────────────────────┘ │
│                            │ 🔒 AES-256-GCM 本地加密缓存                         │
│           ┌────────────────┼────────────────┐                                   │
│           ▼                ▼                ▼                                   │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐                          │
│  │node-processor│ │design-context│ │tokens-extractor│                          │
│  │ 节点精简     │ │ 渐进式上下文  │ │ Token 提取     │                          │
│  │ GROUP扁平化  │ │ metadata概览  │ │ Variables+Styles│                         │
│  │ 🗂️层级自动修复│ │ context详情   │ │                │                          │
│  │ 语义角色标注 │ │              │ │                │                          │
│  └──────┬──────┘  └──────┬───────┘  └───────┬───────┘                          │
│         │                │                   │                                  │
│         └────────┬───────┴───────────┬───────┘                                  │
│                  ▼                   ▼                                          │
│         ┌──────────────┐   ┌────────────────┐   ┌──────────────────┐          │
│         │token-matcher │   │tailwind-mapper │   │ design-linter    │          │
│         │多级Token匹配 │   │完整属性映射    │   │ ✅ 设计规范检查   │          │
│         │codeSyntax→   │   │flex/padding/   │   │ Auto Layout/命名  │          │
│         │精确→模糊匹配 │   │gap/shadow等    │   │ 间距/尺寸/无障碍  │          │
│         │              │   │               │   │ 🗂️父子层级错位检测│          │
│         └──────┬───────┘   └───────┬────────┘   └────────┬─────────┘          │
│                │                   │                     │                    │
│                └─────────┬─────────┘                     │                    │
│                          ▼                               ▼                    │
│                ┌──────────────────┐        ┌──────────────────────┐           │
│                │  code-generator  │───────▶│ v1.4.0 Enhancements │           │
│                │  React JSX生成   │        │ ┌──────────────────┐ │           │
│                │  语义标签+cn()    │        │ │ 🔧 flex-fixer    │ │           │
│                │  TODO标记        │        │ │ ♿ a11y-enhancer  │ │           │
│                │  🔒 XSS全链路防护 │        │ │ 🎨 design-system │ │           │
│                │  Prettier格式化  │        │ │ 📱 responsive    │ │           │
│                └────────┬─────────┘        │ │ 🎨 svg-inline    │ │           │
│         ┌───────────────┴──────────────┐   │ │ ✨ animation     │ │           │
│         ▼               ▼              ▼   │ └──────────────────┘ │           │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐              │           │
│  │asset-        │ │ vue-generator│ │ svg-inline   │              │           │
│  │downloader    │ │ Vue SFC生成  │ │ renderer     │              │           │
│  │图片/SVG下载  │ │              │ │ 矢量→内联SVG │              │           │
│  │SVGO优化      │ └──────────────┘ │ svgo优化     │              │           │
│  │publicCdnUrl()│                  └──────────────┘              │           │
│  └──────┬───────┘                                                │           │
│         │                                                        │           │
│         └──────────────┬─────────────────────────────────────────┘           │
│                        ▼                                                      │
│              ┌────────────────┐      ┌──────────────┐  ┌─────┐              │
│              │  file-writer   │      │  CLI 命令    │  │i18n │              │
│              │  文件写入       │      │ gui/lint/    │  │ zh/ │              │
│              │  CSS/Tailwind/ │      │ lang/token/  │  │ en  │              │
│              │  JSON/TSX/Vue  │      │ jsx/structur │  └─────┘              │
│              │  Prettier格式化│      │ ed/sync/asset│                       │
│              └────────┬───────┘      └──────┬───────┘                       │
│                       │                   │                                 │
│                       ▼                   ▼                                 │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────────────────┐ │
│  │svg-sprite-gen    │  │  token-store     │  │ 🖥️ GUI 服务器 (v1.3.0)       │ │
│  │SVG Sprite生成    │  │  🔐 安全存储      │  │ ┌───────┐ ┌───────┐ ┌──────┐ │ │
│  │TS类型定义        │  │  Keychain/凭据管  │  │ │index  │ │ app   │ │style │ │ │
│  └──────────────────┘  └──────────────────┘  │ │.html  │ │.js    │ │.css  │ │ │
│                                              │ └───────┘ └───────┘ └──────┘ │ │
│                                              │ 静态资源 + Express 服务        │ │
│                                              └──────────────────────────────┘ │
│                                                                               │
└───────────────────────────────────────────────────────────────────────────────┘

📋 Estructura del proyecto

figma-dev-tools/
├── bin/
│   └── figma-dev.js           # CLI 入口（v1.3.0 新增 gui 命令）
├── mcp-standalone.mjs         # 零配置 MCP 入口（v1.1.0 新）
├── gui/                       # 🖥️ v1.3.0 新：GUI 可视化配置面板
│   ├── index.html             # GUI 主页面
│   ├── app.js                 # 前端交互逻辑
│   └── styles.css             # GUI 样式
├── src/
│   ├── index.ts               # MCP 服务器入口（v1.4.0 新增 svg-inline/hierarchy/cache）
│   ├── types.ts               # TypeScript 类型定义
│   ├── i18n/                  # 🌍 v1.3.2 新：国际化
│   │   ├── index.ts           # i18n 核心
│   │   ├── zh-CN.ts           # 中文语言包
│   │   └── en-US.ts           # 英文语言包
│   ├── 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 代码生成（v1.4.0：XSS防护+import分组排序+交互推断+语义标签）
│   │   ├── vue-generator.ts   # 🟢 v1.4.0：Vue SFC 代码生成
│   │   ├── flex-fixer.ts      # 🔧 Flex 布局修复
│   │   ├── a11y-enhancer.ts   # ♿ 无障碍增强
│   │   ├── design-system.ts   # 🎨 设计系统对齐
│   │   ├── responsive-inferrer.ts # 📱 响应式推断
│   │   ├── design-linter.ts   # ✅ 设计规范检查（含🗂️层级错位检测）
│   │   ├── hierarchy-fixer.ts # 🗂️ v1.4.0：智能层级修复（父子错位自动修复）
│   │   ├── svg-inline-renderer.ts # 🎨 v1.4.0：SVG内联渲染（svgo优化+LRU缓存）
│   │   ├── animation-detector.ts  # ✨ v1.4.0：动效检测（基础框架，预留扩展）
│   │   ├── component-mapper.ts    # 🧩 v1.4.0：组件库映射（shadcn/ui等检测提示）
│   │   ├── interaction-inferrer.ts # 🤖 v1.4.0：交互逻辑推断（按钮/表单/Tab/弹窗状态自动推断）
│   │   ├── watch-mode.ts     # 👁️ v1.4.0：Watch模式（轮询Figma变更自动重生成代码）
│   │   ├── cache.ts           # ⚡ v1.4.0：AES-256-GCM本地加密缓存（LRU+TTL）
│   │   ├── code-formatter.ts  # 💅 Prettier 代码格式化
│   │   ├── asset-downloader.ts# ⭐ 资源下载管线（SVGO 优化）
│   │   ├── svg-sprite-generator.ts # 🧩 SVG Sprite 生成
│   │   ├── token-store.ts     # 🔐 Token 安全存储
│   │   ├── tokens-extractor.ts# Tokens 提取
│   │   └── file-writer.ts     # 文件写入
│   ├── types/
│   │   └── nodes.ts           # 节点类型定义
│   └── utils/
│       ├── figma-url.ts       # URL 解析
│       ├── color.ts           # 颜色转换 + CIE76 色差
│       ├── cn.ts              # className 合并工具（tailwind-merge + clsx）
│       ├── security.ts        # 🔒 v1.4.0：XSS安全防护（6个安全函数）
│       └── errors.ts          # 错误处理
├── dist/                      # 编译输出
├── .env.example               # 环境变量模板
├── FIGMA-DESIGN-GUIDELINES.md # 📖 Figma 设计规范指南
├── DEVELOPMENT.md             # 开发文档
├── OPTIMIZATION-ANALYSIS.md   # 优化分析
├── package.json               # v1.4.0
├── tsconfig.json
├── README.md                  # 本文件
├── LICENSE                    # MIT 许可证
└── SKILL.md                   # AI Agent 使用指南

❓ FAQ / Solución de problemas

P: Soy principiante, es la primera vez que lo uso y no sé cómo configurarlo.

Solución (nueva función en v1.3.0 - la forma más sencilla): Ejecuta directamente el asistente de configuración visual GUI, sin necesidad de recordar ningún comando:

npx figma-dev-tools gui

El navegador abrirá automáticamente la interfaz de configuración; sigue los pasos guiados y haz clic:

1. Selecciona el idioma chino

2. Pega tu Token de Figma (validación automática)

3. Marca los editores que quieras configurar (detección automática de los instalados)

4. Haz clic en «Instalación con un clic», ¡y listo!

P: ¿Cómo inicio la configuración mediante la interfaz gráfica GUI?

Solución (nueva en v1.3.0): hay tres formas de iniciar la GUI:

# 方式一：直接启动 gui 命令（推荐）
figma-dev gui
# 或 npx figma-dev-tools gui

# 方式二：向导命令加 --gui 参数
figma-dev wizard --gui

# 方式三：初始化命令加 --gui 参数
figma-dev init --gui

• Puerto predeterminado: 54321

• Si el 54321 está ocupado, prueba automáticamente con 54322, 54323

• Al iniciar, abre automáticamente el navegador predeterminado

• Admite el cambio entre chino e inglés

• Validación en tiempo real de la validez del Token introducido

• Detecta automáticamente más de 8 editores e instala la configuración con un clic

P: ¿Puedo personalizar el puerto de la GUI?

Solución (nueva en v1.3.0):

# 指定端口启动
figma-dev gui --port 3000

# 或通过环境变量
FIGMA_GUI_PORT=3000 figma-dev gui

P: ¿El servidor MCP no se puede iniciar?

Comprobaciones:

1. Si has ejecutado npm install && npm run build (o el comando correspondiente de pnpm/yarn/bun)

2. Si existe el archivo dist/index.js

3. Versión de Node.js ≥ 20 (compruébalo con node -v)

4. Si la ruta en la configuración MCP es correcta (se recomienda usar rutas absolutas)

5. Para el modo sin configuración, puedes usar directamente npx -y figma-dev-tools --figma-api-key=xxx

6. Se recomienda configurar primero con la GUI: figma-dev gui, que realizará automáticamente toda la configuración

P: ¿La solicitud a la API devuelve 401 Unauthorized?

Solución:

1. Comprueba si FIGMA_ACCESS_TOKEN está configurado correctamente

2. Confirma que el Token no haya caducado (genera uno nuevo y pruébalo)

3. Confirma que el Token tenga marcado el permiso File content (Read only)

4. Confirma que tienes permiso para acceder a ese archivo de Figma (el archivo debe ser visible mediante enlace o debes ser colaborador)

5. En v1.3.0+ puedes usar la interfaz GUI para introducir el Token y validar su validez en tiempo real

6. En v1.3.2+ puedes usar figma-dev token set para almacenamiento seguro y evitar errores de configuración con texto en claro

7. Prueba a pasar el Token directamente mediante el parámetro --figma-api-key

P: ¿Los iconos generados se vuelven elipses o se deforman?

Solución (corrección automática en v1.3.2):

• Es un problema clásico del diseño Flex: el contenedor Flex estira los elementos secundarios con align-items: stretch de forma predeterminada

• El figma_generate_jsx de v1.3.2 ya detecta automáticamente y añade align-items: center + flex-shrink: 0 + ancho y alto fijos como corrección

• Si el problema persiste, puedes llamar a figma_lint_design para revisar la configuración de Auto Layout en el diseño

P: Uso Vue/Svelte/otros frameworks, no React?

Solución: Utiliza la nueva herramienta figma_get_structured_data de la v1.1.0, que genera una estructura JSON independiente del framework, con información completa sobre la jerarquía de nodos, estilos, texto y recursos. Puedes generar código para cualquier framework basándote en estos datos.

La CLI también lo admite:

npx figma-dev structured "https://www.figma.com/design/xxx/yyy?node-id=23-11032" --format json

💡 En el paso de "Preferencias de framework" de la configuración GUI puedes seleccionar tu framework habitual.

P: ¿Los colores/espaciados del componente generado no coinciden con el diseño?

Solución:

1. Asegúrate de que en Figma se usen Variables para definir colores/espaciados y se haya configurado codeSyntax.WEB.

2. La función de alineación del sistema de diseño de la v1.3.2 emparejará automáticamente variables de color/espaciado/tipografía/radio/sombra.

3. Se recomienda el formato de color oklch (compatible de forma nativa con Tailwind v4). Si hay problemas, cambia a hex.

4. Los colores que no coincidan con tokens existentes se extenderán mediante @theme inline. No escribas directamente bg-[#hex].

5. Revisa los comentarios TODO y el informe de sugerencias del sistema de diseño en el código generado.

6. Antes de generar, llama a figma_lint_design para verificar las normas del diseño.

P: ¿El código generado contiene muchos divs anidados redundantes?

Solución:

1. Usa figma_generate_jsx de la v1.4.0 en lugar de la antigua figma_generate_component.

2. Los diseñadores de UI deben evitar agrupaciones anidadas sin sentido (usa Frame para delimitar áreas).

3. Llama a figma_lint_design para revisar problemas de anidación.

4. Revisa si los nodos marcados como "solo layout" en el código generado se conservan incorrectamente.

5. Para secciones grandes, es recomendable dividirlas y generarlas por partes, evitando procesar árboles de nodos demasiado profundos de una sola vez.

P: ¿Los recursos de imagen no se descargan automáticamente?

Solución:

1. Debes llamar a la herramienta figma_download_assets pasando los pendingAssets[].nodeId que haya generado generate_jsx.

2. Asegúrate de que el parámetro sceneName esté configurado (los recursos se colocarán en el directorio public/<nombre_de_escena>/).

3. La v1.3.2 optimiza automáticamente los SVG con SVGO durante la descarga, eliminando atributos redundantes.

4. Comprueba si los nodos de imagen en Figma tienen un relleno IMAGE.

5. Problemas de red: la CDN de imágenes de Figma puede requerir acceso a Internet con restricciones.

P: ¿Cómo hacer que el código generado sea responsive?

Solución (nueva funcionalidad de la v1.3.2):

1. figma_generate_jsx de la v1.3.2 infiere automáticamente los breakpoints responsive y ofrece sugerencias con prefijos sm/md/lg en el informe de recomendaciones responsive.

2. Se recomienda diseñar las pantallas para móvil y escritorio por separado, o usar restricciones de Auto Layout.

3. Según las recomendaciones responsive, ajusta manualmente las clases añadiendo prefijos responsive (por ejemplo, md:flex-row).

P: ¿El código generado carece de atributos de accesibilidad?

Solución (mejora automática de la v1.3.2):

• La figma_generate_jsx de la v1.3.2 ya añade automáticamente:

  • Etiquetas HTML semánticas (<button> en lugar de <div onClick>, <h1>-<h6>, etc.)

  • Texto alternativo para imágenes

  • Etiquetas y roles ARIA

  • Indicaciones de tamaño mínimo de clic accesible

• El informe de mejoras de accesibilidad enumera todas las mejoras añadidas.

• Llama a figma_lint_design para comprobar problemas de accesibilidad en el diseño.

P: ¿Hay límites en la frecuencia de las solicitudes a la API?

• La API de Figma tiene límites de velocidad (aproximadamente 60 solicitudes/minuto).

• La herramienta ya incluye throttling automático al descargar recursos por lotes.

• Para archivos grandes, se recomienda procesarlos por partes para evitar muchas solicitudes en poco tiempo.

P: ¿Qué frameworks frontend se admiten?

• React + Tailwind CSS: soporte de primera clase (generación de código TSX + todas las mejoras de la v1.3.2).

• Vue 2/3 / Nuxt: mediante figma_get_structured_data se obtienen datos estructurados, y la IA puede generar SFC de Vue.

• Svelte / SvelteKit: igual que arriba.

• Angular: igual que arriba.

• SolidJS / Qwik: igual que arriba.

• HTML / CSS nativos: igual que arriba.

• Astro: igual que arriba.

• Next.js: se admite, pero ten cuidado de no usar next/image (usa <img> normal o publicCdnUrl()).

• Vite + React: recomendado, ya que coincide mejor con el código generado.

💡 En el asistente de configuración GUI puedes seleccionar tu framework preferido.

P: ¿La configuración del editor Zed no funciona?

Solución: Zed utiliza el campo mcp_servers (con guion bajo), no mcpServers (camelCase).

• Usa la interfaz gráfica figma-dev gui para configurar todo con un solo clic, manejando automáticamente la diferencia de campos de Zed.

• O usa npx figma-dev-tools install que también maneja esta diferencia automáticamente.

P: ¿Cómo cambiar el idioma de la interfaz?

Solución (nuevo en la v1.3.2):

# CLI 交互式切换
figma-dev lang switch

# 直接设置
figma-dev lang set zh-CN  # 中文
figma-dev lang set en-US  # English

# 或通过环境变量
FIGMA_DEFAULT_LANG=zh-CN

💡 En el segundo paso de la configuración GUI también puedes seleccionar el idioma directamente.

P: ¿Cómo almacenar de forma segura el Token de Figma?

Solución (recomendado a partir de la v1.3.0):

• Lo más sencillo: ejecuta figma-dev gui, introduce el Token en la interfaz GUI, se validará automáticamente y se guardará en un almacenamiento seguro.

• Mediante línea de comandos (nuevo en la v1.3.2):

# 交互式保存（推荐，会验证 Token）
figma-dev token set

# 直接保存
figma-dev token set -t figd_your_token_here

# 列出已保存 Token
figma-dev token list

# 查看 Token（掩码显示）
figma-dev token get

# 设置默认 Token
figma-dev token default work

El Token se guardará en el almacenamiento seguro del sistema:

• macOS: Keychain (Llavero)

• Windows: Credential Manager (Administrador de credenciales)

• Linux: libsecret (si no está disponible, se recurre a un archivo cifrado)

📖 Guía de normas de diseño

Consulta el archivo FIGMA-DESIGN-GUIDELINES.md, que es una guía completa de normas de diseño de Figma para diseñadores e IA, e incluye:

• Normas de uso de Auto Layout

• Convenciones de nomenclatura de capas

• Sistema de rejilla de 4px/8px

• Recomendaciones de reutilización de componentes

• Requisitos de diseño accesible

• Buenas prácticas de diseño a código

Antes de generar código, se recomienda ejecutar figma_lint_design para comprobar la calidad del diseño.

🎯 Comparación con otras soluciones

La siguiente comparación se basa en información pública recopilada entre 2025 y 2026, y solo refleja las diferencias de capacidades de figma-dev-tools v1.4.4 frente a cada solución, sin representar todas las capacidades de las otras. La etiqueta "requiere confirmación" indica que la documentación pública no especifica claramente el dato.

vs Soluciones SaaS comerciales

vs Herramientas de código abierto / oficiales

Ventajas diferenciales

• Plan de contingencia para muros de pago: BrowserFallbackService exclusivo de figma-dev-tools v1.4.4, que inicia automáticamente una captura de pantalla con Playwright como respaldo cuando la API REST de Figma falla por muros de pago. Ninguna de las soluciones competidoras ofrece un mecanismo similar.

• Ciclo cerrado de verificación de fidelidad: figma_verify_fidelity proporciona diff de píxeles, mapa de calor de diferencias y puntuación cuantitativa (0-100%). Otras herramientas se quedan en la promoción "pixel-perfect" sin verificación automatizada.

• Datos estructurados independientes del framework: figma_get_structured_data genera JSON estándar, compatible con cualquier framework. Las SaaS comerciales suelen limitarse a frameworks específicos.

• Código abierto + gratuito + funciones completas: Licencia MIT, sin necesidad de asientos de pago para usar las 19 herramientas MCP completas.

📜 Licencia

MIT © contribuidores de figma-dev-tools