DEV Community: @planetabhi

Invite an AI to Look Upon Your Designs

@planetabhi — Sat, 22 Aug 2026 06:55:16 +0000

Who will look upon your work before the world does? Let it be an AI, quietly, inside Figma, reading each frame and pinning its honest thoughts to the very place they belong.

Let Claude, GPT, Gemini, or any AI model wander through your designs, offer its quiet counsel, and leave its thoughts pinned upon the Figma canvas.

A gentle word before you begin. This hands an AI model real power over your Figma files. It may leave comments upon the canvas, and take them away again. So begin where nothing is precious, on a blank, new, or draft file, where a mistake carries no sorrow. Try a few reviews, watch how the assistant speaks, and learn the prompts that answer you kindly. When trust has grown between you, carry it to the files that matter.

The purely local Figma MCP Server with full Figma REST API coverage opens a door through which any AI assistant that speaks MCP may come and look upon your designs. It keeps company with clients such as GitHub Copilot in VS Code, Claude Desktop, and Cursor, and with models such as Claude, GPT, and Gemini. The assistant reads your work, offers its honest reflection, and pins its comments to the canvas. And because it runs upon your own machine, your Figma token never wanders from your hands.

What you can do with it

Speak to your assistant in plain, unhurried language, and it can:

Look upon your frames. It renders a screenshot of any screen, then reads the layers and components beneath when it needs to see closer.
Weigh the design. It's hierarchy, spacing, contrast, alignment, and consistency.
Hold the work against your design system, it's tokens and components.
Leave its feedback in Figma, pinned to the very frame it speaks of.
Move through the comments already there. It reads every open thread, gathers them, sets them in order of urgency, and turns them into a clear list of things to do.

Before you start

Three small things must be gathered first:

An AI client that supports MCP, such as GitHub Copilot in VS Code, Claude Desktop, or Cursor.
Bun.sh installed. It runs the server.
A Figma personal access token, which you create in Step 1.

With these three in hand, the path ahead is short.

Step 01: Get your Figma token

In Figma, go to Settings → Security → Personal access tokens.
Name it, and check all items under the Users and Files scopes. Files lets the assistant read your designs and post comments; Users lets it identify who is commenting. These are the minimum scopes it needs.
Click Generate token.
Copy it now, for Figma will show it only this once. Guard it as you would a password.

Step 02: Connect the server to your AI client

Point your client toward the server but once, and offer it your token. Most clients will keep it safe in your system's secret storage, never lying bare in a plain file.

VS Code (GitHub Copilot)

Open the folder you want to work in. Any project root or test folder works.
Inside it, create a folder named .vscode, and inside that a file named mcp.json.
Paste this into mcp.json and save:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "figma-api-key",
      "description": "Figma API Key",
      "password": true
    }
  ],
  "servers": {
    "figma": {
      "command": "bunx",
      "args": ["figma-mcp-server"],
      "env": {
        "FIGMA_API_KEY": "${input:figma-api-key}"
      }
    }
  }
}

Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows) and run MCP: List Servers.
Pick figma, then Start Server.
Paste the token from Step 01 when prompted. VS Code stores it in your OS secret storage: macOS Keychain, Credential Manager on Windows, or your keyring on Linux.

Claude Desktop, Cursor, and other clients

Add the same server to your client's MCP config:

{
  "mcpServers": {
    "figma": {
      "command": "bunx",
      "args": ["figma-mcp-server"],
      "env": {
        "FIGMA_API_KEY": "your_figma_api_key_here"
      }
    }
  }
}

This block keeps the token in plain sight, so keep this file away from version control. Restart the client, then see that the Figma server has joined you in its MCP settings. Seek the mode that lets the assistant reach for outside tools; each client calls it by a different name, be it agent, tools, or MCP.

Once the bond is made, the server brings forth the Figma tools. In VS Code, the Output console shows the connection alive and names the tools it may use, such as reading frames and leaving comments:

[info] Connection state: Starting
[info] Connection state: Running
[info] Discovered Figma tools

Step 03: Grab a frame link

To point the assistant at a single frame is swifter and more sure than to hand it the whole file. It attends to what you care for, rather than wandering through everything.

In Figma, right-click the frame and choose Copy/Paste as → Copy link to selection. You get a URL like this:

figma.com/design/AbCdEf123456/Project?node-id=42-1337
                 ^^^^^^^^^^^^                 ^^^^^^^
                 file key                     frame

