Html To Figma Design System MCP Server

Mimic AI

The reviewer for your design system — builds in Figma, learns your conventions, flags your gaps.

Mimic translates HTML into Figma using your published components and tokens. It gets smarter about your DS over time: corrections become rules, repeated patterns auto-verify, and every build reports what your system is missing. Runs locally. Your design data never leaves your machine.

Not a Figma product. Independent, open-source MCP server. Works with any MCP client — Claude Code, Cursor, VS Code, Windsurf, JetBrains.

---

Demo coming soon — a screen recording showing DS components being inserted in real time and the learning summary at the end.

---

Works with any design system

Team libraries, community libraries, component-only kits — Mimic adapts to what your DS provides.

Verified with: LayerLens Theme (team), Material UI for Figma (community), HeroUI Figma Kit (community).

---

How it learns

Mimic keeps a local file (ds-knowledge.json) that records how HTML patterns map to your design system components. Each build loads what it knows, uses the cache, and saves what it discovered.

Your corrections teach it. If Mimic picks the wrong component, tell it: "That's wrong — use Button/Primary, and remember it." The mapping updates immediately and applies on every future build.

Your DS evolves, Mimic notices. New components, removed components, variant changes — detected at the start of every build. Stale cache entries are invalidated and re-discovered from the live DS. The design system is always the source of truth, never the cache.

Every build reports what it learned. Patterns saved, patterns promoted, searches skipped, and gaps detected. Gap reports surface what your DS is missing — Mimic doubles as a design system audit tool.

The knowledge is yours. Inspectable JSON on your machine. Nothing is sent anywhere. Share the file with your team if you want everyone to start with the same learned mappings.

---

What you can do

Translate an HTML prototype into Figma

"Here's my HTML prototype. Build it in Figma on the 'Screens' page. Use my design system components wherever possible."

Build UI from a description

"Build a dashboard with 4 KPI cards, a data table with sortable columns, and a donut chart. Use my top-nav shell and spacing-xl gaps."

Target specific components and tokens

"Use my Sidebar, Modal/Large, and FormInput components. surface-secondary background, text-secondary labels."

---

Quick start

Before you begin: You need Node.js v20.6 or later, the Figma desktop app (the browser version won't work), and a Figma Professional plan or above (the free plan can't publish component libraries, which Mimic needs).

Step 1 — Install Mimic

Open a terminal (on Mac: search for "Terminal" in Spotlight) and paste this command:

bash <(curl -fsSL https://raw.githubusercontent.com/miapre/mimic-ai/main/install.sh)

The script downloads Mimic, installs what it needs, asks for your Figma token, and registers the tool. It takes about a minute.

Step 2 — Install the Figma plugin

1. Open Figma desktop
2. Go to Plugins → Development → Import plugin from manifest...
3. Find the mimic-ai folder the script just created (usually in your home folder: ~/mimic-ai/plugin/) and select manifest.json
4. The plugin now appears under Plugins → Development → Mimic AI

Step 3 — Start Mimic (do this each session)

Open a terminal and paste this:

cd ~/mimic-ai && npm run bridge

Keep this terminal window open — it's the connection between your AI assistant and Figma.

Then in Figma desktop: go to Plugins → Development → Mimic AI → Run. You'll see a small badge that says ● ready — that means the connection is live.

Verify the connection. Ask your AI assistant: "Check mimic status." You should see bridge connected, plugin connected, and your DS libraries listed. If anything is missing, fix it before building.

Step 4 — Enable your design system

Open the Figma file where you want to build. Then:

1. Click the book icon in the left sidebar (Assets panel)
2. Click the library icon at the top (looks like a grid of squares)
3. Find your design system in the list and toggle it on

You only need to do this once per file. Without it, Mimic can't find your components.

Using a community library? Community libraries (Material UI, HeroUI, iOS kits, etc.) work out of the box. Enable the library in your file and Mimic handles the rest — components import normally, and variables are discovered via the Figma REST API and imported by key. No need to duplicate or re-publish.

You're ready

Ask your AI assistant to build something. Include a Figma link to the file and page, or describe where you want the output.

---

Works with any MCP client

Mimic uses MCP (Model Context Protocol), the open standard that connects AI assistants to external tools. The build protocol, voice, and learning pipeline are optimized for Claude Code — other MCP clients can create and edit Figma, but may not follow the full governance lifecycle or produce learning reports. Add it to your client's config:

The install script registers Mimic automatically. Or add manually to ~/.claude/settings.json:

{
  "mcpServers": {
    "mimic-ai": {
      "command": "npx",
      "args": ["-y", "@miapre/mimic-ai"]
    }
  }
}

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "mimic-ai": {
      "command": "npx",
      "args": ["-y", "@miapre/mimic-ai"]
    }
  }
}

Click the VS Code install badge at the top of this README, or add to your VS Code settings:

