DEV Community: abhi

Structuring Variables in Figma

abhi — Sat, 29 Aug 2026 08:04:14 +0000

Building a scalable UI library in Figma starts with thoughtful organization of variables. As projects grow, managing primitives, semantics, and themes without proper structure can quickly become overwhelming.

This guide explores a clear, implementation-aligned approach to structuring variables by purpose, from foundational values to reusable design tokens and dynamic content. This approach reduces redundancy, streamlines updates, and maintains consistency across components and abstractions.

Understanding variables in Figma

Before diving into structuring, it helps to understand what variables are and why they matter. At their core, variables in Figma store reusable values that can be applied to various design properties and prototyping actions. They're incredibly useful for saving time and effort when creating designs, managing design systems, and building complex prototyping flows.

When designing a button, instead of manually setting the color, padding, and border radius each time, variables store these values for reuse. When the button's color needs to change across an organization's projects, updating the variable once applies the change everywhere. This capability makes variables essential for maintaining design consistency.

Types of variables

Figma offers six types of variables, each serving a unique purpose:

Type	Defined by
`Color`	Solid fills	Solid values like #000000. Used for theming and organizing palette.
`Number`	Number values	Hold values like 16. Used for responsive, language, and text styles.
`String`	Text strings	Use text (like 'Namaste') for language, text styles, and prototype variants.
`Boolean`	True, false values	Boolean variables use true/false. Used to show/hide layers.
`Timing`	Number values	Duration in milliseconds.
`Easing`	Number values	Easing curve or spring animation.

Collections and groups

Figma provides collections and groups to help keep your variables organized:

Both collections and groups make variables more organized and easier to find.
A collection brings together related variables and modes, making organization more intuitive.
Within collections, you can further organize variables by placing them into logical groups.

Variables vs. styles

Variables define reusable values like colors and spacing, while styles are predefined sets of design properties, such as text formatting and effects.
Unlike styles, variables enable dynamic design changes across different contexts. For instance, you can easily switch between light and dark modes or adjust padding for different devices, creating more adaptable component systems.
Variables offer greater design flexibility, allowing you to change specific values like button text or color for individual instances. Styles help maintain design consistency for elements like button styles, headings, or color palettes.
Variables store individual values, while styles store collections of related values.

Methodology

Organize collections by abstraction levels.

Figma variables can be organized into four collections, each serving a distinct purpose.

┌───────────────┐                                                             
│  Collections  │                                                             
└───────────────┘                                                             
        │                                                                     
        ├───────────────────┬──────────────────┬───────────────────┐          
        ▼                   ▼                  ▼                   ▼          
┌───────────────┐ ┌───────────────────┐ ┌─────────────┐ ┌────────────────────┐
│ Design Tokens │ │ Global Primitives │ │  Language   │ │ Private Primitives │
│  (Published)  │ │    (Published)    │ │ (Published) │ │(Hidden & agnostic) │
└───────────────┘ └───────────────────┘ └─────────────┘ └────────────────────┘

	Name	Visibility	Code Definition
01	Design Tokens	`Published`	`In sync`	Context for the intended use of a design primitive.
02	Global Primitives	`Published`	`In sync`	Basic building blocks of the design.
03	Language	`Published`	`Optional`	Text strings for adapting to different languages.
04	Private Primitives	`Hidden`	`N/A`	Raw values intended for internal use.

The rationale

Through many iterations with enterprise projects, this collection structure has evolved to balance flexibility with governance. It addresses several key challenges when scaling design systems:

Clarity in Abstraction: Separating raw values from semantic tokens aligns design with development. This prevents mixing hex codes with contextual tokens, helping everyone avoid style inconsistencies.
Consistency at Scale: Private primitives help enforce mathematical scales, ensuring uniform spacing throughout interfaces. Designers can use these scaled values rather than manual padding, creating consistent UI element ratios.
Efficient Localization: A dedicated language collection separates text from components, making it simple to switch between languages with minimal effort.
Code as the Source of Truth: "Design Tokens" and "Global Primitives" generate raw, tech-agnostic values. Figma structures mirror codebase themes directly, making design-to-development handoff much smoother.

This approach provides structure to prevent chaos while preserving the flexibility needed for complex product ecosystems.

Collections

Each collection contains groups that provide both precision and flexibility for different use cases.

Collection 01: Design tokens

Design Tokens provide a meaningful context for how a design primitive should be used. For example, a design token called --background-warning instantly conveys a sense of urgency or potential caution.

These tokens define colors, spacing, shadows, and sizing for components, with groups that enforce consistent styling across your interface.

Collection visibility (Figma): Published
Theme definition (Code): In sync

