Mimic AI

An MCP that builds in Figma using your design system — and gets faster every time.

Mimic AI translates HTML into Figma using your published components and design tokens. It's built for how Figma's API actually works: reads are limited, writes are not. So Mimic minimizes reads, caches what it learns, and uses the budget where it counts. By run 3, familiar patterns require no lookups at all. By run 10, most builds are nearly free.

Not a Figma product. This is an independent, open-source MCP server built for Claude Code.

How Mimic works with Figma limits

Figma's API has two kinds of operations: reads and writes. They behave very differently.

Writes are free. Every frame Mimic creates, every component it inserts, every token it binds — these use Figma's plugin channel, which has no rate limit. Mimic can write as much as it needs.

Reads are limited. Figma's official MCP tools — inspecting library components, reading design context, capturing screenshots — draw from a daily quota (200 on Professional plans, 600 on Enterprise). These calls are shared across everything you do in Claude that day.

Mimic is designed around this reality. It enters every build in Instant mode by default: reads only what it must, caches everything it learns, and uses the quota as little as possible. A cold build might use 3–5 reads. A warm build might use 1. A fully learned build might use none.

How it learns

Mimic maintains a local knowledge file — ds-knowledge.json — that records how HTML patterns map to your DS components and which variable IDs belong to which tokens. Every run loads from it before doing any library inspection, and writes back what it used.

Learning also improves consistency. The same HTML pattern resolves to the same DS component every time — no variance between runs. And it improves speed: fewer lookups mean Claude spends more time building and less time discovering.

The knowledge file is yours. It lives on your machine, travels with your project, and is fully inspectable JSON. Nothing is sent anywhere.

Your corrections teach Mimic. If Mimic inserts the wrong component, tell Claude: "That component was wrong — use [the correct one] instead, and remember it for next time." Claude demotes the mapping, records the correction, and uses the right component from that point on. No configuration needed — a plain sentence is enough.

Your DS evolves and Mimic notices. When a new component is added that's a better match for an existing mapping, Mimic flags it in the run report. It never auto-switches — you decide.

Theme decisions are remembered. On the first build in a file, Mimic asks whether to use Light or Dark mode (if your DS supports both). Your answer is stored and auto-applied on every future build in that file — no repeated questions. If you consistently pick the same theme across files using the same DS, it becomes the default for new files too.

Failures become rules. If a DS component can't be used correctly (wrong variant structure, import failure, label that can't be hidden), Mimic records it and skips the failed approach on the next run — going straight to a clean fallback instead of retrying and failing again. These rules are adaptive: after several builds, Mimic re-checks whether the DS has been updated and the issue is resolved.

Every run produces a learning summary. At the end of each build, Claude reports how many patterns were saved, how many were promoted to VERIFIED, how many reads were used, and any design system gaps detected. Gap reports are the clearest signal about what your DS might be missing.

Before every build — two things Mimic needs

1. Where to build Mimic will always ask where in Figma you want the output before it starts. You can answer with a Figma link (file, page, or specific frame), or just describe it in plain language: "my product file, the Screens page, next to the Login artboard." If your original request already includes a link, Mimic skips the question.

2. A library enabled in that file Mimic needs your component library to be enabled in the target Figma file — not just published in your DS file. If no library is found, Mimic stops and tells you exactly how to enable it before continuing. It will never build a screen without DS components and call it done.

What to expect on your first run

The first run is the most expensive — in reads, in time, and in imperfection. That's expected, and the gap closes fast.

Instant mode is always on by default. Before building, Mimic runs a pre-build intelligence phase: it inventories every element in your HTML, searches your DS for matching components, inspects their variants and properties, and maps each element to the best available resolution. This all happens before the first frame is created — so the build starts with the right components, not approximations that need to be fixed later.

Reads are adaptive, not fixed. On a first run, Mimic searches for all common DS patterns upfront — buttons, badges, tabs, inputs, cards, progress bars, and more. It caches everything it finds. Subsequent runs with warm knowledge may need zero reads at all. The system adapts based on what it already knows.

