🎨 Figma Dev Tools v1.4.10

Figma → любой фронтенд-фреймворк MCP-сервер для однокнопочного преобразования дизайна в код

English | 中文

Полный инструментарий, соединяющий дизайн Figma и фронтенд-разработку, поддерживает 🖥️ GUI-мастер визуальной настройки, интеллектуальное извлечение токенов дизайна, генерацию высококачественных компонентов (React/Vue/Svelte/HTML и др.), автоматическую загрузку ресурсов, интеграцию MCP в редакторах. Оптимизирован для AI Agent, решает ключевые проблемы: div soup, взрыв контекста, жёстко прописанные hex, обработка путей ресурсов, деформация Flex-раскладки, отсутствие доступности, адаптивность, подстраховка за paywall и другие.

✨ v1.4.4 Подстраховка за paywall + высокоточное восстановление + оптимизация производительности

Ключевая подстраховка и восстановление

Оптимизация производительности (добавлено в v1.4.4)

Сравнение производительности (до и после оптимизации v1.4.4)

Конфигурация оптимизации производительности (опционально, обратная совместимость)

// 通过 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

📜 Сводка истории версий

✨ Ключевые возможности

🚀 Быстрый старт

📚 Хотите краткое руководство, синхронизированное с версией? См. QUICKSTART.md (китайский) / QUICKSTART.en-US.md (английский). Ниже приведено подробное описание.

Способ 0: GUI-мастер визуальной настройки (рекомендуется для новичков ⭐)

Не нужно запоминать никаких команд, вся настройка через графический интерфейс браузера:

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

# 或全局安装后
figma-dev gui

После запуска автоматически откроется браузер (порт по умолчанию 54321, при занятости автоматически пробует 54322/54323), следуйте шагам:

1. Страница приветствия — узнайте о возможностях figma-dev-tools

2. Выбор языка — переключение между китайским и английским

3. Настройка токена — введите токен Figma, проверка действительности в реальном времени

4. Обнаружение редактора — автоматическое обнаружение 8+ установленных редакторов, установка MCP-конфигурации в один клик после выбора

5. Предпочтения фреймворка — выберите часто используемый фреймворк (React/Vue/HTML)

6. Страница завершения — настройка успешна, предоставлены ссылки на учебные пособия

💡 Также можно запустить GUI-режим через команду мастера:

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

Способ 1: Запуск через npx без конфигурации (самый быстрый)

Без установки, одной командой запустить MCP-сервер:

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

В конфигурации MCP редактора используйте:

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

Способ 2: Установка в один клик (рекомендуется для долгосрочного использования)

# 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

Скрипт установки автоматически:

• Обнаружит установленные AI-редакторы (Trae/VS Code/Cursor/Windsurf/Claude Desktop/Zed/Cline/Roo Code и др., 8+)

• Автоматически обнаружит менеджер пакетов (npm/pnpm/yarn/bun)

• Загрузит/скомпилирует инструмент

• Настроит MCP settings для соответствующего редактора (Zed использует поле mcp_servers)

• Сгенерирует шаблон .env.example

💡 Ещё проще: запустите figma-dev gui для обнаружения и установки конфигурации редактора через графический интерфейс в один клик.

Способ 3: Установка как зависимость проекта

# 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

Способ 4: Установка из локального исходного кода

# 克隆或复制 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. Получение Figma Access Token

1. Войдите в Figma

2. Нажмите на аватар в правом верхнем углу → Settings → Account

3. Найдите Personal access tokens → Generate new token

4. Введите имя, отметьте разрешение File content (Read only)

5. Скопируйте сгенерированный токен (⚠️ отображается только один раз)

💡 При использовании GUI-конфигурации просто вставьте токен в интерфейсе браузера для автоматической проверки и сохранения.

2. Настройка токена

Способ A: GUI-мастер визуальной настройки (рекомендуется v1.3.0+)

figma-dev gui

Введите токен в интерфейсе браузера, после проверки действительности в реальном времени он будет автоматически безопасно сохранён.

Способ B: Безопасное хранение (рекомендуется v1.3.2+)

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

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

Способ C: Через параметры командной строки

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

Способ D: Через файл .env

Создайте файл .env в каталоге figma-dev-tools/:

FIGMA_ACCESS_TOKEN=your-figma-token-here

Способ E: env в конфигурации MCP