┌───────────────────┐                         
│   Design Tokens   │                                            
└───────────────────┘                         
          │                                   
          │  ┌────────────┐     ┌────────────┐
          ├─▶│   Border   │──┬─▶│   Width    │
          │  └────────────┘  │  └────────────┘
          │                  │  ┌────────────┐
          │                  └─▶│   Radius   │
          │                     └────────────┘
          │  ┌────────────┐     ┌────────────┐
          ├─▶│   Colors   │──┬─▶│ Background │
          │  └────────────┘  │  └────────────┘
          │  ┌────────────┐  │  ┌────────────┐
          ├─▶│   Shadow   │  ├─▶│    Base    │
          │  └────────────┘  │  └────────────┘
          │  ┌────────────┐  │  ┌────────────┐
          ├─▶│   Sizing   │  ├─▶│   Border   │
          │  └────────────┘  │  └────────────┘
          │  ┌────────────┐  │  ┌────────────┐
          ├─▶│  Spacing   │  ├─▶│  Content   │
          │  └────────────┘  │  └────────────┘
          │  ┌────────────┐  │  ┌────────────┐
          └─▶│   Alias    │  ├─▶│ Highlight  │
             └────────────┘  │  └────────────┘
                             │  ┌────────────┐
                             └─▶│Illustration│
                                └────────────┘

In the codebase, design-tokens.js might look like this:

export const designTokens = {
  'border': {
    'width': { 'default': '0.063rem' },
    'radius': { 'small': '0.25rem' }
  },
  'colors': {
    'background': { 'primary': 'oklch(100% 0 0)' },
    'base': { 'primary': 'oklch(59.23% 0.2221 261.8)' }
  },
  'shadow': { 'default': '0px 0px 0px rgba(0, 0, 0, 0);' },
  'sizing': { 'xs': '1rem' },
  'spacing': { 'xs': '0.25rem' }
};

Collection 02: Global primitives

Global Primitives form your design system's fundamental building blocks, like colors, spacing, and sizing. They create the foundation of your design but aren't typically used directly in components or layouts.

These primitives store base values such as colors (grey-90, red-50), font sizes, and weights. These can be organized into themes (Default, High Contrast) for quick switching.

Collection visibility (Figma): Published
Theme definition (Code): In sync

┌───────────────────┐                                                                  
│ Global Primitives │                                                                 
└───────────────────┘                                                                  
          │                                                                            
          │  ┌────────────┐     ┌────────────────┐     ┌────────────┐    ┌────────────┐
          ├─▶│   Colors   │──┬─▶│ Default theme  │──┬─▶│    Grey    │─┬─▶│  grey-90   │
          │  └────────────┘  │  └────────────────┘  │  └────────────┘ │  └────────────┘
          │                  │  ┌────────────────┐  │  ┌────────────┐ │  ┌────────────┐
          │                  ├─▶│ High contrast  │  ├─▶│    Red     │ ├─▶│  grey-80   │
          │                  │  └────────────────┘  │  └────────────┘ │  └────────────┘
          │                  │  ┌────────────────┐  │  ┌────────────┐ │  ┌────────────┐
          │                  └─▶│ More themes... │  ├─▶│   Orange   │ ├─▶│  grey-70   │
          │                     └────────────────┘  │  └────────────┘ │  └────────────┘
          │                                         │  ┌────────────┐ │  ┌────────────┐
          │                                         ├─▶│   Yellow   │ ├─▶│  grey-60   │
          │                                         │  └────────────┘ │  └────────────┘
          │  ┌────────────┐     ┌────────────────┐  │  ┌────────────┐ │  ┌────────────┐
          └─▶│ Typography │──┬─▶│  Font family   │  ├─▶│   Green    │ ├─▶│  grey-50   │
             └────────────┘  │  └────────────────┘  │  └────────────┘ │  └────────────┘
                             │  ┌────────────────┐  │  ┌────────────┐ │  ┌────────────┐
                             ├─▶│   Font size    │  ├─▶│    Mint    │ ├─▶│  grey-40   │
                             │  └────────────────┘  │  └────────────┘ │  └────────────┘
                             │  ┌────────────────┐  │  ┌────────────┐ │  ┌────────────┐
                             ├─▶│  Font weight   │  ├─▶│    Teal    │ ├─▶│  grey-30   │
                             │  └────────────────┘  │  └────────────┘ │  └────────────┘
                             │  ┌────────────────┐  │  ┌────────────┐ │  ┌────────────┐
                             └─▶│  Line height   │  ├─▶│    Cyan    │ ├─▶│  grey-20   │
                                └────────────────┘  │  └────────────┘ │  └────────────┘
                                                    │  ┌────────────┐ │  ┌────────────┐
                                                    ├─▶│    Blue    │ ├─▶│  grey-10   │
                                                    │  └────────────┘ │  └────────────┘
                                                    │  ┌────────────┐ │  ┌────────────┐
                                                    ├─▶│   Indigo   │ └─▶│  grey-00   │
                                                    │  └────────────┘    └────────────┘
                                                    │  ┌────────────┐                  
                                                    ├─▶│   Purple   │                  
                                                    │  └────────────┘                  
                                                    │  ┌────────────┐                  
                                                    ├─▶│    Pink    │                  
                                                    │  └────────────┘                  
                                                    │  ┌────────────┐                  
                                                    └─▶│   Brown    │                  
                                                       └────────────┘

