🎨 Figma Dev Tools v1.4.10

Figma → Beliebiges Frontend-Framework Design-to-Code-Konvertierung MCP-Server

English | 中文

Komplette Toolchain zur Verbindung von Figma-Design und Frontend-Entwicklung, unterstützt 🖥️ GUI-Konfigurationsassistent, intelligente Extraktion von Design-Tokens, hochwertige Komponentengenerierung (React/Vue/Svelte/HTML usw.), automatischer Ressourcen-Download, MCP-Integration über Editoren hinweg. Optimiert für KI-Agenten, löst Kernprobleme wie div-soup, Kontextüberflutung, hartcodierte hex-Werte, Ressourcenpfadbehandlung, Flex-Layout-Verzerrung, fehlende Barrierefreiheit, responsive Anpassung, Paywall-Absicherung usw.

✨ v1.4.4 Paywall-Absicherung + Hochwertige Wiedergabe + Leistungsoptimierung

Kern-Absicherung und Wiedergabe

Leistungsoptimierung (neu in v1.4.4)

Leistungsvergleich (vor und nach Optimierung v1.4.4)

Leistungsoptimierungskonfiguration (optional, abwärtskompatibel)

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

📜 Versionsverlauf Zusammenfassung

✨ Funktionen Highlights

🚀 Schnellstart

📚 Möchten Sie eine prägnante, versionssynchrone Kurzanleitung? Siehe QUICKSTART.md (Chinesisch) / QUICKSTART.en-US.md (Englisch). Nachfolgend die ausführliche Anleitung.

Methode Null: GUI-Konfiguration (empfohlen für Anfänger ⭐)

Kein Befehl merken nötig, vollständige Konfiguration über die Browser-GUI:

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

# 或全局安装后
figma-dev gui

Nach dem Start öffnet sich automatisch der Browser (Standardport 54321, bei Belegung wird automatisch 54322/54323 versucht). Folgen Sie der Schritt-für-Schritt-Anleitung:

1. Begrüßungsseite - Kennenlernen der figma-dev-tools-Funktionen

2. Sprachauswahl - Zweisprachige Umschaltung Chinesisch/Englisch

3. Token-Konfiguration - Eingabe des Figma-Tokens, Live-Überprüfung der Gültigkeit

4. Editor-Erkennung - Automatische Erkennung von 8+ installierten Editoren, Auswahl und Ein-Klick-Installation der MCP-Konfiguration

5. Framework-Präferenz - Auswahl des bevorzugten Frameworks (React/Vue/HTML)

6. Abschlussseite - Konfiguration erfolgreich, Bereitstellung von Tutorial-Links

💡 Sie können die GUI auch über den Assistentenbefehl starten:

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

Methode Eins: Null-Konfiguration npx direkt ausführen (schnellste)

Keine Installation erforderlich, ein Befehl zum Starten des MCP-Servers:

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

In der Editor-MCP-Konfiguration verwenden:

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

Methode Zwei: Ein-Klick-Installation (empfohlen für langfristige Nutzung)

# 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

Das Installationsskript wird automatisch:

• Erkennen installierter KI-Editoren (Trae/VS Code/Cursor/Windsurf/Claude Desktop/Zed/Cline/Roo Code usw., 8+)

• Paketmanager automatisch erkennen (npm/pnpm/yarn/bun)

• Tool herunterladen/kompilieren

• MCP-Einstellungen für den entsprechenden Editor konfigurieren (Zed verwendet das Feld mcp_servers)

• .env.example-Vorlage generieren

💡 Einfachere Methode: Führen Sie figma-dev gui aus, um die GUI zur Ein-Klick-Erkennung und Installation der Editor-Konfiguration zu verwenden.

Methode Drei: Als Projektabhängigkeit installieren

# 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

Methode Vier: Aus lokalen Quellen installieren

# 克隆或复制 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 abrufen

1. Melden Sie sich bei Figma an

2. Klicken Sie oben rechts auf das Profilbild → Settings → Account

3. Suchen Sie Personal access tokens → Generate new token

4. Geben Sie einen Namen ein, aktivieren Sie die Berechtigung File content (Read only)

