🎨 Figma Dev Tools v1.4.4

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 Design Tokens, 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 principales como div soup, explosión de contexto, valores hex fijos, manejo de rutas de recursos, deformación de Flex Layout, falta de accesibilidad, adaptación responsiva, cobertura de paywall, etc.

✨ v1.4.4 Cobertura de paywall + Restauración de alta fidelidad + Optimización de rendimiento

Cobertura principal y restauración

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

Comparación 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 秒）
});

📜 Resumen de historial de versiones

✨ Aspectos 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.

Método 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

Después de iniciar, se abrirá automáticamente el navegador (puerto predeterminado 54321, si está ocupado intenta automáticamente 54322/54323), sigue los pasos de la guía:

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 - Ingresa el Token de Figma, verifica la validez en tiempo real

4. Detección de editor - Detecta automáticamente 8+ editores instalados, instala la configuración MCP con un clic después de marcar

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

6. Página de finalización - Configuración exitosa, proporciona enlace de tutorial de uso

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

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

Método uno: Ejecución directa con npx sin configuración (más rápido)

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

# 直接通过 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"]
    }
  }
}

Método 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, 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 más simple: Ejecuta figma-dev gui para usar la interfaz gráfica y detectar e instalar la configuración del editor con un clic.

Método 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

Método 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 Figma Access Token

1. Inicia sesión en Figma

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

3. Encuentra Personal access tokens → Generate new token

4. Ingresa un nombre, marca el permiso File content (Read only)

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

💡 Cuando uses la configuración GUI, pega directamente el Token en la interfaz del navegador para verificar y guardar automáticamente.

2. Configurar Token

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

figma-dev gui

En la interfaz del navegador, ingresa el Token, verifica la 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: A través de 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: A través de 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 de MCP

Agrega 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 - Preinspección de normas de diseño (opcional, muestra 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 del 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 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

Un total de 19 herramientas MCP, ordenadas por flujo de uso:

Parámetros detallados de las herramientas

figma_generate_jsx (v1.4.0 versión mejorada, la más utilizada)

{
  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 de v1.4.0:

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

• 🔧 Informe de corrección de Flex: enumera los 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, adición de atributos ARIA

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

• 📱 Sugerencias responsivas: inferencia de puntos de interrupción, sugerencias de prefijos sm/md/lg

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

• 🖼️ Lista de recursos que necesitan descargarse (nodeId, nombre, tipo)

• 🧩 Sugerencias de componentes reutilizables

• Estadísticas resumidas de nodos

• ✅ Puntuación de sugerencias de especificaciones de diseño (se recomienda reparar primero si es inferior a 80 puntos)

figma_lint_design (Nuevo en v1.3.2, preinspección de calidad de restauración de código)

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

Elementos de inspección:

• Normas de uso de Auto Layout

• Normalización de nombres de capas

• Si el espaciado/tamaño/radio de borde usa la cuadrícula de 4px/8px

• Reutilización de componentes

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

• Profundidad de anidamiento de niveles

• Consistencia de estilos de texto

• Normas de uso de color

Salida:

• Puntuación de calidad de 0 a 100

• Estadísticas clasificadas de errores/advertencias/consejos

• Lista de problemas detallada por categoría

• Sugerencias de reparación específicas

• Ver: FIGMA-DESIGN-GUIDELINES.md

figma_create_icon_sprite (Nuevo en v1.3.2, generación de SVG Sprite)

{
  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 de nodos estructurado completo, 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>

| Comando | Función | Opciones comunes | Versión | | | | figma-dev gui | 🖥️ Inicia el panel de configuración visual GUI | --port <n> Especifica el puerto (por defecto 54321) | v1.3.0 | | | | figma-dev install | Instala la configuración MCP en los editores con un solo clic | - | v1 | | | | figma-dev uninstall | Desinstala la configuración MCP instalada | - | v1 | | | | figma-dev validate <token> | Valida el Token | - | v1 | | | | figma-dev wizard | Asistente de configuración interactivo | --gui Inicia el modo GUI | v1.3.0 | | | | figma-dev init | Inicializa la configuración (asistente interactivo) | --gui Inicia el modo GUI | v1.3.0 | | | | figma-dev lang | 🌍 Configuración de idioma (set/list/switch) | set <lang> / switch | v1.3.2 | | | | figma-dev token | 🔐 Gestión segura de Tokens (set/get/list/delete/default) | set -t <token> | v1.3.2 | | | | figma-dev info <url> | Muestra información del archivo | - | v1 | | | | figma-dev lint <url> | ✅ Pre-revisión de normas de diseño | --node <id> --depth <n> --format md/json --output <file> | v1.3.2 | | | | figma-dev metadata <url> | Obtiene un resumen de metadatos | --node <id> --depth <n> | v1.1.0 | | | | figma-dev structured <url> | Obtiene datos estructurados independientes del framework | --node <id> --depth <n> --format pretty/json --output <file> | v1.1.0 | | | | figma-dev jsx <url> | Genera componentes JSX/Vue mejorados (Flex/a11y/Sistema de diseño/Responsive, v1.4.0 añade Vue 3/UnoCSS) | --name <ComponentName> --scene <name> --depth <n> --framework react | vue --style tailwind | unocss --skip-lint --inline-svg | v1.4.0 | | figma-dev component <url> | Genera componentes básicos | --name <name> --node <id> --js --style tailwind --no-children --output <dir> | v1 | | | | figma-dev assets <url> | Descarga recursos (optimización SVGO) | --node <id> --nodes <id1,id2> --scene <name> --scale <n> --svg-format svg | png --project-root <dir> | v1.1.0 | | | figma-dev sync <url> | Sincroniza Tokens | --node <id> --format oklch --spacing-unit px | rem --prefix <name> --output-format all --file-name <name> | v1 | | | | figma-dev screenshot <url> | Toma capturas de pantalla | --node <id> --format png --scale 2 --download <dir> | v1 | | | | figma-dev mcp | Inicia el servidor MCP (stdio) | - | v1 | | | | figma-dev tutorial | Ver documentación del tutorial (alias help, abre el navegador automáticamente) | --no-browser | v1.3.0 | | | | figma-dev cache | 📦 Gestión de caché (status/clear) | status / clear -f | v1.4.0 | | | | figma-dev privacy | 🔒 Aviso de privacidad (ver compromiso de seguridad de datos + comprobación .gitignore) | - | v1.4.0 | | |

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.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 configuración: ejecuta figma-dev gui Inicia la interfaz gráfica, detecta automáticamente todos los editores instalados en tu ordenador, marca los que quieras configurar e instala todo con un solo clic, sin necesidad de buscar rutas de archivos de configuración manualmente.

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 (nota: 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"
      }
    }
  }
}