Paste that link into your prompt just as it is. The file key tells the assistant which file to enter, and the node-id which frame to seek. To review several frames, offer a link for each, or point the assistant at a whole page and ask it to consider every top-level frame upon it.

A word on cost and limits. Every review spends model tokens, and the Figma API sets a limit on how often you may ask within a span of time. To review whole files, or many frames at once, wears through both the sooner. Begin with a few frames, and should you meet a limit, wait a little while and ask for less.

Step 04: Ask for a review

First, give the assistant its bearings. Tell it the purpose of the screen, the device it is made for, and the people who will meet it. A frame seen alone, without its story, will be faulted for what was meant all along, its states, its breakpoints.

Open your AI client and let it reach for tools or act as an agent, so it may call upon the Figma tools. In VS Code, open Copilot Chat and turn it to Agent mode. Then paste the frame link and tell it what to look for:

Review this frame: https://www.figma.com/design/AbCdEf123456/Project?node-id=42-1337. Check spacing consistency, color contrast, and visual hierarchy. List the top issues before posting anything.

The assistant enters the frame, considers it, and returns a gathered list. It will name the very components and layers, not merely "the blue button somewhere."

Should it say it cannot reach the frame, look again at the token scopes from Step 1, and be sure the link leads to a frame you yourself may open.

Step 05: Post it to the canvas

When the notes sit right with you, send them home to Figma:

Post each issue as a comment, pinned to the frame it's about. Suffix every comment with "(Added by Claude)" so we know which model left it.

Ask the assistant to sign what it leaves (say, "Added by Claude" or "Added by Gemini"). This matters most when many hands, or many models, tend the same file: every word stays known by its author. Choose a prefix or a suffix, and hold to it.

The comments settle where the trouble lies. Your companions open Figma and find the review pinned upon the work itself, marked with the name of whoever wrote it.

When not to use it

The assistant looks upon a rendered image and the data of the layers. It cannot feel motion, nor follow a prototype's flow, nor know the touch of real use; and it does not stand in place of testing with people, or of true research.

Why it's worth it

Set it up but once, and a design review becomes a single sentence spoken to your assistant. The reviews keep their steady voice across many designers, they catch the small faults of spacing and contrast before the handoff, and they lighten the rounds of review. The same quiet helper can later read your design tokens, weigh your components, or trace a file's history, all through plain conversation.

When your work is finished. Take the key from your config, then remove the token in Figma under Settings → Security. And so it is fully revoked.

Explore Figma MCP Server ↗

Design Diff, a Visual Feedback Loop for Coding Agents

@planetabhi — Sat, 22 Aug 2026 06:33:18 +0000

A coding agent can write the markup, wire the styles, and ship a page in seconds. It can even look at that page. What it cannot do is measure it against the design, pixel for pixel. Glancing at a screenshot, it will not catch that the heading sits a few pixels too low, that the color has cooled by a shade, that the font quietly failed to load. It builds by eye, and the page drifts from the design with nothing exact to catch it.

Design Diff gives it that measure. It lays the design over a screenshot of the live page at the exact same pixel size, then returns one number for what matched and the box around what did not. Call it, read the score, fix what the box points at, call it again. That loop runs until the page matches the design, and no one has to be watching.

It is built agent-first, a command and a library that speak plain JSON, so any agent or script can drive it. The same signal serves people just as well, from developers closing a handoff to design engineers building a system to designers who want proof rather than a promise.

Install

It runs on Bun and needs no global install, since bunx fetches and runs it in one step. The first run downloads Chromium once. Every run after that is instant.

Quickstart

You have a running page and a PNG of the design. Point the tool at both and let them stand side by side.

bunx design-diff http://localhost:3000 --png home.png --open

It answers in three ways.

A short report in the terminal.
An interactive page in the browser where you lay one image over the other.
And a folder of artifacts, written to .design-diff by default, one timestamped run at a time, or wherever you point --out.

An agent skips the browser and reads the JSON, but the loop is the same, question to answer and back again.

DESIGN DIFF
────────────────────────

Visual match    92.4%

Diff bounds
x=0..1440
y=812..980
page coverage=17.1%

Ninety-two percent of the pixels line up. The rest is gathered near the foot of the frame, between the lines it names. You know where to look before you even open the report, and knowing where the trouble sits is half the fix.

Every flag appears in context throughout this piece, and design-diff --help lists them all.

How measurement works

The loop only works if the number can be trusted, and three things make it so. A shared frame of reference, a page caught at the right moment, and a score you can read at a glance.