Добавьте в конфигурацию MCP редактора:

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

3. Первый пример Figma → код

React + Tailwind (рекомендуется, улучшенная версия v1.4.0):

В AI-редакторе (например, Trae) просто напишите в диалоге:

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

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

AI автоматически выполнит следующий улучшенный процесс (v1.3.2):

1. figma_lint_design — предварительная проверка стандартов дизайна (опционально, указывает на проблемы)

2. figma_parse_url — разбор ссылки

3. figma_get_metadata — получение обзора структуры страницы

4. figma_get_screenshot — получение визуального эталона

5. figma_generate_jsx — генерация TSX-кода в один клик (включая исправление Flex, улучшение a11y, выравнивание по системе дизайна, адаптивное определение)

6. figma_download_assets — загрузка ресурсов изображений (автоматическая оптимизация SVGO)

Другие фреймворки (Vue/Svelte/HTML и др.):

Используйте инструмент figma_get_structured_data для получения JSON-структуры, независимой от фреймворка:

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

Быстрый опыт 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

🔧 Справочник по MCP-инструментам

Всего 19 MCP-инструментов, расположены в порядке использования:

Подробные параметры инструментов

figma_generate_jsx (v1.4.0 улучшенная версия, наиболее часто используемая)

{
  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;        // 可选，优先用环境变量
}

Улучшенный вывод v1.4.0:

• Полный код React + TypeScript + Tailwind TSX (форматирован Prettier)

• 🔧 Отчёт об исправлении Flex: список автоматически исправленных проблем верстки (деформация иконок, обрезка текста и т.д.)

• ♿ Отчёт об улучшении доступности: семантические теги, alt-текст, добавление ARIA-атрибутов

• 🎨 Предложения по дизайн-системе: рекомендации по сопоставлению переменных цвета/отступов/скруглений/теней

• 📱 Рекомендации по адаптивности: определение контрольных точек, предложения префиксов sm/md/lg

• ⚠️ Список токенов, требующих расширения @theme

• 🖼️ Список ресурсов, которые необходимо загрузить (nodeId, имя, тип)

• 🧩 Подсказки о переиспользуемых компонентах

• Статистика по сокращению узлов

• ✅ Оценка соответствия дизайн-специфікациям (рекомендуется исправить, еслі оченка ніже 80)

figma_lint_design (v1.3.2 новое, предварительная проверка качесва восстановления кода)

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

Проверяемые пункты:

• Соблюдение правил Auto Layout

• Нормы именования слоёв

• Использование сетки 4px/8px для отступов/размеров/скруглений

• Повторное использование компонентов

• Минимальный размер клика для доступности (48×48px)

• Глубина вложенности

• Согласованность стилей текста

• Нормы использования цвета

Вывод:

• Оценка качества 0–100

• Распределение по категориям: ошибки/предупреждения/подсказки

• Детальный список проблем по категориям

• Конкретные рекомендации по исправлению

• См. также: FIGMA-DESIGN-GUIDELINES.md

figma_create_icon_sprite (v1.3.2 новое, генерация 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 (v1.1.0 новое, поддержка нескольких фреймворков)

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

Содержимое вывода:

• Полная JSON-структура, не зависящая от фреймворка, каждый узел содержит:

  • id / name — идентификатор узла

  • role — семантическая роль (button/card/image/text/icon/section и т.д.)

  • type — тип узла Figma (FRAME/TEXT/RECTANGLE/GROUP/INSTANCE и т.д.)

  • size — { width, height }

  • layout — атрибуты Flex-верстки (display/flexDirection/justifyContent/alignItems/gap/padding и т.д.)

  • styles — свойства стиля (color/backgroundColor/borderRadius/shadow/fontSize/fontWeight и т.д.)

  • text — текстовое содержимое (только для узлов TEXT)

  • asset — информация о ресурсе (для узлов-изображений: тип, формат, URL загрузки)

  • children — массив дочерних узлов

• Краткое резюме: семантическая роль, тип узла, размер, общее количество узлов, количество цветов, количество ресурсов, количество текстовых узлов

• structuredContent — полное дерево структурированных узлов, готовое для прохода и генерации кода на любом фреймворке

Подходящие фреймворки:

• ✅ React / Next.js / Remix (лучше всего с generate_jsx)

• ✅ Vue 2/3 / Nuxt

• ✅ Svelte / SvelteKit

• ✅ Нативный HTML / CSS

• ✅ Angular

• ✅ SolidJS

• ✅ Qwik

• ✅ Astro

• ✅ Любой фронтенд-фреймворк

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 名称前缀
}

