🎨 Figma Dev Tools v1.4.4

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

English | 中文

Kompletter Werkzeugkasten, der Figma-Design und Frontend-Entwicklung miteinander verbindet, unterstützt 🖥️ GUI-Konfigurationsassistent, intelligentes Extrahieren von Design-Tokens, hochwertige Komponentengenerierung (React/Vue/Svelte/HTML usw.), automatischer Ressourcen-Download, MCP-Integration zwischen Editoren. Speziell für KI-Agenten optimiert, um Kernprobleme wie Div-Suppe, Kontextexplosion, hartcodierte Hex-Werte, Ressourcenpfad-Handhabung, Flex-Layout-Verzerrung, fehlende Barrierefreiheit, reaktionsfähige Anpassung und Paywall-Absicherung zu lösen.

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

Kern-Absicherung und Wiedergabe

Leistungsoptimierungen (Neu in v1.4.4)

Leistungsvergleich (Vorher/Nachher v1.4.4-Optimierung)

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

📜 Versionshistorie Zusammenfassung

✨ Feature-Highlights

🚀 Schnellstart

📚 Möchtest du eine kompakte, 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 ⭐)

Keine Befehle merken nötig, komplette Konfiguration über die Browser-GUI:

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

# 或全局安装后
figma-dev gui

Nach dem Start wird automatisch der Browser geöffnet (Standard-Port 54321, bei Belegung automatisch 54322/54323 versucht), den Anweisungen folgen:

1. Willkommensseite - Figma-Dev-Tools-Funktionen kennenlernen

2. Sprachauswahl - Zweisprachiger Wechsel Chinesisch/Englisch

3. Token-Konfiguration - Figma-Token eingeben, Echtzeit-Validierung

4. Editor-Erkennung - Automatische Erkennung von 8+ installierten Editoren, MCP-Konfiguration mit einem Klick installieren

5. Framework-Präferenz - Bevorzugtes Framework auswählen (React/Vue/HTML)

6. Abschlussseite - Konfiguration erfolgreich, Link zur Anleitung

💡 Du kannst den GUI-Modus auch über den Assistentenbefehl starten:

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

Methode Eins: Null-Konfiguration npx Direktausführung (Schnellste)

Keine Installation erforderlich, MCP-Server mit einem Befehl starten:

# 直接通过 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 Langzeitnutzung)

# 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 führt automatisch durch:

• Erkennung installierter KI-Editoren (Trae/VS Code/Cursor/Windsurf/Claude Desktop/Zed/Cline/Roo Code u.a. 8+)

• Automatische Erkennung des Paketmanagers (npm/pnpm/yarn/bun)

• Download/Kompilierung des Tools

• Konfiguration der MCP-Einstellungen für die entsprechenden Editoren (Zed verwendet das Feld mcp_servers)

• Generierung der .env.example-Vorlage

💡 Einfacher: figma-dev gui ausführen, um die grafische Oberfläche zur Erkennung und Installation der Editor-Konfiguration zu nutzen.

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. Bei Figma anmelden

2. Rechts oben auf das Profilbild klicken → Settings → Account

3. Personal access tokens finden → Generate new token

4. Namen eingeben, Berechtigung File content (Read only) auswählen

5. Generierten Token kopieren (⚠️ wird nur einmal angezeigt)

💡 Bei GUI-Konfiguration den Token direkt im Browser-Interface einfügen; automatische Validierung und Speicherung.

2. Token konfigurieren

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

figma-dev gui

Token im Browser-Interface eingeben, Echtzeit-Validierung, dann 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 Befehlszeilenparameter

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

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

FIGMA_ACCESS_TOKEN=your-figma-token-here

Methode E: MCP-Konfiguration env

In der Editor-MCP-Konfiguration hinzufügen:

