{"_id":"figma-codekit-mcp","_rev":"4-82903a7401fdbc0cf5e1e521849dd8f0","name":"figma-codekit-mcp","dist-tags":{"latest":"0.3.0"},"versions":{"0.0.0-stage":{"name":"figma-codekit-mcp","version":"0.0.0-stage","_id":"figma-codekit-mcp@0.0.0-stage","stub":true,"maintainers":[{"name":"mehmoodqureshi","email":"mehmoodqureshi997@gmail.com"}],"dist":{"shasum":"822ecf6821a85c1110c5e2eae4cbe726bd88a98d","tarball":"https://registry.npmjs.org/figma-codekit-mcp/-/figma-codekit-mcp-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-/Y9CDAdrCX8b0wqNeJAetLAUJu4IHjxiXbSZrCFPf8vfR77BZ/iPAZ17mTw5ucGmPkG1P9mGVIRUwlOkmMVrcw==","signatures":[{"sig":"MEUCIF/tCbeOngh4+qs8IS/PxG9NjipDmvsrPwH8qZqoKtDNAiEA54rgVv1eAz3JyX2BvMisRkwQ0EgxXKVY+Gyrm11Ey/8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":339},"_npmUser":{"name":"mehmoodqureshi","email":"mehmoodqureshi997@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.2.3":{"name":"figma-codekit-mcp","version":"0.2.3","keywords":["mcp","model-context-protocol","mcp-server","figma","figma-to-code","figma-api","design-to-code","pixel-perfect","visual-diff","visual-regression","html","react","playwright","ai-agent","claude","claude-code"],"author":{"name":"Mehmood Ur Rehman Qureshi"},"license":"MIT","_id":"figma-codekit-mcp@0.2.3","maintainers":[{"name":"mehmoodqureshi","email":"mehmoodqureshi997@gmail.com"}],"homepage":"https://github.com/Mehmoodqureshi/figma-codekit-mcp#readme","bugs":{"url":"https://github.com/Mehmoodqureshi/figma-codekit-mcp/issues"},"bin":{"figma-codekit-mcp":"src/mcp/server.js"},"dist":{"shasum":"5acf6573a226302a1020f3d6f795bae1e9d443ea","tarball":"https://registry.npmjs.org/figma-codekit-mcp/-/figma-codekit-mcp-0.2.3.tgz","fileCount":39,"integrity":"sha512-Q/iNE97lMzZArDgXaPf/CAYxLLdiN48MSOykXVpzz1pp/IKjaNc8gLkteuqeLNIpaXs/MbSaCeJvidiGkRBVYA==","signatures":[{"sig":"MEUCIQC8QqAuEpCVynwwAEGd5wR4KgtZxQ3bQfat1h7RHk5oSAIgOUr3XoZK+3+Kf+g5PpOJADd0Fn63hhbWSvMz6Sd2FJo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIBK4DocdxQQG9SbVm/D3ayc1HsVZHBCFCzL2nrgFQU/0AiEA8oxGc6PnUQ18z2ADEdqIvTG/kOgSg+zyylpu9jhBp1g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":262277},"main":"src/index.js","type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.js","./ir":"./src/ir/index.js","./codegen":"./src/codegen/index.js"},"gitHead":"849d2a16accead6ecaf68b50bb6dfb0d088af0dd","mcpName":"io.github.Mehmoodqureshi/figma-codekit-mcp","scripts":{"site":"node site/server.js","test":"node example/mcp-adapter-test.js && node example/doctor-test.js","serve":"node src/mcp/server.js","example":"node example/run-example.js","site:open":"node site/server.js --open","example:ir":"node example/ir-example.js","postinstall":"node scripts/postinstall.js","test:doctor":"node example/doctor-test.js","test:server":"node example/mcp-server-test.js","example:codegen":"node example/codegen-example.js","example:pipeline":"node example/pipeline.js","example:responsive":"node example/responsive-example.js","example:paint-order":"node example/paint-order-example.js","example:element-diff":"node example/element-diff-example.js"},"_npmUser":{"name":"mehmoodqureshi","email":"mehmoodqureshi997@gmail.com"},"repository":{"url":"git+https://github.com/Mehmoodqureshi/figma-codekit-mcp.git","type":"git"},"_npmVersion":"11.9.0","description":"Figma to pixel-perfect code, as an MCP server. Converts a frame to self-contained HTML deterministically, then closes the loop: renders your code in Chromium, pixel-diffs it against the Figma reference, and tells the agent exactly which elements are missi","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^4.4.3","pngjs":"^7.0.0","pixelmatch":"^6.0.0","playwright":"^1.48.0","@anthropic-ai/sdk":"^0.68.0","@modelcontextprotocol/sdk":"^1.32.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/figma-codekit-mcp_0.2.3_1792072743248_0.09268741271092074","host":"s3://npm-registry-packages-npm-production"}},"0.2.4":{"name":"figma-codekit-mcp","version":"0.2.4","keywords":["mcp","model-context-protocol","mcp-server","figma","figma-to-code","figma-api","design-to-code","pixel-perfect","visual-diff","visual-regression","html","react","playwright","ai-agent","claude","claude-code"],"author":{"name":"Mehmood Ur Rehman Qureshi"},"license":"MIT","_id":"figma-codekit-mcp@0.2.4","maintainers":[{"name":"mehmoodqureshi","email":"mehmoodqureshi997@gmail.com"}],"homepage":"https://github.com/Mehmoodqureshi/figma-codekit-mcp#readme","bugs":{"url":"https://github.com/Mehmoodqureshi/figma-codekit-mcp/issues"},"bin":{"figma-codekit-mcp":"src/mcp/server.js"},"dist":{"shasum":"882407a9a309dfc62f3e1de156c6222b02dd26ca","tarball":"https://registry.npmjs.org/figma-codekit-mcp/-/figma-codekit-mcp-0.2.4.tgz","fileCount":39,"integrity":"sha512-+vV9MqjQriOqc/gJk3OhnuUOvVlm+7z7yjVRTGN/JePtGl4HPoM8Osg3FNJIBOXje9X9KkXSVWV/TRL4KZwOtA==","signatures":[{"sig":"MEUCIH0+4d/+ZSfsep5ZKA7VtkZBzbcfdp/bejHB790k8pqxAiEApfsZ/ORhQOqCjh4qXJdOciEj48A5lFkj1MFhXADSapE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCPOscCwbZ8d6fd4mSgHuaKSS88EjavZaes+10YgfdxZgIgU/PQpFRIiwkJ1p/UW7V9IuXpwICy2giZpkO6AxiDtcY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/figma-codekit-mcp@0.2.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":262277},"main":"src/index.js","type":"module","engines":{"node":">=20"},"exports":{".":"./src/index.js","./ir":"./src/ir/index.js","./codegen":"./src/codegen/index.js"},"gitHead":"2460dcc0feeaec7a829f36b9f9a7d66f25c3da62","mcpName":"io.github.Mehmoodqureshi/figma-codekit-mcp","scripts":{"site":"node site/server.js","test":"node example/mcp-adapter-test.js && node example/doctor-test.js","serve":"node src/mcp/server.js","example":"node example/run-example.js","site:open":"node site/server.js --open","example:ir":"node example/ir-example.js","postinstall":"node scripts/postinstall.js","test:doctor":"node example/doctor-test.js","test:server":"node example/mcp-server-test.js","example:codegen":"node example/codegen-example.js","example:pipeline":"node example/pipeline.js","example:responsive":"node example/responsive-example.js","example:paint-order":"node example/paint-order-example.js","example:element-diff":"node example/element-diff-example.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"f630a41e-7d86-4024-a3a2-31a8d734063c"}},"repository":{"url":"git+https://github.com/Mehmoodqureshi/figma-codekit-mcp.git","type":"git"},"_npmVersion":"12.2.0","description":"Figma to pixel-perfect code, as an MCP server. Converts a frame to self-contained HTML deterministically, then closes the loop: renders your code in Chromium, pixel-diffs it against the Figma reference, and tells the agent exactly which elements are missi","directories":{},"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.4.3","pngjs":"^7.0.0","pixelmatch":"^6.0.0","playwright":"^1.48.0","@anthropic-ai/sdk":"^0.68.0","@modelcontextprotocol/sdk":"^1.32.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/figma-codekit-mcp_0.2.4_1792074696795_0.4680133100350776","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"figma-codekit-mcp@0.3.0","bin":{"figma-codekit-mcp":"src/mcp/server.js"},"bugs":{"url":"https://github.com/Mehmoodqureshi/figma-codekit-mcp/issues"},"dist":{"shasum":"b7219e95a4f8ceb337416e0c4c5ed73dee5965c4","tarball":"https://registry.npmjs.org/figma-codekit-mcp/-/figma-codekit-mcp-0.3.0.tgz","fileCount":42,"integrity":"sha512-Yrnh+mKTKjTi55zGgp9WwN42jPSVM4ZDX9pzaUN6loVLExg9OHf3OfBJCXcgQDNv2H0qEGkkcrEG9EMccUUTFw==","signatures":[{"sig":"MEQCIHdArLI0h698gV9CoqiHlto1rlXuqNWEDxxiR8e+/Iq5AiBUxadZetN3ZSTS8E+H3+X1Azj3hfZdRw0eAgnR5ch6rg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDf16BkYhTaKjltqq+15foegdA1AvnEfAQ1Zl9qoJFTugIhAMV7t9sk5EmauwHMTUjp49Cv1GbyEDygeuzurShlBOJn"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/figma-codekit-mcp@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":298706},"main":"src/index.js","name":"figma-codekit-mcp","type":"module","author":{"name":"Mehmood Ur Rehman Qureshi"},"engines":{"node":">=20"},"exports":{".":"./src/index.js","./ir":"./src/ir/index.js","./codegen":"./src/codegen/index.js"},"gitHead":"0459470abd459bb7211df5fbe7b61bff623abec3","license":"MIT","mcpName":"io.github.Mehmoodqureshi/figma-codekit-mcp","scripts":{"site":"node site/server.js","test":"node example/mcp-adapter-test.js && node example/doctor-test.js","serve":"node src/mcp/server.js","example":"node example/run-example.js","site:open":"node site/server.js --open","example:ir":"node example/ir-example.js","postinstall":"node scripts/postinstall.js","test:doctor":"node example/doctor-test.js","test:server":"node example/mcp-server-test.js","example:codegen":"node example/codegen-example.js","example:pipeline":"node example/pipeline.js","example:responsive":"node example/responsive-example.js","example:paint-order":"node example/paint-order-example.js","example:element-diff":"node example/element-diff-example.js"},"version":"0.3.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"f630a41e-7d86-4024-a3a2-31a8d734063c"}},"homepage":"https://github.com/Mehmoodqureshi/figma-codekit-mcp#readme","keywords":["mcp","model-context-protocol","mcp-server","figma","figma-to-code","figma-api","design-to-code","pixel-perfect","visual-diff","visual-regression","html","react","playwright","ai-agent","claude","claude-code","design-qa","pixel-diff","verify","tailwind","design-tokens","dtcg","nextjs","cursor"],"repository":{"url":"git+https://github.com/Mehmoodqureshi/figma-codekit-mcp.git","type":"git"},"_npmVersion":"12.2.2","description":"Figma to pixel-verified code, as an MCP server. Deterministic Figma frame → HTML / React / Next.js (optionally Tailwind) with design tokens and image files, then renders it in Chromium and pixel-diffs it against the Figma reference — or verifies your own ","directories":{},"maintainers":[{"name":"mehmoodqureshi","email":"mehmoodqureshi997@gmail.com"}],"_nodeVersion":"24.22.2","dependencies":{"zod":"^4.6.7","pngjs":"^7.0.0","pixelmatch":"^6.0.0","playwright":"^1.65.0","@anthropic-ai/sdk":"^1.6.0","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/figma-codekit-mcp_0.3.0_1793914731797_0.7997091276073967"}}},"time":{"created":"2026-10-15T13:56:55.523Z","modified":"2026-11-05T21:38:52.288Z","0.0.0-stage":"2026-10-15T13:56:55.523Z","0.2.3":"2026-10-15T13:59:03.412Z","0.2.4":"2026-10-15T14:31:36.896Z","0.3.0":"2026-11-05T21:38:51.928Z"},"bugs":{"url":"https://github.com/Mehmoodqureshi/figma-codekit-mcp/issues"},"author":{"name":"Mehmood Ur Rehman Qureshi"},"license":"MIT","homepage":"https://github.com/Mehmoodqureshi/figma-codekit-mcp#readme","keywords":["mcp","model-context-protocol","mcp-server","figma","figma-to-code","figma-api","design-to-code","pixel-perfect","visual-diff","visual-regression","html","react","playwright","ai-agent","claude","claude-code","design-qa","pixel-diff","verify","tailwind","design-tokens","dtcg","nextjs","cursor"],"repository":{"url":"git+https://github.com/Mehmoodqureshi/figma-codekit-mcp.git","type":"git"},"description":"Figma to pixel-verified code, as an MCP server. Deterministic Figma frame → HTML / React / Next.js (optionally Tailwind) with design tokens and image files, then renders it in Chromium and pixel-diffs it against the Figma reference — or verifies your own ","maintainers":[{"name":"mehmoodqureshi","email":"mehmoodqureshi997@gmail.com"}],"readme":"# figma-codekit-mcp\n\n**Figma → code that is actually checked against the design.** The pixel-diff\nverifier for Figma-to-code: it renders the output and diffs it against the frame\nuntil it converges — and it can verify *your own running app* the same way, so it\nworks alongside Figma's official MCP server or Framelink rather than replacing them.\n\nMost Figma-to-code tools stop at the moment of generation: they hand you JSX and\nwalk away. Nobody ever renders the output and compares it to the frame, so the\nresult stalls at \"90% there\" and you spend the afternoon nudging padding by eye.\n\nThis MCP server closes that loop. It converts a frame to self-contained HTML\n**deterministically** (no LLM, no hallucinated layout), then renders your code in\nChromium, pixel-diffs it against the Figma reference, measures every element's\nbox, and tells the agent exactly what is missing or misplaced. The agent edits,\ncalls verify again, and repeats until the diff is at the anti-aliasing floor.\n\n<table>\n<tr>\n<th align=\"center\">Figma reference</th>\n<th align=\"center\">First pass — 5.18% off</th>\n<th align=\"center\">Pixel diff</th>\n<th align=\"center\">Converged — 0.00%</th>\n</tr>\n<tr>\n<td><img src=\"docs/demo-reference.png\" width=\"220\" alt=\"The Figma frame, used as ground truth\"></td>\n<td><img src=\"docs/demo-render-first.png\" width=\"220\" alt=\"First generated pass: grey badge, small title, missing button\"></td>\n<td><img src=\"docs/demo-diff-first.png\" width=\"220\" alt=\"Pixel diff with mismatched regions highlighted\"></td>\n<td><img src=\"docs/demo-render-final.png\" width=\"220\" alt=\"After three verify iterations, pixel-identical to the reference\"></td>\n</tr>\n</table>\n\nThose are real artifacts from `npm run example`, which runs the loop end to end\nwith no API key. The `generate` callback in that demo is a *scripted* stand-in\nfor an LLM, so it shows the loop mechanics honestly — the measuring is real, the\n\"model\" is not.\n\n## Why the verify step matters\n\nA Figma node tree tells you what the designer *declared*. It does not tell you\nwhat a browser will *do* with your CSS. Those diverge constantly — a flex gap\nthat collapses, a font that falls back, an absolute child that escapes its\nparent. The only way to know is to render it and look.\n\n`figma_verify` gives the agent three independent signals per pass:\n\n- **Pixel diff** — the overall mismatch ratio plus the worst regions, so it knows\n  *how* wrong and *where*.\n- **Element bounding-box IoU** — every IR node is tagged `data-ir-id`, measured in\n  the live DOM, and matched against its Figma box. This is what turns \"the\n  bottom-left looks off\" into \"the CTA button is missing\" or \"the price label is\n  40px too low\".\n- **Paint order and clipping** — Figma lists children back-to-front, so a node's\n  pre-order index *is* its paint order; `elementsFromPoint` over a sample grid\n  gives the rendered order wherever two elements actually overlap. This catches\n  the class of bug the other two signals are blind to by construction: elements\n  present, in exactly the right box, stacked the wrong way round — or cut off by\n  an ancestor's `overflow` where the design lets them overhang. Neither moves a\n  box, and on a tall frame neither moves the diff ratio much, but a decorative\n  overlay drawn over a photo instead of under it is the first thing a person\n  sees. Reported as `WRONG STACKING` / `OVER-CLIPPED`, and reported even when the\n  pixel diff has converged.\n\n## Tools\n\n| Tool | What it does | Network |\n|---|---|---|\n| `figma_convert` | Fetch a frame → HTML + `ir.json` + images as files in `assets/` (or data URIs with `inlineAssets: true`) + `reference.png` + design tokens (`tokens.json` in W3C DTCG format, `tokens.css`, a Tailwind v4 `tailwind.theme.css`). Optional `react: true` (component + the `components/` it imports), `next: true` (a runnable App Router project) and `tailwind: true` (React/Next.js output as Tailwind classes), plus a responsive variant. | Figma API (cached) |\n| `figma_verify` | Render HTML in Chromium, pixel-diff vs the reference, IoU-check every element, check paint order and clipping, return targeted fix instructions. Pass `url` (and optionally `selector`) to verify a **running page instead** — your own app at `http://localhost:3000`, in any framework — against the frame. | none (or your dev server) |\n| `figma_inspect` | Print the IR as an indented outline (role, box, layout, text, tokens), filterable — read the structure without dumping raw Figma JSON into context. | none |\n\n### Responsive output depends on what the design actually declares\n\n`responsive: true` reads Figma's sizing intent — FILL becomes `flex`/`100%`, HUG becomes\n`fit-content`, FIXED keeps its px. That only exists where the designer used Auto Layout.\n\nA frame with **no** Auto Layout on the root is a canvas: every child is `position:absolute` at a\ncoordinate on a 1440px artboard. There is nothing to relax, so making the root `width:100%` does not\nreflow it — the children stay pinned at their canvas coordinates and the right-hand side disappears\nunder `overflow:hidden`. That reads exactly like a page breaking when you zoom.\n\nFor those frames the converter keeps the exact canvas and scales it to the viewport instead, so the\ndesign stays intact at every width and zoom level (down to 0.5x, after which the page scrolls).\n`figma_convert` tells you which strategy it used. If you want real reflow rather than proportional\nscaling, add Auto Layout in Figma — that is the signal the converter needs.\n\nEvery tool returns **file paths and numbers, never large blobs**. A converted\nframe is often 100+ KB of HTML; pushing that through a tool result would burn the\nagent's context for nothing. The agent reads and edits the files directly.\n\nFigma responses are cached per frame, so after the first `figma_convert` the\nwhole loop runs offline and free — including when you are rate-limited.\n\n## Quick start\n\nYou need a Figma personal access token: **Figma → Settings → Security → Personal\naccess tokens**, scope `File content: read`.\n\n```bash\nexport FIGMA_TOKEN=figd_REPLACE_WITH_YOUR_TOKEN\n```\n\nAdd it to Claude Code:\n\n```bash\nclaude mcp add figma --env FIGMA_TOKEN=$FIGMA_TOKEN -- npx -y figma-codekit-mcp@latest\n```\n\nOr for any MCP host that reads a JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"figma\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"figma-codekit-mcp@latest\"],\n      \"env\": { \"FIGMA_TOKEN\": \"figd_REPLACE_WITH_YOUR_TOKEN\" }\n    }\n  }\n}\n```\n\nThen, in the agent: copy a frame link out of Figma (right-click the frame →\n**Copy link to selection**) and say *\"convert this frame and verify it until it\nconverges.\"*\n\n### Check your setup\n\n```bash\nFIGMA_TOKEN=$FIGMA_TOKEN npx -y figma-codekit-mcp@latest --check\n```\n\nIt checks Node, whether a token was found (and where, never its value), whether\nFigma accepts it, and whether the Chromium `figma_verify` renders in is\ninstalled, then prints `READY` or what to fix. Exit code 0 means all three tools\nwill work. If Chromium is missing (a skipped download, or CI), install it with\n`npx -y figma-codekit-mcp@latest --install-browser`.\n\n### Windows\n\n`npx` resolves to `npx.cmd`, which some MCP hosts cannot spawn directly. If the\nserver fails to start, point at the shim explicitly:\n\n```json\n{\n  \"command\": \"cmd\",\n  \"args\": [\"/c\", \"npx\", \"-y\", \"figma-codekit-mcp@latest\"]\n}\n```\n\n## The loop, concretely\n\n```\nfigma_convert  →  generated.html, reference.png, ir.json   (deterministic, no LLM)\n      ↓\nfigma_verify   →  \"NOT CONVERGED — 4.93% of pixels differ.\n                   Elements: 22/26 match — 1 missing, 3 misplaced.\n                   MISSING: button 'Get started'\n                   MISPLACED: h1 'Pricing plan' — 6px too high\"\n      ↓\n  agent edits generated.html\n      ↓\nfigma_verify   →  \"CONVERGED — 0.31% of pixels differ (threshold 2.00%).\"\n```\n\nThe refine loop runs **through the calling agent**, not through an LLM inside the\nserver. That means no `ANTHROPIC_API_KEY`, no second model billing, and the agent\nkeeps full context on what it already tried. A headless refine loop\n(`src/refine/`) still exists for library use.\n\n## Watch the loop without an agent\n\nThe same pipeline has a one-page local web front end, split in two: a chat on the\nleft, the generated app on the right. You send a frame link, it asks what to\nbuild — HTML, React or Next.js; exact or responsive — and then converts, renders\nand diffs in front of you. The right pane carries the running app, its source\nfiles, the verify numbers and the pixel diff.\n\n```bash\nnpm run site        # http://localhost:5173\n```\n\nIt uses the same `.figma-token` and the same `.figma-cache/`, so a frame you have\nalready converted re-runs offline in about a second. Useful for checking a frame\nconverts cleanly before pointing an agent at it — and for showing someone what\n\"verified against the design\" means rather than describing it. Details in\n[`site/README.md`](site/README.md).\n\n## Configuration\n\n| Variable | Purpose |\n|---|---|\n| `FIGMA_TOKEN` | Required. Also read from a `.figma-token` file in your project directory. `FIGMA_API_KEY` is accepted as an alias. |\n| `FIGMA_MCP_CACHE_DIR` | Where converted frames are cached. Defaults to `.figma-cache/` in the directory the server is started from. |\n| `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` | Optional, headless refine loop only. The MCP server never calls an LLM. |\n| `FIGMA_MCP_SKIP_BROWSER_DOWNLOAD=1` | Skip the Chromium download on install. `figma_convert` and `figma_inspect` still work; `figma_verify` will not. |\n\nSee [`.env.example`](.env.example). Add `.figma-cache/` to your project's\n`.gitignore` — a cached frame keeps the original bitmaps and can be tens of megabytes.\n\n`FIGMA_FILE_TIMEOUT_MS` (default `90000`) caps how long `figma_convert` waits for\nFigma's whole-file download, which it falls back to when the per-node endpoint is\nrate-limited. When Figma will not answer, the tool says so within that time and,\nif the frame is already cached anywhere, builds from the cached copy and marks the\nresult **STALE CACHE** instead of hanging.\n\n### Verify your own app, not just the generated HTML\n\n```text\nfigma_convert  url=<frame link>                      → .figma-cache/<frame>/ (reference.png)\nfigma_verify   dir=<that dir>  url=http://localhost:3000/pricing  selector=\"#plans\"\n```\n\nBuild the page however you like — Figma's official MCP server, Framelink, by hand —\nthen point `figma_verify` at it. It screenshots the page (or just the selected\nelement) at the frame's size and pixel-diffs it against Figma. Element-box and\nlayering checks need the converter's `data-ir-id` markers, so for a URL only the\npixel diff runs.\n\n## What it does not do\n\nBeing straight about the edges, because they are Figma's, not bugs:\n\n- **Token names are derived, not designed, unless you are on Enterprise.** The\n  Figma Variables REST API is Enterprise-only. Without it the converter still\n  collects every colour, font, size and spacing value into `tokens.json` /\n  `tokens.css` / `tailwind.theme.css`, but names them after the value\n  (`--color-c8960c`) because it cannot know intent. Rename them in your theme.\n- **Figma rate-limits by cost.** A very large file fetched repeatedly can lock a\n  token out for hours (free accounts hit this sooner). Cached frames keep working\n  offline; `figma_convert` tells you when the limit lifts.\n- **Component *prop* bindings need Code Connect.** Components are matched by name\n  and reported, but the API does not expose which instance prop drove which\n  value.\n- **The diff has a floor.** Anti-aliasing and font hinting keep the ratio around\n  0.5–1.5% even on a perfect match. `threshold` defaults to 2% for that reason —\n  chasing 0 is chasing rendering noise.\n- **One frame at a time.** No whole-file crawling, by design: it keeps token\n  spend and Figma rate-limit pressure predictable.\n\n## Use it as a library\n\nThe verify loop is framework-agnostic and does not need the MCP layer:\n\n```js\nimport { verifyLoop } from 'figma-codekit-mcp';\nimport fs from 'node:fs';\n\nconst result = await verifyLoop({\n  initialCode: firstPassHtml,\n  referencePng: fs.readFileSync('frame.png'),\n  ir,                                   // enables element-level IoU findings\n  viewport: { width: 1440, height: 900, deviceScaleFactor: 2 },\n  threshold: 0.02,\n  maxIterations: 5,\n  generate: async ({ code, correction }) => callYourModel({ code, correction }),\n});\n\nconsole.log(result.converged, result.diffRatio);\nfs.writeFileSync('diff.png', result.bestDiffPng);\n```\n\nThe loop keeps the **best** iteration seen, so a later regression never makes the\nresult worse. To verify a React component on a dev server instead of an HTML\nstring, pass `render: () => renderUrl('http://localhost:3000/preview', viewport)`.\n\n## Develop\n\n```bash\ngit clone https://github.com/Mehmoodqureshi/figma-codekit-mcp.git\ncd figma-codekit-mcp\nnpm install          # also downloads Chromium via postinstall\nnpm test             # full chain against a mocked Figma API — no token, no network\nnpm run example      # the verify loop end to end; watch the diff ratio fall\nnpm run serve        # run the MCP server on stdio\n```\n\n| Path | Role |\n|---|---|\n| `src/mcp/` | MCP server, Figma REST source, frame loading, asset export |\n| `src/ir/` | Figma node tree → normalized IR (roles, boxes, auto-layout, style, tokens) |\n| `src/codegen/` | IR → HTML / React / CSS |\n| `src/render.js` `src/diff.js` `src/elementDiff.js` `src/paintOrder.js` | Playwright render, pixel diff, bounding-box IoU, z-order + clipping |\n| `src/correction.js` `src/verifyLoop.js` | Turn a diff into fix instructions; drive the loop |\n| `src/refine/` | Optional headless LLM refiners (Anthropic, Gemini) |\n| `example/` | Runnable demos and the offline test suite |\n\n`example/` doubles as the test suite — `npm test` runs the full\n`loadFrame → figmaToIR → generateHtml` chain against a mocked Figma REST API,\nincluding rate-limit handling and rotation/mirror transforms. No token, no\nnetwork, no browser, so it runs in CI on every push.\n\n## Upgrading from an earlier package name\n\nReplace the package in your MCP client command with `npx -y figma-codekit-mcp@latest`. Existing environment settings and saved data remain compatible.\n\n## Related\n\n- [MCP Browser Extension](https://mcp-browser-extension.com) ([mcp-browser-extension](https://github.com/Mehmoodqureshi/mcp-browser-extension)): let Claude, Cursor or any MCP agent use the Chrome you are already logged into, with a deny-all domain allowlist.\n\n## License\n\nMIT © Mehmood Ur Rehman Qureshi\n","readmeFilename":"README.md"}