figcraft

FigCraft

English | 中文

AI-powered Figma plugin for design quality. Two-way bridge between AI IDEs and Figma — create UI, review designs, sync tokens, lint for compliance, audit, and auto-fix, all via natural language. Works great on its own, and even better alongside the official Figma MCP server.

New here? Start with docs/introduction.md for a 5-minute product tour (positioning, three core capabilities, FAQ). This README focuses on installation and reference.

What can you do with it?

Describe what you want in natural language, and FigCraft + Figma MCP make it happen in Figma:

"Create a login screen, then lint the whole page and auto-fix issues"

"Sync tokens from my DTCG JSON to Figma variables, diff and update"

"Check WCAG contrast and target sizes on this page, auto-fix what you can"

Features

• 🎨 From creation to delivery, fully covered — Create UI directly in Figma with 116 MCP tools. Build frames, components, variants, icons — check quality right after, fix issues on the spot
• 🧠 Opinion Engine — auto-infers layout direction, sizing, token bindings, and catches parameter conflicts before they hit Figma. You describe what, it figures out how
• 🔍 Automated design audit — token bindings, color contrast, spacing, component health — all checked in one pass · Full guide →
• 🔧 Lint + fix in one step — 40 rules covering token compliance, WCAG, layout structure — one command to batch-fix everything flagged
• 🔄 Two-way token sync — DTCG JSON ↔ Figma variables, Light/Dark multi-mode in one step. Changed tokens in code? Just sync
• 🔀 Dual mode for any team — Library mode for Figma shared libraries, Spec mode for DTCG JSON — pick what fits your workflow
• 📐 Prototype → dev docs — parse prototype interactions into Mermaid flow diagrams + interaction specs, no more manual handoff docs
• 🛡️ Harness Pipeline — auto-verifies every creation, recovers from errors with actionable suggestions, and tracks quality debt across turns

Quick Start

Requires Node.js >= 20.

1. Install the Figma Plugin

FigCraft is not yet on the Figma Community. Build from source:

git clone https://github.com/DivikWu/figcraft.git
cd figcraft
npm install
npm run build

Then in Figma Desktop:

1. Plugins → Development → Import plugin from manifest
2. Select the manifest.json file from the cloned repo

2. Add MCP Servers to your IDE

FigCraft handles both UI creation and design quality on its own. For even more creation capabilities, you can add the official Figma MCP server alongside it — both servers run in parallel and complement each other.

Note: figcraft-design is not yet published to npm. You need to build from source first (step 1 above). Replace cwd below with the absolute path to your local clone.

FigCraft config (same for all IDEs):

{
  "mcpServers": {
    "figcraft": {
      "command": "node",
      "args": ["dist/mcp-server/index.js"],
      "cwd": "/your/absolute/path/to/figcraft"
    }
  }
}

FigCraft works standalone for both UI creation and design quality. Adding the Figma MCP server gives you even more creation capabilities.

<details> <summary><strong>Adding the official Figma MCP server (for extra creation capabilities)</strong></summary>

Figma provides two deployment options:

Desktop server (local, runs inside Figma Desktop App):

1. Open Figma Desktop → Dev Mode → Enable MCP server in the inspect panel
2. Add to your IDE config:

{
  "mcpServers": {
    "figma-desktop": {
      "url": "http://127.0.0.1:3845/mcp"
    }
  }
}

Remote server (cloud, broader feature set — recommended by Figma): See Figma's remote server setup guide.

For full details, see the official Figma MCP documentation. </details>

Put it in the right file for your IDE:

📦 If you cloned this repo for fork-and-use, the shared project configs are already committed: .cursor/mcp.json, .mcp.json, .kiro/settings/mcp.json.example — plus .claude/settings.json for Claude Code's auto-approval. Copy the Kiro example to .kiro/settings/mcp.json for local Kiro use. Each IDE has a different auto-approval mechanism — see the per-IDE notes below or user-guide §6.5 for the full table.

<details> <summary><strong>Cursor</strong> — <code>.cursor/mcp.json</code></summary>

Create .cursor/mcp.json in your project root with the config above.

Auto-approval is configured separately at user level — Cursor does NOT auto-approve from .cursor/mcp.json. Create ~/.cursor/permissions.json:

{ "mcpAllowlist": ["figcraft:*", "figma-desktop:*"] }

(See Cursor permissions docs. Auto-Run mode must be enabled in Cursor settings for the allowlist to apply.) </details>

<details> <summary><strong>Claude Code</strong> — <code>.mcp.json</code></summary>

Create .mcp.json in your project root with the config above.

Auto-approval: Claude Code ignores any autoApprove field inside .mcp.json (that field is a Cursor/Kiro extension, not MCP standard). Use .claude/settings.json instead:

{
  "permissions": {
    "allow": ["mcp__figcraft__create_frame", "mcp__figcraft__nodes", "..."]
  }
}

This repo's pre-committed .claude/settings.json already lists all 122 figcraft approval entries (119 schema tools + 3 toolset meta tools) + 13 figma-desktop tools. Run npm run schema to regenerate after upstream tool changes. </details>

<details> <summary><strong>Kiro</strong> — <code>.kiro/settings/mcp.json</code></summary>

Copy .kiro/settings/mcp.json.example to .kiro/settings/mcp.json in your project root. Kiro supports autoApprove natively:

{
  "mcpServers": {
    "figcraft": {
      "command": "npx",
      "args": ["tsx", "packages/figcraft-design/src/index.ts"],
      "cwd": "${workspaceFolder}",
      "disabled": false,
      "autoApprove": ["ping", "create_frame", "nodes", "..."]
    }
  }
}