5. Kopieren Sie das generierte Token (⚠️ wird nur einmal angezeigt)

💡 Bei Verwendung der GUI-Konfiguration fügen Sie das Token einfach in der Browser-Oberfläche ein; es wird automatisch überprüft und gespeichert.

2. Token konfigurieren

Methode A: GUI-Konfiguration (empfohlen v1.3.0+)

figma-dev gui

Geben Sie das Token in der Browser-Oberfläche ein, die Gültigkeit wird in Echtzeit überprüft und automatisch sicher gespeichert.

Methode B: Sicherer Speicher (empfohlen v1.3.2+)

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

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

Methode C: Über Kommandozeilenparameter

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

Methode D: Über .env-Datei

Erstellen Sie eine .env-Datei im Verzeichnis figma-dev-tools/:

FIGMA_ACCESS_TOKEN=your-figma-token-here

Methode E: MCP-Konfiguration env

Fügen Sie in der Editor-MCP-Konfiguration hinzu:

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

3. Erstes Figma → Code-Beispiel

React + Tailwind (empfohlen, erweiterte Version v1.4.0):

Im KI-Editor (z. B. Trae) direkt sprechen:

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

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

Die KI führt automatisch den folgenden erweiterten Prozess (v1.3.2) aus:

1. figma_lint_design - Designrichtlinien-Vorprüfung (optional, zeigt Probleme an)

2. figma_parse_url - Link analysieren

3. figma_get_metadata - Seitenstrukturübersicht abrufen

4. figma_get_screenshot - Visuelle Basis abrufen

5. figma_generate_jsx - TSX-Code mit einem Klick generieren (mit Flex-Reparatur, a11y-Verbesserung, Designsystem-Ausrichtung, responsiver Inferenz)

6. figma_download_assets - Bildressourcen herunterladen (SVGO automatisch optimiert)

Andere Frameworks (Vue/Svelte/HTML usw.):

Verwenden Sie das Tool figma_get_structured_data, um die framework-unabhängige JSON-Struktur abzurufen:

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

CLI-Kurzerfahrung

# 🖥️ 启动 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-Toolreferenz

Insgesamt 19 MCP-Tools, sortiert nach Verwendungsablauf:

Detaillierte Parameter der Werkzeuge

figma_generate_jsx (v1.4.0 erweiterte Version, am häufigsten verwendet)