{
  "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 chatten:

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

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

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

1. figma_lint_design - Designregel-Vorprüfung (optional, Probleme anzeigen)

2. figma_parse_url URL parsen

3. figma_get_metadata Seitenstrukturübersicht abrufen

4. figma_get_screenshot Visuelle Basis abrufen

5. figma_generate_jsx TSX-Code mit einem Klick generieren (inkl. Flex-Korrektur, a11y-Verbesserungen, Designsystem-Ausrichtung, reaktionsfähige Inferenz)

6. figma_download_assets Bildressourcen herunterladen (SVGO automatisch optimiert)

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

Verwende figma_get_structured_data, um eine 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-Tool-Referenz

Insgesamt 19 MCP-Tools, nach Nutzungsablauf geordnet:

Detaillierte Tool-Parameter

figma_generate_jsx (v1.4.0 verbesserte 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;        // 可选，优先用环境变量
}

Verbesserte Ausgabe von v1.4.0:

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

• 🔧 Flex-Fixbericht: Liste automatisch korrigierter Layout-Probleme (Icon-Verzerrung, Textabschneidung usw.)

• ♿ Barrierefreiheitsverbesserungsbericht: Hinzugefügte semantische Labels, alt-Texte, ARIA-Attribute

• 🎨 Designsystem-Vorschläge: Vorschläge zur Variablenzuordnung von Farbe/Abstand/Radius/Schatten

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

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

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

• 🧩 Hinweise auf wiederverwendbare Komponenten

• Statistik der reduzierten Knoten

• ✅ Designrichtlinien-Bewertungshinweis (unter 80 Punkten wird eine vorherige Reparatur empfohlen)

figma_lint_design (Neu in v1.3.2, Qualitätsvorprüfung für Code-Umsetzung)

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

Prüfpunkte:

• Verwendung von Auto Layout

• Namenskonvention der Ebenen

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

• Wiederverwendung von Komponenten

• Minimale barrierefreie Klickgröße (48×48px)

• Verschachtelungstiefe

• Konsistenz der Textstile

• Verwendung von Farben

Ausgabe:

• Qualitätsbewertung 0-100 Punkte

• Kategorisierte Statistik von Fehlern/Warnungen/Hinweisen

• Nach Kategorien aufgeschlüsselte Problemliste

• Konkrete Reparaturempfehlungen

• Siehe: FIGMA-DESIGN-GUIDELINES.md

figma_create_icon_sprite (Neu in v1.3.2, 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 (Neu in v1.1.0, Multi-Framework-Unterstützung)

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

Ausgabeinhalt:

• Vollständige, framework-unabhängige 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 TEXT-Knoten)

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

  • children - Array der Unterknoten

• Vorschau-Zusammenfassung: Semantische Rolle, Knotentyp, Größe, Gesamtknotenzahl, Anzahl Farben, Anzahl Ressourcen, Anzahl Textknoten

• structuredContent - Vollständige strukturierte Knoten-Baumstruktur, die direkt durchlaufen werden kann, um Code für jedes Framework zu generieren

Geeignete Frameworks:

• ✅ React / Next.js / Remix (besser 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.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ühren Sie figma-dev gui aus Starten Sie die grafische Oberfläche, erkennen Sie automatisch alle auf Ihrem Computer installierten Editoren, wählen Sie die zu konfigurierenden Editoren aus und installieren Sie mit einem Klick – ohne manuelle Suche nach Konfigurationsdateipfaden.

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 (Beachten Sie, dass das Feld mcp_servers heißt):

{
  "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"]
    }
  }
}

💡 Verwenden Sie npx figma-dev-tools install oder figma-dev gui Es erkennt automatisch den Editor und füllt den korrekten Pfad aus. Bei Zed wird automatisch das Feld mcp_servers verwendet.

⚙️ Konfigurationshinweise

Umgebungsvariablen (.env)

Kopieren Sie .env.example in .env und füllen Sie 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. Befehlszeilenargument --figma-api-key / -t / --token

2. Über die GUI-Oberfläche konfiguriertes und gespeichertes Token (v1.3.0 neu, automatisch in sicherem Speicher abgelegt)

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

4. accessToken-Parameter, der beim Aufruf des MCP-Tools übergeben wird

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

📋 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 die Konfiguration vornehmen soll?

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

npx figma-dev-tools gui

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

1. Wählen Sie die Sprache (Deutsch)

2. Fügen Sie Ihren Figma-Token ein (automatische Validierung)

3. Wählen Sie die zu konfigurierenden Editoren aus (automatische Erkennung installierter Editoren)

4. Klicken Sie auf Ein-Klick-Installation – fertig!

F: Wie starte ich die GUI-Konfiguration?

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

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

• Nach dem Start wird automatisch der Standardbrowser geöffnet

• Unterstützt Deutsch/Englisch-Umschaltung

• Echtzeit-Validierung der Token-Eingabe

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

F: Kann ich den GUI-Port 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?

Überprü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. Für Zero-Config direkt npx -y figma-dev-tools --figma-api-key=xxx verwenden

6. Empfohlen: Zuerst mit GUI konfigurieren: figma-dev gui erledigt die gesamte Konfiguration automatisch

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

Lösung:

1. Überprü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 Sie Zugriff auf die Figma-Datei haben (Datei muss für den Link sichtbar sein oder Sie sind Mitarbeiter)

5. Ab v1.3.0 können Sie das Token über die GUI-Oberfläche eingeben und in Echtzeit auf Gültigkeit prüfen

6. Ab v1.3.2 können Sie mit figma-dev token set das Token sicher speichern, um Klartext-Konfigurationsfehler zu vermeiden

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

F: Generierte Symbole werden zu Ellipsen/verzerrt?