💻 Справка по 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>

Примеры 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

🖥️ Поддерживаемые редакторы (8+)

💡 Самый простой способ настройки: запустите figma-dev gui Запустите графический интерфейс, автоматически обнаружит все установленные редакторы на вашем компьютере, выберите нужные редакторы и выполните одношаговую установку, без необходимости вручную искать пути к файлам конфигурации.

Шаблон конфигурации MCP

Стандартный формат (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"
      }
    }
  }
}

Формат Zed (обратите внимание, что имя поля — 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"
      }
    }
  }
}

Способ npx с нулевой конфигурацией (без локальной установки):

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

💡 Используйте npx figma-dev-tools install или figma-dev gui Автоматически обнаружит редакторы и заполнит правильные пути, Zed автоматически использует поле mcp_servers.

⚙️ Описание конфигурации

Переменные окружения (.env)

Скопируйте .env.example в .env и заполните:

# 必需：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

Приоритет конфигурации MCP

Приоритет чтения токена:

1. Параметр командной строки --figma-api-key / -t / --token

2. Токен, настроенный и сохранённый через GUI (новое в v1.3.0, автоматически сохраняется в безопасное хранилище)

3. Токен по умолчанию в безопасном хранилище (новое в v1.3.2, сохраняется командой figma-dev token set)

4. Параметр accessToken, переданный при вызове инструмента MCP

5. env.FIGMA_ACCESS_TOKEN в конфигурации MCP

6. FIGMA_ACCESS_TOKEN в файле .env

7. Системная переменная окружения FIGMA_ACCESS_TOKEN

🏗️ Архитектурная диаграмма

┌──────────────────────────────────────────────────────────────────────────────────┐
│                         用户界面层                                                 │
│  ┌──────────────┐  ┌──────────────────────────────────────────────────────────┐  │
│  │  💻 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 服务        │ │
│                                              └──────────────────────────────┘ │
│                                                                               │
└───────────────────────────────────────────────────────────────────────────────┘

📋 Структура проекта

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 使用指南

❓ Часто задаваемые вопросы / Устранение неполадок

В: Я новичок, впервые использую, не знаю, как настроить?

Решение (новое в v1.3.0 — самый простой способ): Просто запустите мастер настройки GUI, не нужно запоминать никаких команд:

npx figma-dev-tools gui

Браузер автоматически откроет интерфейс конфигурации, следуйте шагам:

1. Выберите русский язык

2. Вставьте ваш Figma Token (автоматическая проверка)

3. Отметьте редакторы для настройки (автоматическое обнаружение установленных)

4. Нажмите «Одношаговая установка», готово!

В: Как запустить графический интерфейс конфигурации?

Решение (новое в v1.3.0): Есть три способа запустить GUI:

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

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

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

• Порт по умолчанию: 54321

• Если порт 54321 занят, автоматически попробует 54322, 54323

• После запуска автоматически откроется браузер по умолчанию

• Поддержка переключения между русским и английским

• Проверка действительности токена в реальном времени

• Автоматическое обнаружение 8+ редакторов и одношаговая установка конфигурации

В: Можно ли настроить порт в GUI?

Решение (новое в v1.3.0):

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

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

В: MCP-сервер не запускается?

Проверьте:

1. Выполнили ли вы npm install && npm run build (или соответствующую команду pnpm/yarn/bun)

2. Существует ли файл dist/index.js

3. Версия Node.js ≥ 20 (проверьте node -v)

4. Правильный ли путь в конфигурации MCP (рекомендуется абсолютный путь)

5. Для нулевой конфигурации можно использовать npx -y figma-dev-tools --figma-api-key=xxx

6. Рекомендуется сначала настроить через GUI: figma-dev gui, он автоматически выполнит всю настройку

В: API-запрос возвращает 401 Unauthorized?

Решение:

1. Проверьте, правильно ли настроен FIGMA_ACCESS_TOKEN

2. Убедитесь, что токен не истёк (попробуйте сгенерировать новый)

3. Убедитесь, что у токена есть разрешение File content (Read only)