{
  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 erweiterte Ausgabe:

• Vollständiger React + TypeScript + Tailwind TSX-Code (Prettier-formatierte)

• 🔧 Flex-Korrekturbericht: Liste automatisch behobener Layoutprobleme (Symbolverformung, Textabschneidung usw.)

• ♿ Barrierefreiheitsverbesserungsbericht: Hinzufügung semantischer Tags, Alt-Texte, ARIA-Attribute

• 🎨 Designsystemvorschläge: Farb-/Abstands-/Eckenradius-/Schattenvariablen-Matching-Vorschläge

• 📱 Responsivitätsvorschläge: Breakpoint-Ableitung, sm/md/lg-Präfixvorschläge

• ⚠️ Liste der Token, die eine @theme-Erweiterung erfordern

• 🖼️ Liste der herunterzuladenden Ressourcen (nodeId, Name, Typ)

• 🧩 Hinweise auf wiederverwendbare Komponenten

• Knoten-Verdichtungsstatistik

• ✅ Bewertungshinweis zur Designkonformität (bei unter 80 Punkten wird empfohlen, zuerst zu korrigieren)

figma_lint_design (v1.3.2 neu, Vorabprüfung der Code-Wiederherstellungsqualität)

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

Prüfpunkte:

• Auto-Layout-Verwendungskonformität

• Ebenennamenskonformität

• Verwendung des 4px/8px-Rasters für Abstände/Größen/Eckenradien

• Wiederverwendung von Komponenten

• Minimale Klickgröße für Barrierefreiheit (48×48px)

• Tiefe der Verschachtelungsebenen

• Konsistenz der Textstile

• Farbverwendungskonformität

Ausgabe:

• Qualitätsbewertung von 0-100 Punkten

• Kategorisierte Statistik: Fehler/Warnungen/Hinweise

• Nach Kategorien gegliederte Problemliste

• Konkrete Korrekturvorschläge

• Siehe: FIGMA-DESIGN-GUIDELINES.md

figma_create_icon_sprite (v1.3.2 neu, SVG-Sprite-Generierung)

{
  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 neu, Mehrfach-Framework-Unterstützung)

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

Ausgabeinhalt:

• Vollständiges Framework-unabhängiges JSON-Struktur, jeder Knoten enthält:

  • id / name – Knotenbezeichner

  • role – Semantische Rolle (button/card/image/text/icon/section usw.)

  • type – Figma-Knotentyp (FRAME/TEXT/RECTANGLE/GROUP/INSTANCE usw.)

  • size – { width, height }

  • layout – Flex-Layout-Eigenschaften (display/flexDirection/justifyContent/alignItems/gap/padding usw.)

  • styles – Stileigenschaften (color/backgroundColor/borderRadius/shadow/fontSize/fontWeight usw.)

  • text – Textinhalt (nur für TEXT-Knoten)

  • asset – Ressourceninformationen (Bildknoten: Typ, Format, Download-URL)

  • children – Array von Unterknoten

• Vorschauzusammenfassung: semantische Rolle, Knotentyp, Größe, Gesamtknotenanzahl, Anzahl Farben, Anzahl Ressourcen, Anzahl Textknoten

• structuredContent – vollständiger strukturierter Knotenbaum, der direkt durchlaufen werden kann, um Code für beliebige Frameworks zu generieren

Unterstützte Frameworks:

• ✅ React / Next.js / Remix (besser in Kombination mit generate_jsx)

• ✅ Vue 2/3 / Nuxt

• ✅ Svelte / SvelteKit

• ✅ Natives HTML / CSS

• ✅ Angular

• ✅ SolidJS

• ✅ Qwik

• ✅ Astro

• ✅ Beliebiges Frontend-Framework

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-Befehlsreferenz

# 全局安装后使用
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-Beispiele:

# 🖥️ 启动 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

🖥️ Unterstützte Editoren (8+)

💡 Einfachste Konfigurationsmethode: Führe figma-dev gui aus. Starte die grafische Oberfläche, erkennt automatisch alle auf deinem Computer installierten Editoren, wähle die zu konfigurierenden Editoren aus und installiere mit einem Klick – kein manuelles Suchen nach Konfigurationsdateipfaden erforderlich.

MCP-Konfigurationsvorlage

Standardformat (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-Format (beachte das Feld 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"
      }
    }
  }
}

Zero-Config npx-Methode (keine lokale Installation erforderlich):

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

💡 Verwende npx figma-dev-tools install oder figma-dev gui. Erkennt automatisch Editoren und füllt die korrekten Pfade aus. Bei Zed wird automatisch das Feld mcp_servers verwendet.

⚙️ Konfigurationshinweise

Umgebungsvariablen (.env)

Kopiere .env.example in .env und fülle aus:

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

Token-Lesepriorität:

1. Kommandozeilenparameter --figma-api-key / -t / --token

2. In der GUI konfiguriertes und gespeichertes Token (v1.3.0 neu, automatisch in sicherem Speicher)

3. Standard-Token im sicheren Speicher (v1.3.2 neu, gespeichert mit figma-dev token set)

4. accessToken-Parameter beim Aufruf des MCP-Tools

5. env.FIGMA_ACCESS_TOKEN in der MCP-Konfiguration

6. FIGMA_ACCESS_TOKEN in der .env-Datei

7. Systemumgebungsvariable FIGMA_ACCESS_TOKEN

🏗️ Architekturdiagramm

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

📋 Projektstruktur

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 / Fehlerbehebung

F: Ich bin Anfänger und weiß nicht, wie ich konfigurieren soll?

Lösung (v1.3.0 neue Funktion – einfachste Methode): Starte direkt den GUI-Konfigurationsassistenten, ohne Befehle merken zu müssen:

npx figma-dev-tools gui