The output is functional, not perfect. Patterns Mimic has never seen before will be resolved with its best judgment. If a DS component can't be used correctly (wrong variant, structural mismatch), Mimic builds a clean primitive with your DS variables instead — it never forces a broken component just to avoid a fallback. These are candidates for correction, not failures.

After the first run, the gaps start closing. Correcting a component teaches Mimic what to use. Repeating a pattern three times makes it permanent. Variable IDs are cached after the first read — no re-collection on subsequent runs.

The learning summary at the end tells you where things stand: how many patterns are now VERIFIED, how many reads were used, and what to correct if anything was off.

When Mimic may stop a build

Mimic is aware of your Figma read budget. If a mid-build situation would require reads that exceed what's available or advisable, Mimic stops and tells you — rather than burning calls on uncertain operations.

This is intentional. A partial build with 3 compliant sections is more useful than an incomplete attempt that exhausts the daily budget on retries. You can continue the next day, or ask Mimic to resume from where it stopped.

Mimic will also stop if a write fails unexpectedly. It does not retry blindly — it classifies the error, applies a fix if one is known, and reports what happened.

Why this matters

Other HTML-to-Figma tools are stateless. Every run starts from scratch: inspect library, resolve patterns, build, done. Run 1 and run 50 cost the same.

Mimic compounds. The longer you use it against the same design system, the fewer reads each run requires, the more consistent the output becomes, and the faster builds complete. It converges on your DS vocabulary instead of re-discovering it every time.

This is the part that can't be replicated by a generic write-back tool. The knowledge belongs to your team's specific DS, your specific naming conventions, and your specific corrections over time.

What you can do

Translate an HTML prototype into Figma

Have an existing HTML file — a prototype, a coded mockup, a landing page? Mimic AI reads it and recreates it inside Figma using your design system instead of hardcoded values.

"Here's an HTML file I built as a prototype. Translate it into Figma on the 'Prototypes' page, artboard 'Onboarding v2'. Use my design system components wherever possible — match the layout, hierarchy, and content."

Build UI from a description

Describe a screen and Claude builds it in Figma — section by section, using your actual published components and design token variables.

"Go to the 'Screens' page in my design file and build a new dashboard on the artboard called 'Overview'. Use the top-nav shell. Include: 4 KPI metric cards, a line chart of weekly activity, a data table with sortable columns, and a donut chart by category."

Target specific library components and variables

Name the components you want, and Claude will find and insert the real library instances.

"Build a settings screen using my Sidebar, Modal/Large, and FormInput components. Use the surface-secondary background, spacing-xl gaps, and text-secondary for label colors."

Quick start