4. Убедитесь, что у вас есть доступ к этому файлу Figma (файл должен быть виден по ссылке или вы должны быть соавтором)

5. В v1.3.0+ можно использовать GUI для ввода токена с проверкой в реальном времени

6. В v1.3.2+ можно использовать figma-dev token set для безопасного хранения, избегая ошибок в открытой конфигурации

7. Попробуйте передать токен напрямую через параметр --figma-api-key

В: Сгенерированные иконки становятся овальными/деформируются?

Решение (автоматическое исправление в v1.3.2):

• Это классическая проблема Flex-макета: контейнер Flex по умолчанию align-items: stretch растягивает дочерние элементы

• В v1.3.2 figma_generate_jsx автоматически обнаруживает и добавляет align-items: center + flex-shrink: 0 + фиксированную ширину/высоту для исправления

• Если проблема остаётся, вызовите figma_lint_design для проверки настроек Auto Layout в дизайн-макете

В: Я использую Vue/Svelte/другой фреймворк, а не React?

Решение: Используйте новый инструмент figma_get_structured_data, добавленный в v1.1.0. Он выводит фреймворк-независимую JSON-структуру, содержащую полную иерархию узлов, стили, текст и информацию о ресурсах. На основе этих данных вы можете генерировать код для любого фреймворка.

CLI также поддерживает:

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

💡 На шаге «Предпочтения фреймворка» в настройках GUI вы можете выбрать часто используемый вами фреймворк.

В: Сгенерированные цвета/отступы компонентов не соответствуют дизайн-макету?

Решение:

1. Убедитесь, что в Figma для определения цветов/отступов используются Variables и установлен codeSyntax.WEB.

2. Функция выравнивания дизайн-системы v1.3.2 автоматически сопоставляет переменные цветов, отступов, шрифтов, скруглений и теней.

3. Рекомендуемый формат цвета — oklch (нативная поддержка Tailwind v4). При возникновении проблем переключитесь на hex.