One frame of reference

Measurement needs a common ground. Two things can be compared only on the same scale, so the design sets the size and the page is captured at that exact width and height. Laid on one measure, they line up point for point, with no room for a false reading.

Caught at the right moment

Design Diff does not capture in haste. It waits for the fonts to load, for the images to arrive, for the network to settle, and it turns off animation and the blinking caret. Most false diffs come from catching a page mid-render. If the fonts still are not ready, it says so in the output instead of handing you a bad score in silence. For an agent looping toward a match, this is what keeps the signal honest. The number moves only when the page truly changed, not when it was caught too early.

A score you can read

Every run prints three measures and writes them to metrics.json in the run folder.

Metric	What it tells you
Visual match	How many pixels line up. The headline score.
Diff bounds	The box enclosing every changed pixel, in CSS pixels. A tight box means one component is off. A box spanning the page points at a layout, viewport, or font problem.
Page coverage	How much of the page that box spans. Tells a local issue from a global one.

The shape of the diff is the diagnosis. A small box on a button is a mistaken color. A box that spans the page is a font that never loaded or a viewport that does not match. Read the shape, not the number alone. The number says something is wrong, the shape says what. For an agent this is a ready-made reward signal. A match percentage to climb, and the diff bounds to point the next edit at.

{
  "url": "http://localhost:3000",
  "matchPercent": 92.4,
  "diffPercent": 7.6,
  "changedPixels": 107251,
  "totalPixels": 1411200,
  "coveragePercent": 17.1,
  "diffBounds": { "x": 0, "y": 812, "width": 1440, "height": 168 },
  "readiness": { "fontsReady": true, "imagesComplete": true },
  "paths": {
    "design": ".design-diff/2026-08-16T14-22-09-482Z/design.png",
    "page": ".design-diff/2026-08-16T14-22-09-482Z/dom.png",
    "heatmap": ".design-diff/2026-08-16T14-22-09-482Z/heatmap.png",
    "overlay": ".design-diff/2026-08-16T14-22-09-482Z/overlay.html",
    "metrics": ".design-diff/2026-08-16T14-22-09-482Z/metrics.json"
  }
}

Working with real designs and real pages

Real work is messier than a clean mockup against a static page. Design Diff meets it where it is, whether the source of truth lives in Figma, the page carries content that was always going to change, loads late, sits behind a login, or exists only as a screenshot on disk.

Straight from Figma

No manual export. Give it a file key and a frame id and it fetches the frame size and PNG straight from the Figma API.

export DESIGN_DIFF_FIGMA_TOKEN=figd_your_token
bunx design-diff http://localhost:3000 --file abc123 --frame 10-2 --open

The frame id is the one in the frame URL, like 10-2. A read-only token is enough. This is the closest thing to a live handoff. The designer moves a component, you run it again, you see the drift at once. An agent can aim straight at a Figma frame as its target and never touch a local file.

Mask what is meant to change

Real pages carry things that were always going to change. An avatar, a timestamp, a live counter, a random hero image. Counting those as faults is a quarrel with the nature of the page. Mask them so they never count.

By a fixed rectangle, in CSS pixels, repeated as often as you like.

bunx design-diff http://localhost:3000 --png home.png \
  --ignore 24,24,48,48 --ignore 0,900,1440,120

Or by CSS selector, which is wiser when the region moves or resizes between runs. Every element that matches is masked by its own live bounding box.

bunx design-diff http://localhost:3000 --png home.png \
  --ignore-selector "[data-dynamic], time, .avatar"

Masking by selector is what turns a flaky score into a steady one. It silences the noise that was never a real difference. For an agent iterating toward 100, a stable score is everything, since it needs the number to reflect its own edits and nothing else.

Wait for readiness

Some pages wake late, or fetch their hero after a round-trip. Hold the capture until a chosen selector appears. If the selector never shows within fifteen seconds, it fails loudly rather than quietly handing you a bad screenshot.

bunx design-diff http://localhost:3000 --png home.png --wait-for ".hero-loaded"

Pages behind a login

Save a session once with Playwright, then hand it over. No credentials ever touch the tool itself. The saved file holds only cookies and local storage. When it expires, make it again.

bunx playwright codegen --save-storage=auth.json https://your-app/login
# log in in the window, then close it
bunx design-diff https://your-app/dashboard --png dash.png --auth auth.json --open

From two images

Sometimes both images already sit on disk and there is no page to visit. Let the browser sleep and lay the two side by side.