Der Browser öffnet automatisch die Konfigurationsoberfläche. Folge den Schritten:

1. Sprache auf Deutsch umstellen (oder Chinesisch/Englisch wählen)

2. Figma-Token einfügen (automatische Validierung)

3. Zu konfigurierende Editoren auswählen (automatische Erkennung installierter Editoren)

4. Auf Ein-Klick-Installation klicken – fertig!

F: Wie starte ich die GUI-Konfigurationsoberfläche?

Lösung (v1.3.0 neu): Es gibt drei Möglichkeiten, die GUI zu starten:

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

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

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

• Standardport: 54321

• Falls Port 54321 belegt ist, wird automatisch 54322, 54323 versucht

• Nach dem Start wird automatisch der Standardbrowser geöffnet

• Unterstützt Deutsch/Englisch-Umschaltung

• Token-Eingabe mit Echtzeit-Validierung

• Automatische Erkennung von 8+ Editoren und Ein-Klick-Installation

F: Kann ich den Port der GUI anpassen?

Lösung (v1.3.0 neu):

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

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

F: Der MCP-Server startet nicht?

Prüfung:

1. Wurde npm install && npm run build ausgeführt (oder entsprechende pnpm/yarn/bun-Befehle)?

2. Existiert die Datei dist/index.js?

3. Node.js-Version ≥ 20 (mit node -v prüfen)

4. Ist der Pfad in der MCP-Konfiguration korrekt? (Absolute Pfade empfohlen)

5. Zero-Config-Methode: direkt npx -y figma-dev-tools --figma-api-key=xxx verwenden

6. Empfohlen: zuerst mit GUI konfigurieren: figma-dev gui erledigt alles automatisch

F: API-Anfrage gibt 401 Unauthorized zurück?

Lösung:

1. Prüfen, ob FIGMA_ACCESS_TOKEN korrekt konfiguriert ist

2. Sicherstellen, dass das Token nicht abgelaufen ist (neu generieren)

3. Sicherstellen, dass das Token die Berechtigung File content (Read only) hat

4. Sicherstellen, dass du Zugriff auf die Figma-Datei hast (Datei muss für den Link sichtbar sein oder du bist Mitarbeiter)

5. Ab v1.3.0: Token in der GUI eingeben, Echtzeit-Validierung

6. Ab v1.3.2: figma-dev token set für sichere Speicherung verwenden, um Klartext-Konfigurationsfehler zu vermeiden

7. Versuche, das Token direkt über den Parameter --figma-api-key zu übergeben

F: Generierte Symbole werden zu Ellipsen/verzerrt?

Lösung (v1.3.2 automatische Korrektur):

• Dies ist ein klassisches Flex-Layout-Problem: Flex-Container setzen standardmäßig align-items: stretch, was Kindelemente streckt

• Ab v1.3.2 erkennt figma_generate_jsx dies automatisch und fügt align-items: center + flex-shrink: 0 + feste Breite/Höhe zur Korrektur hinzu

• Falls das Problem weiterhin besteht, rufe figma_lint_design auf, um die Auto-Layout-Einstellungen im Design zu überprüfen

F: Ich verwende Vue/Svelte/andere Frameworks, nicht React?

Lösung: Verwenden Sie das in v1.1.0 neu hinzugefügte Tool figma_get_structured_data, das eine frameworkunabhängige JSON-Struktur ausgibt, die vollständige Knotenhierarchie, Stile, Texte und Ressourceninformationen enthält. Basierend auf diesen Daten können Sie Code für jedes Framework generieren.

Die CLI unterstützt dies ebenfalls:

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

💡 Im GUI-Konfigurationsschritt „Framework-Präferenz“ können Sie Ihr bevorzugtes Framework auswählen.

F: Die generierten Komponentenfarben/-abstände stimmen nicht mit dem Design überein?

Lösung:

1. Stellen Sie sicher, dass in Figma Variablen zur Definition von Farben/Abständen verwendet werden und codeSyntax.WEB gesetzt ist.

2. Die Designsystem-Ausrichtungsfunktion von v1.3.2 gleicht automatisch Farb-/Abstands-/Schrift-/Ecken-/Schattenvariablen ab.

