How to Test Figma Designs With Applitools

To test a Figma design against a running website with Applitools Eyes, use Figma Dev Comparison: give Eyes a Figma frame URL, map it to the matching test name, and run your existing Eyes test. The design becomes a visual reference, and Eyes sizes the test viewport to match it. You need an Eyes SDK in a supported framework, an Applitools account, and a Figma personal access token with the file_content:read scope. [Applitools Figma Dev Comparison documentation]

This guide shows the current SDK-linked workflow, how to choose baseline behavior, and how to diagnose common setup failures. It compares a rendered implementation with a design; it does not perform general design QA inside Figma or edit the design file.

1. Check your SDK and framework

Figma Dev Comparison is configured in an Applitools Eyes SDK project. The documented combinations include:

JavaScript/TypeScript: Playwright (Fixtures and Standard), Cypress, Storybook, Selenium, and WebdriverIO.
Java: Selenium and Playwright.
Python: Selenium and Playwright.
.NET: Selenium and Playwright.

Native mobile support is described as planned, so do not assume it is currently available for this workflow. Start from the integration instructions for the SDK and framework you already use, then add the Figma mapping to that SDK’s configuration.

2. Create a Figma access token

Create a Figma personal access token with the file_content:read scope. The integration reads it from the FIGMA_ACCESS_TOKEN environment variable or from the accessToken option inside figmaOptions. If neither is configured, and offline or cache-only mode is not enabled, Eyes cannot retrieve the design through the Figma API. See the official setup and token requirements for the SDK-specific configuration shape.

# Set this in your shell or CI secret store; replace the value with your token.
export FIGMA_ACCESS_TOKEN="YOUR_FIGMA_PERSONAL_ACCESS_TOKEN"

Keep the token out of source control and logs. In CI, add it as a secret environment variable available to the test process.

3. Link a Figma selection to an Eyes test

Copy the Figma URL for the frame, component, or component set you want to compare. Then associate that URL with the exact test or story name that the selected SDK uses. You can configure the project’s figmaBaselines mapping for one or more tests, or use the SDK’s direct setup function when configuring a single URL. The mapping key must match the name Eyes resolves for that test or story.

// Configuration shape: use the documented option names in your SDK's config.
// The mapping key must equal the resolved Eyes test or story name.
figmaBaselines: {
  "checkout page": "https://www.figma.com/design/FILE_KEY/Design?node-id=1-2"
}

This is an illustrative configuration shape, not a complete SDK test file: the package, test lifecycle, and configuration wrapper differ by framework. Follow the corresponding code sample in the Applitools integration documentation for the SDK you use. A URL that is not a valid Figma design link is a validation error.

4. Choose how design changes affect baselines

The comparison mode determines whether Eyes follows the current Figma design or an accepted implementation baseline. Pick the mode that matches how your team reviews design changes:

Mode	Behavior	Useful when
`auto-baseline` (default)	Compares against the linked design when it has changed since the last accepted implementation baseline. After the implementation is accepted, later runs use that accepted baseline until the linked design changes.	You want design updates to trigger review, followed by ordinary visual regression checks against the approved implementation.
`figma-baseline`	Always uses the current linked Figma design as the reference.	You want each run compared directly with the latest design.
`test-baseline`	Uses the accepted Eyes test baseline.	You want the test’s accepted implementation image to control comparisons.
`disabled`	Turns off the Figma integration.	You need to disable design comparison for a run or environment.

Set the mode through the SDK configuration or the documented APPLITOOLS_FIGMA_MODE environment variable. Confirm your local and CI settings agree with the review policy; an unexpected mode can make a test appear to ignore either a new design or an accepted test baseline.

5. Run the test and review differences

Run the existing Eyes test or story with the Figma token and mapping available to the process.
Open the Eyes result and inspect the implementation beside the linked design reference. The viewport is sized to match the design.
Review the detected visual differences. Accept changes that are intentional; reject differences that indicate a defect so the prior accepted baseline remains active.
For later runs, check the selected comparison mode to understand whether the reference is the current design or the accepted test baseline.