Lösung (v1.3.2 automatische Reparatur):

• Dies ist ein klassisches Flex-Layout-Problem: Flex-Container standardmäßig align-items: stretch dehnt untergeordnete Elemente

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

• Wenn das Problem weiterhin besteht, rufen Sie 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 framework-unabhängige JSON-Struktur mit vollständigen Knotenhierarchien, Stilen, Texten und Asset-Informationen ausgibt. Basierend auf diesen Daten können Sie Code für jedes Framework generieren.

CLI unterstützt auch:

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

💡 Im Schritt "Framework-Präferenz" der GUI-Konfiguration können Sie Ihr bevorzugtes Framework auswählen.

F: Die generierten Komponenten haben andere Farben/Abstände als das Design?

Lösung:

1. Stellen Sie sicher, dass in Figma Variablen für Farben/Abstände verwendet werden und codeSyntax.WEB gesetzt ist

2. Die Designsystem-Ausrichtung in 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 umschalten

4. Farben, die nicht auf vorhandene Tokens passen, werden über @theme inline erweitert – nicht direkt bg-[#hex] schreiben

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

6. Rufen Sie vor der Generierung figma_lint_design auf, um die Designrichtlinien 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, bedeutungslose Group-Verschachtelungen vermeiden (verwenden Sie Frame zur Bereichsaufteilung).

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 zur Generierung in Blöcke aufgeteilt werden, um die Verarbeitung zu tiefer Knotenbäume in einem Durchgang 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 Herunterladen automatisch mit SVGO optimiert, um redundante Attribute zu entfernen.

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

5. Netzwerkproblem: Der Figma-Bild-CDN erfordert möglicherweise einen Proxy/Zugang.

F: Wie kann der generierte Code responsiv gemacht werden?

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

1. figma_generate_jsx aus v1.3.2 erkennt automatisch responsive Breakpoints und gibt im Responsive-Vorschlagsbericht Empfehlungen mit sm/md/lg-Präfixen.

2. Es wird empfohlen, Designs getrennt für Mobil/Desktop zu erstellen oder Auto-Layout-Constraints zu verwenden.

3. Passen Sie die Klassennamen basierend auf den Responsive-Vorschlägen manuell an, indem Sie responsive Präfixe hinzufügen (z. B. md:flex-row).

F: Dem generierten Code fehlen Barrierefreiheits-Attribute?

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

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

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

  • Alt-Text für Bilder

  • ARIA-Labels und -Rollen

  • Hinweise zur Mindestgröße für barrierefreie Klickziele

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

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

F: API-Anforderungsratenbegrenzung?

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

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

• Bei großen Dateien wird eine Aufteilung empfohlen, um eine hohe Anzahl von Anfragen in kurzer Zeit zu vermeiden.

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: Wie oben.

• Angular: Wie oben.

• SolidJS / Qwik: Wie oben.

• Natives HTML / CSS: Wie oben.

• Astro: Wie oben.

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

• Vite + React: Empfohlen, passt am besten zum generierten Code.

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

F: Die Konfiguration für den Zed-Editor funktioniert nicht?

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

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

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

F: Wie kann ich die Oberflächensprache wechseln?

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-Konfigurationsoberfläche 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 validiert 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 Systemsicherheitsspeicher abgelegt:

• macOS: Keychain

• Windows: Credential Manager

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

📖 Designrichtlinien

Siehe FIGMA-DESIGN-GUIDELINES.md – der vollständige 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

• Anforderungen an barrierefreies Design

• 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 Fähigkeitsunterschiede zwischen figma-dev-tools v1.4.4 und den jeweiligen Lösungen wider, nicht deren gesamtes Können. Mit „zu bestätigen“ gekennzeichnete Punkte sind in öffentlichen Quellen nicht eindeutig geklärt.

vs. Kommerzielle SaaS-Lösungen

vs. Open-Source / Offizielle Tools

Differenzierungsvorteile

• Paywall-Absicherung: Der exklusive BrowserFallbackService von figma-dev-tools v1.4.4 startet automatisch einen Playwright-Screenshot-Fallback, wenn die Figma-REST-API aufgrund einer Paywall fehlschlägt. Kein Wettbewerber bietet einen ähnlichen Mechanismus.

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

• Framework-unabhängige Strukturdaten: figma_get_structured_data gibt standardisiertes JSON aus, das jedes Framework unterstützt. Kommerzielle SaaS-Lösungen sind oft an bestimmte Frameworks gebunden.

• Open Source + Kostenlos + Voll funktionsfähig: MIT-Lizenz, alle 19 MCP-Tools ohne kostenpflichtigen Sitz nutzbar.

📜 Lizenz

MIT © figma-dev-tools contributors