🎨 Figma Dev Tools v1.4.4

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

English | Русский

Полный инструментарий, соединяющий дизайн Figma и фронтенд-разработку, поддерживает 🖥️ GUI-мастер визуальной настройки, интеллектуальное извлечение дизайн-токенов, генерацию высокоточных компонентов (React/Vue/Svelte/HTML и др.), автоматическую загрузку ресурсов, интеграцию MCP в редакторах. Оптимизирован для AI-агентов, решает ключевые проблемы: 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 秒）
});

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

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

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

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

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

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

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

# 或全局安装后
figma-dev gui

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

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

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

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

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 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 (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.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.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 服务        │ │
│                                              └──────────────────────────────┘ │
│                                                                               │
└───────────────────────────────────────────────────────────────────────────────┘

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

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 / Устранение неполадок

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

Решение (новая функция v1.3.0 - самый простой способ): Запустите мастер визуальной конфигурации GUI, не нужно запоминать никаких команд:

npx figma-dev-tools gui

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

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

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

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

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

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

Решение (новое в 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 версии 1.4.0 вместо устаревшей figma_generate_component

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

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

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

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

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

Решение:

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

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

3. В версии 1.3.2 при загрузке автоматически используется SVGO для оптимизации SVG, удаляются избыточные атрибуты

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

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

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

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

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

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

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

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

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

• figma_generate_jsx версии 1.3.2 уже автоматически добавляет:

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

  • Текст alt для изображений

  • 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, введите токен в интерфейсе 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

Токен будет сохранён в системном защищённом хранилище:

• 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, который автоматически запускает Playwright для создания скриншота, когда Figma REST API недоступен из-за paywall. Ни один из конкурентов не предлагает подобного механизма.

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

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

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

📜 Лицензия

MIT © figma-dev-tools contributors