4. Цвета, не попавшие в существующие токены, расширяются через @theme inline. Не пишите напрямую bg-[#hex].

5. Проверьте TODO-комментарии в сгенерированном коде и отчет о рекомендациях дизайн-системы.

6. Перед генерацией вызовите figma_lint_design для проверки соответствия дизайн-макета стандартам.

В: В сгенерированном коде много избыточных вложенных div?

Решение:

1. Используйте figma_generate_jsx из v1.4.0 вместо старого figma_generate_component.

2. UI-дизайнерам следует избегать многоуровневых бессмысленных вложений Group (используйте Frame для разделения областей).

3. Вызовите figma_lint_design для проверки проблем с уровнем вложенности.

4. Проверьте, не были ли ошибочно сохранены узлы, помеченные в сгенерированном коде как layout-only.

5. Для больших блоков рекомендуется разбивать их на части и генерировать код для каждой части отдельно, чтобы избежать обработки слишком глубокого дерева узлов за один раз.

В: Ресурсы изображений не загружаются автоматически?

Решение:

1. Обязательно вызовите инструмент figma_download_assets, передав ему pendingAssets[].nodeId из вывода generate_jsx.

2. Убедитесь, что параметр sceneName установлен (ресурсы будут помещены в каталог public/<имя_сцены>/).

3. При загрузке в v1.3.2 автоматически используется SVGO для оптимизации SVG и удаления избыточных атрибутов.

4. Проверьте, есть ли у узла изображения в Figma заливка IMAGE.

5. Проблемы с сетью: CDN изображений Figma может требовать доступа через VPN.

В: Как сделать сгенерированный код адаптивным?

Решение (новая функция v1.3.2):

1. figma_generate_jsx в v1.3.2 автоматически определяет точки останова для адаптивности и в отчете с рекомендациями по адаптивности предлагает префиксы sm/md/lg.

2. Рекомендуется создавать отдельные дизайн-макеты для мобильной и десктопной версий или использовать ограничения Auto Layout.

3. Следуя рекомендациям по адаптивности, вручную добавьте адаптивные префиксы к классам (например, md:flex-row).

В: В сгенерированном коде отсутствуют атрибуты доступности?

Решение (автоматическое улучшение v1.3.2):

• figma_generate_jsx в v1.3.2 автоматически добавляет:

  • Семантические HTML-теги (<button> вместо <div onClick>, <h1>-<h6> и т.д.)

  • Альтернативный текст для изображений

  • ARIA-метки и роли

  • Подсказки о минимальном размере кликабельных элементов для доступности

• Отчет об улучшении доступности перечисляет все добавленные улучшения.

• Вызовите figma_lint_design для проверки проблем доступности в дизайн-макете.

В: Ограничение частоты запросов к API?

• Figma API имеет ограничение скорости (около 60 запросов/мин).

• При пакетной загрузке ресурсов инструмент автоматически применяет регулировку.

• Для больших файлов рекомендуется разбивать обработку, чтобы избежать большого количества запросов за короткое время.

В: Какие фронтенд-фреймворки поддерживаются?

• React + Tailwind CSS: Первостепенная поддержка (генерация TSX-кода + полное улучшение в v1.3.2).

• Vue 2/3 / Nuxt: Через figma_get_structured_data получайте структурированные данные, AI может генерировать Vue SFC.

• Svelte / SvelteKit: Аналогично.

• Angular: Аналогично.

• SolidJS / Qwik: Аналогично.

• Нативный HTML / CSS: Аналогично.

• Astro: Аналогично.

• Next.js: Поддерживается, но не используйте next/image (используйте обычный <img> или publicCdnUrl()).

• Vite + React: Рекомендуется, наилучшее соответствие сгенерированному коду.

💡 В мастере настройки GUI вы можете выбрать предпочитаемый фреймворк.

В: Не работают настройки редактора Zed?

Решение: Zed использует поле mcp_servers (с подчеркиванием), а не mcpServers (camelCase).

• Используйте графический интерфейс figma-dev gui для настройки в один клик, он автоматически обрабатывает разницу в полях для Zed.

• Или используйте npx figma-dev-tools install, он также автоматически обработает это различие.

В: Как переключить язык интерфейса?

Решение (новое в 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

💡 На втором шаге интерфейса настройки GUI вы также можете напрямую выбрать язык.

В: Как безопасно хранить Figma Token?

Решение (рекомендуется v1.3.0+):

• Самый простой способ: Запустите figma-dev gui, введите Token в интерфейсе GUI, он будет автоматически проверен и сохранен в безопасном хранилище.

• Способ через командную строку (новое в 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

Token будет сохранен в системном безопасном хранилище:

• macOS: Keychain

• Windows: Credential Manager

• Linux: libsecret (если недоступно, то в зашифрованном файле)

📖 Дизайн-спецификация

Смотрите FIGMA-DESIGN-GUIDELINES.md — это полное руководство по дизайн-спецификациям Figma для дизайнеров и AI, включающее:

• Правила использования Auto Layout

• Соглашения об именовании слоев

• Сетка 4px/8px

• Рекомендации по повторному использованию компонентов

• Требования к дизайну для доступности

• Лучшие практики перехода от дизайна к коду

Перед генерацией кода рекомендуется запустить figma_lint_design для проверки качества дизайн-макета.

🎯 Сравнение с другими решениями

Следующее сравнение основано на публичной информации, собранной за 2025-2026 годы, и отражает только различия в возможностях figma-dev-tools v1.4.4 и других решений, не являясь полным описанием их возможностей. Пометка «требуется подтверждение» означает, что в открытых источниках нет четких указаний.

vs Коммерческие SaaS-решения

vs Инструменты с открытым исходным кодом / официальные инструменты

Ключевые отличия

• Резервный план при paywall: Уникальный BrowserFallbackService в figma-dev-tools v1.4.4, который при неудаче Figma REST API из-за paywall автоматически запускает Playwright для создания резервного скриншота. Ни один из конкурентов не предлагает подобного механизма.

• Замкнутый цикл верификации точности: figma_verify_fidelity предоставляет пиксельный diff + тепловую карту различий + количественную оценку (0-100%). Другие инструменты в основном ограничиваются заявлениями о «pixel-perfect» без автоматической верификации.

• Фреймворк-независимые структурированные данные: figma_get_structured_data выводит стандартный JSON, поддерживающий любые фреймворки. Коммерческие SaaS-решения часто привязывают к определенному фреймворку.

• Открытый исходный код + бесплатно + полный функционал: Лицензия MIT, не требует платного места для использования всех 19 MCP-инструментов.

📜 Лицензия

MIT © figma-dev-tools contributors