Requirements before you begin: Node.js v20.6+, git, Figma desktop app, Figma Professional plan or above (the free plan cannot publish component libraries or bind variables — the tool's core features require a paid Figma plan). Full Figma setup steps are in Before you start below.

Step 1 — Run the installer:

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

The script clones this repo, runs npm install, asks for your Figma token, and writes the MCP entry to ~/.claude/settings.json.

Step 2 — Install the Figma plugin:

1. Open Figma desktop

2. From the menu bar: Plugins → Development → Import plugin from manifest…

3. Navigate to your ~/mimic-ai/plugin/ folder and select manifest.json

4. Confirm — the plugin now appears under Plugins → Development → Mimic AI

Step 3 — Restart Claude Code, then each session:

1. cd ~/mimic-ai && npm run bridge — keep this terminal open

2. In Figma desktop: Plugins → Development → Mimic AI → Run

3. The plugin badge shows ● ready

Step 4 — Enable your design system in the target file:

1. Open the Figma file where you want Claude to build

2. Open the Assets panel (book icon, left sidebar)

3. Click the Team library icon at the top

4. Find your design system and toggle it on

Without this, Mimic can't find any components and will stop before building anything.

You're ready. Ask Claude to build something — include a Figma link or tell it which file and page to use.

Before you start: Figma requirements

These are the most common reason things break. Work through them in order before running the installer.

The browser version of Figma does not work. The bridge communicates with a Figma plugin over WebSocket, which requires the desktop app.

Download it at: figma.com/downloads

The bridge uses this token to resolve published component keys via the Figma REST API.

1. Open Figma desktop

2. Click your profile picture (top-left corner) → Settings

3. Scroll down to Personal access tokens

4. Click Generate new token

5. Give it a name, e.g. claude-bridge

6. Set an expiration (or no expiration) — read access is sufficient

7. Click Generate token

8. Copy the token immediately — Figma only shows it once

You will be asked to paste it during the install script. It gets saved to the .env file in the repo.

The plugin imports components from your team library. Your design system must live in a separate Figma file and be published as a library.

To publish:

1. Open your design system file in Figma desktop

2. Open the Assets panel (book icon in the left sidebar)

3. Click the Team library icon (grid of squares at the top)

4. Click Publish → confirm

If you add or update a component later, publish again before asking Claude to use it.

Starting from scratch? See docs/GUIDE.md — Part 0 for how to structure a design system file, set up variables (tokens), and create components properly.

Publishing makes the library available to your team. Enabling makes it accessible in a specific file.

1. Open the Figma file where you want Claude to build

2. Open the Assets panel

3. Click the Team library icon

4. Find your design system in the list and toggle it on

You only need to do this once per file.

Publishing component libraries and using variables (design tokens) requires a Figma Professional plan or above — not the Starter/Free plan. This is a hard requirement, not a feature limitation.

What works on the free plan: The bridge can create frames and raw text nodes.

What does not work on the free plan: Component insertion, variable binding, and design token application — the three features that make Mimic AI useful. If you are on a free plan, upgrade before setting up the tool.

Manual setup

Prefer to set things up manually, or want to understand each step? See docs/GUIDE.md for the full walkthrough:

• How to structure your Figma design system

• How to export design tokens so Claude can use them

• How to find and save component keys

• How to build Claude's memory for consistent results across sessions

• Build script patterns and layout rules

To inspect or manually manage the knowledge file, see docs/knowledge-schema.md for the full schema reference — including how to inject known mappings, dismiss recommendations, share knowledge across a team, and reset entries after DS changes.

Available tools

Once the MCP is registered, Claude has access to:

Learning

Build

Edit

Inspect

Every session

1. Start the bridge (keep this terminal open):

cd ~/mimic-ai   # or wherever you installed it
npm run bridge

2. Run the plugin in Figma desktop: Plugins → Development → Mimic AI → Run

The plugin badge shows ● ready when connected.

3. Ask Claude to build something.

How it works

Claude Code  →  MCP server (mcp.js)  →  Bridge server (bridge.js)  →  Figma Plugin  →  Figma document

Two separate channels connect Claude to Figma:

Read channel — official Figma MCP Claude uses Figma's official MCP server to inspect designs, discover node IDs, and read existing content. Read-only.

Write channel — this repo Claude calls tools in mcp.js. Each call is an HTTP POST to bridge.js running locally on your machine. The bridge forwards the instruction to the Figma plugin over WebSocket. The plugin executes it using Figma's Plugin API and returns the new node ID. Claude uses that ID as the parent for the next element.

All variable bindings are real — nodes created this way use your actual design token variables, not hardcoded values. If you update a token in your library and re-publish, the nodes update automatically.

Privacy

This tool runs entirely on your machine. No design data, component names, token values, or HTML content is sent to any external server. The only outbound network call is to the Figma REST API to resolve published component keys using your Personal Access Token — the same call Figma's own plugins make.

Troubleshooting

"Figma plugin is not connected" → The bridge is running but the plugin is not. Go to Figma desktop → Plugins → Development → Mimic AI → Run.

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

"No component key" → The component is not published. Open your design system file → Assets → Team library → Publish.

"object is not extensible" → A frame-only property (like counterAxisSizingMode) is being passed to a text node. See docs/GUIDE.md — Troubleshooting for the full list.

License

MIT