Here's a simplified example of what global.js could look like in practice:

export const globalPrimitives = {
  'colors': {
    'default': {
      'grey': { 'grey-90': 'oklch(0% 0 0)', 'grey-00': 'oklch(100% 0 0)' }
    }
  },
  'typography': {
    'fontFamily': { 'default': "system-ui, sans-serif;" },
    'fontSize': { 'm': '1rem' },
    'fontWeight': { 'regular': 400 },
    'lineHeight': { 'm': '1.5' }
  }
};

Collection 03: Language

The Language collection holds text strings for global areas, components, patterns, and abstractions. This centralizes translations, making them accessible throughout the design system.

Collection visibility (Figma): Published
Theme definition (Code): Optional

┌───────────────────┐                                  
│     Language      │                                                                    
└───────────────────┘                                  
          │                                            
          │  ┌────────────────┐      ┌────────────────┐
          ├─▶│Global Patterns │───┬─▶│     Header     │
          │  └────────────────┘   │  └────────────────┘
          │  ┌────────────────┐   │  ┌────────────────┐
          ├─▶│  Abstractions  │   ├─▶│    Sidebar     │
          │  └────────────────┘   │  └────────────────┘
          │  ┌────────────────┐   │  ┌────────────────┐
          └─▶│    More...     │   ├─▶│     Footer     │
             └────────────────┘   │  └────────────────┘
                                  │  ┌────────────────┐
                                  └─▶│    More...     │
                                     └────────────────┘

Collection 04. Private primitives

Private primitives contain fundamental values (numbers, scales, black/white) that are used by other collections. They help build spacing scales and colors for other collections, ensuring mathematical consistency across your design system.

Collection visibility (Figma): Hidden
Theme definition (Code): Not applicable

┌───────────────────┐          
│Private Primitives │                   
└───────────────────┘          
          │                    
          │  ┌────────────────┐
          ├─▶│      zero      │
          │  └────────────────┘
          │  ┌────────────────┐
          ├─▶│   1, 2, 4...   │
          │  └────────────────┘
          │  ┌────────────────┐
          ├─▶│      50vh      │
          │  └────────────────┘
          │  ┌────────────────┐
          ├─▶│  black, white  │
          │  └────────────────┘
          │  ┌────────────────┐
          ├─▶│     solid      │
          │  └────────────────┘
          │  ┌────────────────┐
          └─▶│ regular, bold  │
             └────────────────┘

Bringing it all together

By organizing Figma variables into these four collections, the result is a system that's both robust and scalable. This structured approach enhances collaboration, scalability, and flexibility, enabling teams to build better user interfaces with greater efficiency.

Variables in Figma

.
├── Design Tokens
│   ├── Border
│   │   ├── Width
│   │   └── Radius
│   ├── Colors
│   │   ├── Background
│   │   ├── Base
│   │   ├── Border
│   │   └── ...
│   ├── Shadow
│   ├── Sizing
│   ├── Spacing
│   └── ...
├── Global Primitives
│   ├── Colors
│   │   ├── Default theme/
│   │   ├── High contrast theme/
│   │   └── ...
│   └── Typography
│       ├── Font family
│       ├── Font size
│       ├── Font weight
│       └── Line height
├── Language
│   ├── Global areas
│   │   ├── Header
│   │   ├── Sidebar
│   │   ├── Footer
│   │   └── ...
│   ├── Patterns
│   ├── Abstractions
│   └── ...
└── Private Primitives/

Organization alone isn't sufficient. Figma variables should stay in sync with the codebase, creating a single source of truth. This can be achieved through automated scripts and Figma local MCP server that bridge the gap between design and development.

In the codebase

.
└── themes
    ├── definitions
    │   ├── dark
    │   ├── light
    │   └── tests
    ├── design-tokens.js   // generated from `Design Tokens` Figma collection
    ├── global.js          // generated from `Global Primitives` Figma collection
    └── utils.js

This structure provides the flexibility needed for complex projects while maintaining the rigor required for enterprise-level design systems.

Invite an AI to Look Upon Your Designs

abhi — 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

abhi — 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 ↗