Visual UI testing generally captures screenshots at important application states, called checkpoints, and compares them with stored baselines. On a first run, captured checkpoints become baselines; on later runs, reviewers accept legitimate changes or reject bug-related differences. [Applitools overview of visual UI testing]

With Figma Dev Comparison, linked runs also create a short-lived Eyes test to render the design reference. That temporary test is removed afterward, though a transient dashboard entry may appear. Results expose design context such as its name, type, revision, last-modified time, and comparison mode.

6. Common problems and fixes

Symptom	Likely cause	What to check
Eyes cannot resolve the design	The token is missing, invalid, or lacks permission.	Confirm it is a Figma personal access token with `file_content:read`; check that the test process receives `FIGMA_ACCESS_TOKEN` or the configured `figmaOptions.accessToken`.
Configuration rejects the URL	The value is not a valid Figma URL, or the URL points somewhere other than the intended selection.	Copy the link to the frame, component, or component set from Figma and use that URL in the mapping.
The mapping appears to be ignored	The mapping key differs from the test or story name resolved by the SDK.	Compare the configured key with the actual Eyes test/story name, including spelling and punctuation.
The result compares with an unexpected reference	The configured mode chooses a different reference than expected.	Inspect the SDK setting and `APPLITOOLS_FIGMA_MODE`; choose among `auto-baseline`, `figma-baseline`, `test-baseline`, and `disabled`.
A temporary test appears in the dashboard	Eyes created the short-lived test used to render the linked design reference.	This is part of the documented linked-run behavior; it is removed afterward.
You expect Figma file validation or editing	This integration compares a running implementation with a design reference.	Use Figma’s design workflow for design-file QA or editing; Dev Comparison is not a general Figma inspection or editing tool.

7. Reliability and workflow notes

Protect access: provide the token through environment configuration or the SDK option, and manage CI access as a secret.
Make reference behavior explicit: choose a mode deliberately for local development and CI so design updates and accepted implementation changes produce predictable reviews.
Keep names stable: mapping depends on the SDK-resolved test or story name. Renaming tests may require updating the mapping.
Review viewport implications: the design determines the test viewport size, so a Figma-linked comparison may use a different viewport from other visual checkpoints.
Plan review time: visual differences require human decisions about intended changes versus bugs; accepting a change updates the accepted reference behavior.

The cited integration documentation does not establish a performance benchmark or a pricing figure for this workflow. Check your Applitools plan and current account terms for cost details rather than estimating from screenshot count alone.

8. Migrating from the older Eyes Figma plugin

Older tutorials may show the Eyes Figma plugin exporting selected frames to Eyes. Its documented workflow requires an active Applitools account and API key; first exports are auto-accepted as baselines unless that setting is changed, and later exports are compared with those baselines. The plugin documentation says it will be deprecated in favor of Figma Dev Comparison. Use the newer SDK-linked flow for design-to-implementation comparison. The plugin remains relevant context for teams maintaining an existing export workflow or for design-to-design review. [Eyes Figma Plugin documentation]

Applitools’ September 15, 2026 product update describes frame-URL design baselines without plugin installation, manual export, or baseline upload. Use the Dev Comparison documentation for the detailed setup and mode behavior. [Applitools What’s new?]

Or skip the browser setup

If your immediate task is to capture a page image without configuring a local browser, ScreenshotNeo provides a website screenshot API and MCP server. Its one-request API returns a PNG, JPEG, WebP, or PDF, and its parameters are compatible with names used by other screenshot APIs. It captures the rendered page; it does not link a Figma frame to an Eyes test or replace the Figma baseline workflow above.

For a basic capture, replace the target URL and API key:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners are accepted like a visitor and removed along with 60+ known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server offers take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Can I use any Figma link?

Use a valid Figma URL for the frame, component, or component set you intend to compare. A non-Figma URL is a validation error.

Does this check a design without a running implementation?

Figma Dev Comparison is documented for comparing a running implementation with a design reference. The legacy plugin documents design-to-design and design-to-code export comparisons.

Will accepting a difference change the Figma file?

No. The workflow reviews and accepts an Eyes baseline; it does not edit the Figma design.

Can I use this with Storybook?

Yes. Storybook is among the documented JavaScript/TypeScript integrations. Match the Figma mapping key to the story name resolved by the SDK.