figma-to-code-pixel-perfect

Short version: TLDR.md.

Lets an AI coding agent build pages that match Figma, and prove it:

• You save the design into the repo;
• the agent builds the page
• the agent loops on pixel-check until every mapped element matches Figma within 1px.

Tool	Does
figma-snapshot	Figma → nodes.json + frame PNG/SVG in your repo. Resumable, --dry-run
figma-distill	nodes.json → short readable spec per frame
pixel-check	The check. --tree lists node ids, --coverage finds unmapped parts
pixel-agent/	Plan → build → review pipeline for any coding agent

Node ≥ 22 and Chrome. No npm dependencies.

Step by step

1. Install. Not on npm yet, so npx/pnpm dlx alone won't find it.

npm i -D github:<owner>/figma-to-code-pixel-perfect

2. Token. Figma → Settings → Security → Personal access tokens, scopes file_content:read, library_content:read.

export FIGMA_TOKEN=<token>

3. Frame id. Select a frame (not the page) → Copy link to selection. …/design/<fileKey>/…?node-id=1-2 → file key + node 1:2.

4. design/snapshot.json

{ "fileKey": "<fileKey>", "batches": { "home": { "home-desktop": "1:2" } } }

5. Fetch. View/Collab seats get ~20 requests a month: dry-run first.

npx figma-snapshot --dry-run
npx figma-snapshot       # design/home/nodes.json, frames/home-desktop.png
npx figma-distill        # design/home/specs/home-desktop.md

6. Vectors (icons, illustrations, odd shapes) as SVG: add a batch, fetch again.

"home-assets": { "fetchData": false, "format": "svg", "nodes": { "logo": "1:3" } }

7. Build the page from the spec and PNG. Run it.

npm run dev    # or: python3 -m http.server 3000 -d site

8. Map nodes to selectors in pixel-checks/home.json (example).

npx pixel-check --tree 1:2

{ "path": "/", "screens": [{ "name": "home-desktop", "frame": "1:2", "width": 1440,
  "items": [{ "node": "1:9", "selector": "h1" }, { "node": "1:14", "selector": "a.more" }] }] }

9. Check until PASSED.

npx pixel-check pixel-checks/home.json --coverage
npx pixel-check pixel-checks/home.json

10. Look at tmp/pixel/home-desktop.png next to design/home/frames/home-desktop.png: images, SVG shapes and shadows aren't measured.

Check-file format and rules: docs/workflow.md.

Config

Optional pixel.config.json (or PIXEL_CONFIG=<path>). Example.

Key	Default
designDir	design	snapshot folder
baseUrl	http://localhost:3000	--base overrides
shotDir	tmp/pixel	screenshots
siteChrome	["Header", "Footer"]	instances excluded from page coverage
fontWeights	{}	{ "Family": { "430": 400 } } when font file weight ≠ Figma
tokensCss	—	CSS with --color-*; specs show token names

Env: FIGMA_TOKEN, CHROME_PATH.

Limits

• Not a pixel diff: measured boxes, text, opacity, solid colors, ±1px. Rest is the screenshot review.
• Keep agents off the Figma API; they read the snapshot.
• The snapshot is your client's design: keep it out of public repos.

License

Apache-2.0. Copyright 2026 Mad Devs LLC.