{
  "mcp": {
    "servers": {
      "mimic-ai": {
        "command": "npx",
        "args": ["-y", "@miapre/mimic-ai"]
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mimic-ai": {
      "command": "npx",
      "args": ["-y", "@miapre/mimic-ai"]
    }
  }
}

Settings → Tools → AI Assistant → MCP Servers → Add:

{
  "mimic-ai": {
    "command": "npx",
    "args": ["-y", "@miapre/mimic-ai"]
  }
}

Regardless of which client you use, you still need the bridge running (Step 3) and the Figma plugin active. The config above just tells your AI assistant where to find Mimic's tools.

---

Desktop app required

The browser version of Figma won't work — the bridge connects to the plugin over a local network connection that only the desktop app supports. Download Figma desktop

Personal Access Token

The bridge needs a Figma token to look up your published component keys. Think of it as a password that lets Mimic read (not write) your library metadata.

1. Open Figma desktop → click your profile picture (top-left) → Settings
2. Scroll to Personal access tokens → Generate new token
3. Name it something like mimic-ai, set read access
4. Copy the token immediately — Figma only shows it once
5. Paste it when the install script asks

Publish your design system

Your components and tokens need to be in a separate Figma file, published as a team library. If you haven't done this:

1. Open your design system file
2. Click the book icon → library icon → Publish

Re-publish after adding or updating components — otherwise Mimic won't see the changes.

Enable the library in your target file

Publishing makes the library available to your team. Enabling makes it usable in a specific file. You only need to do this once per file: Assets panel → Team library icon → toggle your DS on.

Figma plan

Publishing component libraries and using design tokens (variables) requires a Professional plan or above. The free plan lets Mimic create basic frames and text, but it can't insert components or bind tokens — which is the whole point.

---

How it works

Your AI assistant → Mimic MCP server → Bridge → Figma Plugin → Your Figma file

Writes are unlimited. Every frame Mimic creates, every component it inserts, every token it binds — these go through Figma's plugin channel, which has no rate limit.

Reads are limited. Inspecting library components and reading design context draw from a daily quota (200 on Professional, 600 on Enterprise). Mimic minimizes reads, caches aggressively, and stops if the budget would be exceeded mid-build.

All token bindings are real — nodes use your actual design system variables. Update a token in your library, re-publish, and the Figma nodes update automatically.

CSS maps to Figma auto-layout. Mimic reads the HTML's CSS properties and translates them directly: display: flex → auto-layout, gap → itemSpacing bound to DS spacing variables, max-width + margin: auto → FILL + maxWidth + parent CENTER, align-items: flex-end → counterAxisAlignItems MAX. The CSS→Figma reference table in CLAUDE.md documents every mapping.

---

Quality built in — not bolted on

Every build is checked by 6 specialist roles before it's reported as done. A 7th role (Marketing & Communications) ensures public documentation stays current. You don't invoke them — they run automatically.

How it works without costing you tokens:

1. Plugin-level enforcement (free) — The Figma plugin automatically hides icon placeholders, sets auto-layout defaults, and rejects raw values in strict mode. Zero tool calls, zero tokens. It just happens.

2. Inline warnings (free) — Every tool response includes warnings if something isn't DS-compliant: "Text created without DS text style," "Frame fill is raw hex." These are in responses you'd already see — no extra calls.

3. Build completion audit (1 call) — At the end of the build, one audit checks everything: DS compliance, content fidelity, learning pipeline. If anything fails, it gets fixed before you see "Build complete."

The result: 46 rules enforced, 0 extra tool calls for enforcement.

Full specification: GOLDEN_RULES.md, ROLES.md, VOICE_AND_TONE.md.

---

Available tools

---

Project structure

mcp.js              — MCP server, exposes tools to your AI assistant
bridge.js           — Local bridge between the MCP server and Figma plugin
plugin/
  code.js           — Figma plugin (runs inside Figma's sandbox)
  ui.html           — Plugin UI and connection indicator
  manifest.json     — Plugin manifest

internal/
  rendering/        — URL rendering, input resolution
  resolution/       — Component matching, icon resolution
  layout/           — Layout tree builder, direction detection
  learning/         — Build completion, knowledge persistence
  parsing/          — HTML parsing

CLAUDE.md           — Build protocol, CSS→Figma mapping, phased lifecycle
GOLDEN_RULES.md     — 46 rules governing every build
ROLES.md            — 6 roles operating as build gates
VOICE_AND_TONE.md   — Identity, voice principles, output formats
KNOWN_ISSUES.md     — Compatibility matrix and limitations
CHANGELOG.md        — Version history
docs/
  GUIDE.md          — Full setup guide, DS structure, build patterns
  knowledge-schema.md — Knowledge file schema reference

---

Privacy

Runs entirely on your machine. No design data, component names, token values, or HTML content is sent to any external server. The only outbound call is to the Figma REST API to look up published component keys — the same call Figma's own plugins make.

---

Troubleshooting

"Figma plugin is not connected" → Open Figma desktop → Plugins → Development → Mimic AI → Run. The plugin runs per file — if you switch to a different Figma file, you need to run the plugin again in that file.

"Library import failed" → Your design system isn't enabled in the target file. Open the Assets panel → Team library → toggle it on.

"No component key" → The component isn't published. Open your DS file → Assets → Team library → Publish.

"DS_VARIABLE_NOT_FOUND" → The variable path doesn't match what's in the DS. Run mimic_discover_ds to refresh the DS inventory, or check variable naming with figma_read_variable_values.

Plugin code changes not taking effect → The Figma plugin loads code.js once at startup. Close and reopen the plugin in Figma to load updated code.

---

Known constraints

• Figma Professional plan required. The free plan can't publish component libraries, which Mimic needs to import your DS components.
• First-build font caching. If text styles don't apply on the very first build, it's because Figma hasn't cached the font data yet. Re-run the build — the second attempt will succeed.
• npx mode doesn't support library imports. The one-click npx -y @miapre/mimic-ai install doesn't set a FIGMA_ACCESS_TOKEN, which is needed for importing components from team libraries. Use the full installer script for team library support.
• Governance is Claude-optimized. The 46 rules, phased lifecycle, and learning reports are followed by Claude Code. Other MCP clients will have the tools but may not follow the protocol unless their LLM is instructed to read CLAUDE.md.
• Chart geometry uses absolute positioning. Donut arcs, scatter dots, and line paths use pixel calculations. Everything else in charts (bars, labels, legends, containers) uses auto-layout and DS tokens.

---

License

MIT