Modo npx sin configuración (sin necesidad de 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 detectará automáticamente el editor y completará la ruta correcta; con Zed usará automáticamente el campo mcp_servers.

⚙️ Descripción de la configuración

Variables de entorno (.env)

Copia .env.example como .env y rellena:

# 必需：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 a través de la interfaz GUI (nuevo en v1.3.0, se almacena 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 pasado en la llamada a 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.4                            │
│     🖥️ 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, no sé cómo configurarlo la primera vez.

Solución (nuevo 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, solo sigue los pasos guiados:

1. Selecciona el idioma chino

2. Pega tu Token de Figma (se valida automáticamente)

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

4. Haz clic en Instalar con un solo clic, ¡listo!

P: ¿Cómo iniciar la configuración de la interfaz gráfica GUI?

Solución (nuevo 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 por defecto: 54321

• Si el puerto 54321 está ocupado, intenta automáticamente 54322, 54323

• Después de iniciar, abre automáticamente el navegador predeterminado

• Soporta cambio entre chino e inglés

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

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

P: ¿Puedo personalizar el puerto de la GUI?

Solución (nuevo en v1.3.0):

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

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

P: El servidor MCP no se inicia.

Comprobaciones:

1. ¿Ejecutaste npm install && npm run build (o el comando correspondiente para pnpm/yarn/bun)?

2. ¿Existe el archivo dist/index.js?

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

4. ¿Es correcta la ruta en la configuración MCP? (se recomienda usar rutas absolutas)

5. El modo sin configuración puede usar directamente npx -y figma-dev-tools --figma-api-key=xxx

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

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 ha expirado (genera uno nuevo para probar)

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

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

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

6. En v1.3.2+ puedes usar figma-dev token set para almacenarlo de forma segura, evitando errores de configuración en texto plano

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

P: El icono generado se vuelve elipse / deformado.

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

• Es un problema clásico de Flex: el contenedor Flex por defecto align-items: stretch estira los elementos hijos

• El figma_generate_jsx de v1.3.2 ya detecta automáticamente y añade align-items: center + flex-shrink: 0 + ancho y alto fijo para repararlo

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

P: Uso Vue/Svelte/otro framework, no React.

Solución: Usa la herramienta figma_get_structured_data añadida en v1.1.0, que produce una estructura JSON independiente del framework, con toda la jerarquía de nodos, estilos, texto e información de recursos. Puedes generar código para cualquier framework basándote en estos datos.

CLI también es compatible:

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

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

P: Los colores/espaciados de los componentes generados no coinciden con el diseño.

Solución:

1. Asegúrate de que en Figma se usaron Variables para definir colores/espaciados y se configuró codeSyntax.WEB

2. La función de alineación con el sistema de diseño de v1.3.2 empareja automáticamente variables de color/espaciado/fuente/borde/sombra

3. Se recomienda el formato de color oklch (soporte nativo de 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 en el código generado y el informe de recomendaciones del sistema de diseño

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

P: El código generado tiene muchas etiquetas div anidadas redundantes.

Solución:

1. Usa figma_generate_jsx de v1.4.0 en lugar de la versión anterior figma_generate_component

2. Los diseñadores de UI deben evitar anidaciones múltiples de Group sin sentido (usa Frame para dividir áreas)

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

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

5. Se recomienda dividir bloques grandes y generarlos por partes, evitando procesar árboles de nodos demasiado profundos de una sola vez

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

Solución:

1. Debes llamar a la herramienta figma_download_assets, pasando el pendingAssets[].nodeId de la salida de 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. En v1.3.2, al descargar se usa automáticamente SVGO para optimizar SVG, eliminando atributos redundantes

4. Verifica 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 v1.3.2):

1. figma_generate_jsx de v1.3.2 infiere automáticamente los puntos de interrupción responsive y proporciona sugerencias de prefijos sm/md/lg en el informe de recomendaciones responsive

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

3. Según las recomendaciones responsive, ajusta manualmente los nombres de clase 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 v1.3.2):

• figma_generate_jsx de 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 mejora de accesibilidad enumera todas las mejoras añadidas

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

P: ¿Límite de frecuencia de solicitudes a la API?

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

• Al descargar recursos en lote, la herramienta ya aplica throttling automáticamente

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

P: ¿Qué frameworks frontend se soportan?

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

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

• Svelte / SvelteKit: igual que arriba

• Angular: igual que arriba

• SolidJS / Qwik: igual que arriba

• HTML / CSS nativo: igual que arriba

• Astro: igual que arriba

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

• Vite + React: recomendado, es el que mejor coincide 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 usa el campo mcp_servers (con guion bajo), no mcpServers (camelCase).

• Usa la interfaz gráfica figma-dev gui para configurar con un clic, que maneja 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 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 interfaz de configuración GUI también puedes seleccionar el idioma directamente.

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

Solución (recomendado desde v1.3.0+):

• Lo más sencillo: ejecuta figma-dev gui, ingresa el Token en la interfaz GUI, se valida automáticamente y se guarda en almacenamiento seguro

• Mediante línea de comandos (nuevo en 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 guarda en el almacenamiento seguro del sistema:

• macOS: Keychain

• Windows: Credential Manager

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

📖 Guía de diseño

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

• Normas de uso de Auto Layout

• Convenciones de nombres de capas

• Sistema de cuadrícula de 4px/8px

• Recomendaciones de reutilización de componentes

• Requisitos de diseño accesible

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

Antes de generar código, se recomienda ejecutar figma_lint_design para verificar 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 entre figma-dev-tools v1.4.4 y cada solución, no representa todas las capacidades de la otra parte. Las marcas "requiere confirmación" indican que la información pública no es clara.

vs Soluciones SaaS comerciales

vs Herramientas de código abierto / oficiales

Ventajas diferenciadoras

• Plan de respaldo para paywall: BrowserFallbackService exclusivo de figma-dev-tools v1.4.4, que inicia automáticamente Playwright para capturar pantallas como respaldo cuando la API REST de Figma falla debido al paywall. Ningún competidor ofrece un mecanismo similar.

• Ciclo cerrado de verificación de fidelidad: figma_verify_fidelity proporciona diff de píxeles + mapa de calor de diferencias + 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. Los SaaS comerciales suelen estar bloqueados a frameworks específicos.

• Código abierto + gratuito + funcionalidad completa: Licencia MIT, no se requiere asiento de pago para usar las 19 herramientas MCP.

📜 Licencia

MIT © figma-dev-tools contributors