3. Empfohlenes Farbformat: oklch (nativ von Tailwind v4 unterstützt). Bei Problemen auf hex umstellen.

4. Farben, die keinen vorhandenen Token treffen, werden über @theme inline erweitert. Verwenden Sie nicht direkt bg-[#hex].

5. Überprüfen Sie die TODO-Kommentare im generierten Code und den Designsystem-Vorschlagsbericht.

6. Rufen Sie vor der Generierung figma_lint_design auf, um die Design-Spezifikation zu prüfen.

F: Der generierte Code enthält viele redundante verschachtelte Divs?

Lösung:

1. Verwenden Sie figma_generate_jsx aus v1.4.0 anstelle der älteren figma_generate_component.

2. UI-Designer sollten mehrfache sinnlose Group-Verschachtelungen vermeiden (Bereiche mit Frame abgrenzen).

3. Rufen Sie figma_lint_design auf, um Probleme mit der Verschachtelungstiefe zu prüfen.

4. Überprüfen Sie, ob Knoten, die im generierten Code als layout-only markiert sind, fälschlicherweise beibehalten wurden.

5. Große Abschnitte sollten in Blöcke aufgeteilt und einzeln generiert werden, um eine zu tiefe Knotenstruktur in einem Durchlauf zu vermeiden.

F: Bildressourcen werden nicht automatisch heruntergeladen?

Lösung:

1. Sie müssen das Tool figma_download_assets aufrufen und die pendingAssets[].nodeId aus der Ausgabe von generate_jsx übergeben.

2. Stellen Sie sicher, dass der Parameter sceneName gesetzt ist (Ressourcen werden im Verzeichnis public/<Szenenname>/ abgelegt).

3. Ab v1.3.2 werden SVGs beim Download automatisch mit SVGO optimiert und redundante Attribute entfernt.

4. Überprüfen Sie, ob die Bildknoten in Figma einen IMAGE-Fill haben.

5. Netzwerkproblem: Das Figma-Bild-CDN erfordert möglicherweise einen Proxy.

F: Wie kann der generierte Code responsiv gemacht werden?

Lösung (neue Funktion in v1.3.2):

1. figma_generate_jsx in v1.3.2 leitet automatisch responsive Breakpoints ab und gibt im Responsive-Vorschlagsbericht sm/md/lg-Präfixe vor.

2. Es wird empfohlen, das Design separat für Mobil/Desktop zu gestalten oder Auto Layout-Einschränkungen zu verwenden.

3. Fügen Sie basierend auf den Responsive-Vorschlägen manuell responsive Präfixe zu den Klassen hinzu (z. B. md:flex-row).

F: Dem generierten Code fehlen Barrierefreiheitsattribute?

Lösung (automatische Verbesserung in v1.3.2):

• figma_generate_jsx in v1.3.2 fügt automatisch hinzu:

  • Semantische HTML-Tags (<button> statt <div onClick>, <h1>-<h6> usw.)

  • Alt-Texte für Bilder

  • ARIA-Labels und -Rollen

  • Hinweise zur minimalen barrierefreien Klickgröße

• Der Barrierefreiheits-Verbesserungsbericht listet alle hinzugefügten Verbesserungen auf.

• Rufen Sie figma_lint_design auf, um Barrierefreiheitsprobleme im Design zu prüfen.

F: API-Anfragenratenbegrenzung?

• Die Figma-API hat eine Ratenbegrenzung (ca. 60 Anfragen/Minute).

• Beim Batch-Download von Ressourcen wird im Tool intern automatisch gedrosselt.

• Große Dateien sollten zur Vermeidung vieler Anfragen in kurzer Zeit aufgeteilt werden.

F: Welche Frontend-Frameworks werden unterstützt?

• React + Tailwind CSS: Erstklassige Unterstützung (TSX-Codegenerierung + volle Verbesserungen ab v1.3.2)

• Vue 2/3 / Nuxt: Über figma_get_structured_data strukturierte Daten abrufen, KI kann Vue SFC generieren

• Svelte / SvelteKit: Gleiches Vorgehen

• Angular: Gleiches Vorgehen

• SolidJS / Qwik: Gleiches Vorgehen

• Natives HTML / CSS: Gleiches Vorgehen

• Astro: Gleiches Vorgehen

• Next.js: Unterstützt, aber next/image nicht verwenden (normales <img> oder publicCdnUrl() verwenden)

• Vite + React: Empfohlen, am besten mit generiertem Code kompatibel

💡 Im GUI-Konfigurationsassistenten können Sie Ihre Framework-Präferenz auswählen.

F: Die Konfiguration des Zed-Editors funktioniert nicht?

Lösung: Zed verwendet das Feld mcp_servers (Unterstrich), nicht mcpServers (CamelCase).

• Verwenden Sie die grafische Oberfläche figma-dev gui zur Ein-Klick-Konfiguration, die automatisch die Feldunterschiede von Zed behandelt.

• Oder verwenden Sie npx figma-dev-tools install, das diesen Unterschied ebenfalls automatisch behandelt.

F: Wie kann ich die Oberflächensprache umschalten?

Lösung (neu in 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

💡 Im zweiten Schritt der GUI-Konfiguration können Sie auch direkt die Sprache auswählen.

F: Wie kann ich das Figma-Token sicher speichern?

Lösung (empfohlen ab v1.3.0+):

• Am einfachsten: Führen Sie figma-dev gui aus, geben Sie das Token in der GUI-Oberfläche ein, es wird automatisch verifiziert und im sicheren Speicher abgelegt.

• Befehlszeilenmethode (neu in 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

Das Token wird im systemeigenen sicheren Speicher gespeichert:

• macOS: Keychain

• Windows: Credential Manager

• Linux: libsecret (falls nicht verfügbar, Rückfall auf verschlüsselte Datei)

📖 Designrichtlinien

Siehe FIGMA-DESIGN-GUIDELINES.md – ein vollständiger Leitfaden zu Figma-Designrichtlinien für Designer und KI, einschließlich:

• Auto Layout-Nutzungsrichtlinien

• Namenskonventionen für Ebenen

• 4px/8px-Rastersystem

• Empfehlungen zur Wiederverwendung von Komponenten

• Barrierefreiheitsanforderungen

• Best Practices von Design zu Code

Es wird empfohlen, vor der Codegenerierung figma_lint_design auszuführen, um die Designqualität zu prüfen.

🎯 Vergleich mit anderen Lösungen

Der folgende Vergleich basiert auf öffentlich zugänglichen Informationen von 2025–2026 und spiegelt nur die Unterschiede zwischen figma-dev-tools v1.4.4 und den jeweiligen Lösungen wider, nicht deren vollständige Fähigkeiten. Mit „muss bestätigt werden“ gekennzeichnete Punkte sind in öffentlichen Quellen nicht eindeutig angegeben.

vs. Kommerzielle SaaS-Lösungen

vs. Open-Source / Offizielle Tools

Differenzierungsvorteile

• Paywall-Abfangmechanismus: Der exklusive BrowserFallbackService von figma-dev-tools v1.4.4 startet automatisch einen Playwright-Screenshot-Notfall, wenn die Figma-REST-API aufgrund einer Paywall fehlschlägt. Kein Wettbewerber bietet eine ähnliche Funktion.

• Wiedergabetreue-Prüfungszyklus: figma_verify_fidelity bietet Pixel-Diff + Differenz-Heatmap + quantitative Bewertung (0–100%). Andere Tools bleiben meist bei „pixel-perfect“-Werbung ohne automatisierte Prüfung.

• Frameworkunabhängige strukturierte Daten: figma_get_structured_data gibt standardisiertes JSON aus und unterstützt jedes Framework. Kommerzielle SaaS-Lösungen binden oft an bestimmte Frameworks.

• Open Source + Kostenlos + Voll funktionsfähig: MIT-Lizenz, keine kostenpflichtigen Sitze erforderlich, um alle 19 MCP-Tools zu nutzen.

📜 Lizenz

MIT © figma-dev-tools contributors