This repo's pre-committed .kiro/settings/mcp.json.example already auto-approves all 122 figcraft approval entries (119 schema tools + 3 toolset meta tools). Tools are surfaced in Kiro as mcp_figcraft_<tool> (e.g. mcp_figcraft_ping).

Tip: This repo includes .kiro/steering/figcraft.md as a workflow guide. Copy it to your project's .kiro/steering/ folder.

</details>

<details> <summary><strong>Antigravity (Google)</strong> — MCP Server management panel</summary>

Open Antigravity → Agent dropdown → Manage MCP Servers → View raw config, then paste the config above. </details>

<details> <summary><strong>Codex CLI (OpenAI)</strong> — <code>~/.codex/config.toml</code></summary>

[mcp_servers.figcraft]
command = "node"
args = ["dist/mcp-server/index.js"]
cwd = "/your/absolute/path/to/figcraft"

</details>

3. Connect & Verify

Open the FigCraft plugin in Figma — both sides auto-connect via the WebSocket relay. The plugin UI shows the channel ID and connection status.

To verify the connection works, ask your AI IDE to run the ping tool. If it returns a response, you're all set.

Troubleshooting: If the connection fails, check that port 3055 is not occupied by another process. The relay will auto-try ports 3056–3060 as fallback.

Architecture

FigCraft operates on a single Plugin Channel to Figma:

AI IDE (Kiro / Cursor / Claude Code / Antigravity / Codex)
    │ MCP (stdio)
    ▼
MCP Server (Node.js)
    └── Plugin Channel ──→ WS Relay (:3055) ──→ Figma Plugin
        (lint, audit, token sync, node ops)

• Plugin Channel: WebSocket relay to the FigCraft Figma Plugin. Required for all operations — creation, lint, audit, node inspection, and token sync all run through the Plugin API sandbox.
• ping checks Plugin Channel connectivity and reports status.
• FigCraft handles UI creation, design system search, component management, and design-to-code context extraction natively. The official Figma MCP server complements it with FigJam support and Code Connect publishing.

Dual Mode

| Mode | Token Source | Lint Behavior | Use Case | |------|-------------|---------------|----------| | Library | Figma shared library | Check variable/style bindings | Daily design with team library | | Spec | DTCG JSON files | Check values against token specs | Spec-driven validation |

Switch modes via set_mode tool or the plugin UI.

UI Creation

FigCraft creates UI directly in Figma — frames, text, SVG, components, variants, icons, and images. The Opinion Engine auto-infers layout, sizing, and token bindings so you describe structure, not implementation details. GRID layout, nested children trees, and batch operations are all supported.

• create_frame with inline children builds entire screen hierarchies in one call
• create_component / create_component_set build reusable component libraries with variant guardrails
• create_image_frame_from_local imports local PNG/JPEG/GIF files as image-filled frames; fill_existing_image_from_local replaces existing fills with edit access
• import_html converts static HTML, local .html files, or simple URLs into editable FigCraft frame/text/image layers
• After creating UI, the Harness Pipeline auto-verifies quality; or run lint_fix_all manually
• Use get_design_context to extract node trees with resolved tokens for design-to-code workflows

Lint Rules (40)

Current lint coverage spans token compliance, WCAG accessibility, layout structure, screen-level quality, naming, and component health.

• Token compliance (5): color, typography, radius, hardcoded token usage, missing text style
• WCAG accessibility (5): contrast, target size, text size, line height, non-text contrast
• Layout & Structure (27): screen shell validation, misclassified interactive root, nested interactive shell, missing auto-layout, empty container, spacer frames, nesting depth, button variants (solid/outline/ghost/text/icon), standalone link, text overflow, form consistency, CTA width consistency, overflow parent, HUG/STRETCH paradox, section spacing collapse, screen bottom overflow, social/nav/stats row crowding, input field structure, mobile dimensions, elevation consistency, elevation hierarchy
• Naming & Content (2): default name detection, placeholder text detection
• Component (1): component property binding checks

See docs/generated/lint-rules.md for the complete rule reference.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | FIGCRAFT_RELAY_PORT | Relay WebSocket port | 3055 | | FIGCRAFT_RELAY_URL | Full WebSocket relay URL (overrides port) | ws://localhost:3055 | | FIGCRAFT_CHANNEL | Channel ID | figcraft | | FIGMA_API_TOKEN | Figma Personal Access Token (for REST API fallback; can also be set in plugin UI or via OAuth) | — | | FIGCRAFT_ACCESS | Access control level: read, create, or edit | edit |

Development

Requires Node.js >= 20.

npm install
npm run build          # Build all (MCP server + relay + plugin)
npm run build:plugin   # Build Figma plugin only
npm run dev:relay      # Start WebSocket relay server (for debugging)
npm run dev:mcp        # Start MCP server (stdio transport)
npm run schema         # Regenerate tool registry from schema/tools.yaml
npm run content        # Compile templates, guides, and prompts from content/
npm run typecheck      # TypeScript type check
npm run test           # Run unit tests (vitest)

For details on content assets (templates, guides, prompts) and how to add new ones, see docs/asset-maintenance.md.

<details> <summary><strong>Run MCP server from source (for development)</strong></summary>

Instead of npx figcraft-design, point your IDE to the local source:

{
  "mcpServers": {
    "figcraft": {
      "command": "npx",
      "args": ["tsx", "packages/figcraft-design/src/index.ts"],
      "cwd": "/path/to/figcraft"
    }
  }
}

</details>

Contributing

Contributions welcome! Fork the repo and open a Pull Request.

Before submitting, make sure:

npm run typecheck      # Type check passes
npm run test           # Tests pass

License

MIT