bunx design-diff --actual screenshot.png --png design.png --json

This is the fast path an agent uses in a tight loop. It has already captured the page by its own means, so Design Diff only diffs the two files and launches no browser at all. It works offline, in tests, and in sandboxes. With no live page there is no waiting and no selector masking, and scale is ignored since there is no screen to answer to, so the bounds come back in plain image pixels. Everything else is the same.

Outputs for agents and humans

The same run answers two very different readers. A machine wants a number and a box. A person wants to see it. Design Diff gives each what it needs from one pass.

The interactive report

The HTML report is not a static picture. It is a tool for holding two images as one.

A reveal slider wipes between the design and the page. Drag the handle to move the seam across the frame.
An opacity slider fades the design onto the page so a small shift shows itself.
A heatmap lights up every changed pixel so nothing hides.
A bounds box outlines the changed region so your eye goes straight to it.

It is retina-safe. When your export is drawn at twice the size, pass --scale 2 and it keeps the measure honest.

A shareable image

The HTML report is good in front of you, but it cannot travel into a pull request comment. Pass --annotate and it draws the diff box onto the page screenshot itself.

bunx design-diff http://localhost:3000 --png home.png --annotate

No browser needed to view it. Drop it into a review, a Slack thread, a CI artifact. Nothing is written when there is no diff, so an annotated file always means there is something to look at.

JSON and the CI gate

Agents and pipelines want the numbers, not the page. --json prints only the metrics object to stdout, so a script or an agent reads it with no parsing. --fail-under sets the bar. If the visual match falls below it, the process exits 1 and the build goes red.

bunx design-diff http://localhost:3000 --png home.png --json --fail-under 98

This is the agent contract. Read the JSON, act on matchPercent and diffBounds, run again, and stop when the score is high enough.

One thing to keep straight. --fail-under is a percentage measured against the visual match. It is not --threshold, which is the per-pixel color sensitivity. One keeps the gate, the other tunes how strict each pixel comparison is. When you weigh many pages, or the same page again and again, pass --no-overlay to skip the HTML and keep only the metrics.

Using it programmatically

The CLI is a convenience. The loop really lives in the library, one function you can call as fast as you can edit.

The function

The CLI is a thin wrapper over one function that returns everything it computed, along with the path to every artifact.

import { designDiff } from "design-diff"

const result = await designDiff({
  url: "http://localhost:3000", // or actual: "screenshot.png" for image mode
  design: "home.png",           // or { fileKey, frameId }
  scale: 1,
  threshold: 0.1,
  ignore: [{ selector: "[data-dynamic]" }, { x: 24, y: 24, width: 48, height: 48 }],
  waitFor: ".hero-loaded",
})

if (result.matchPercent < 98) process.exit(1)

You get back matchPercent, diffPercent, changedPixels, totalPixels, coveragePercent, diffBounds, the readiness signals, and the paths to the design, page, heatmap, overlay, annotated image, and metrics. The same object it writes to metrics.json, with nothing useful thrown away. An agent reads matchPercent to know how close it is and diffBounds to know where to edit next, then calls the function again.

Reuse the browser

Checking a whole app? Launch Chromium once and pass it into every call. It is a real speed win when a suite or an agent runs the tool over and over.

import { designDiff, launchBrowser } from "design-diff"

const browser = await launchBrowser()
try {
  for (const page of pages) {
    const r = await designDiff({ url: page.url, design: page.design, browser })
    console.log(page.url, r.matchPercent)
  }
} finally {
  await browser.close()
}

The honest limits

Design Diff compares pixels, not perception, so read the score as a guide and not a verdict. Anti-aliasing and font rendering vary across machines, so a real page against a design export settles just short of a clean hundred even when it looks right. Choose a threshold rather than chase the last point. The design and the page must be the same size, since a large mismatch is a hard error by design. And a high score is necessary but not sufficient, because a shifted component can still hide inside it. The diff box and a human eye stay the final check.

The bottom line

Visual regression tools compare an app to its own past, which catches change no one intended. Design Diff compares the app to the design, which catches the thing that matters at handoff, the gap between what was drawn and what was built.

It is small and asks no allegiance to a service. Most tools in this space are built for a person to look at a report. This one is built to be read by a machine and acted on in a loop, so an agent can drive the page toward the design on its own, and it still hands a person a picture that ends the argument. Point it at your page, read the box, and close the gap.

Explore the Design Diff ↗