Upload Figma images to Percy via CLI

This page provides information on how to upload Figma images to Percy and get visual comparisons.

Percy’s support to upload Figma designs via CLI enables you to validate designs and detect visual discrepancies. This guide walks you through running Percy-Figma visual tests using CLI.

Prerequisites

• Install the latest version of Percy CLI.
• Log in to Percy with your credentials and create a Percy Web project.
• Have a basic understanding of CLI and Figma file structuring.

Steps to run your first test

To Upload Figma images to Percy using CLI, follow these steps:

Step 1: Install the dependencies

Ensure that Percy CLI is installed. If it’s not, install it using npm:

npm install -g @percy/cli

Next, install the Percy Figma package.

npm install percy-figma

Step 2:Create the configuration file

Create a configuration file to store the settings needed to upload your Figma images to Percy. This file includes details such as your Figma account, list of designs, and Percy project information.

Here’s a sample .yml file:

percy_token: Percy Project Token
figma_token: Figma Account Access Token
figma_file_token: Figma File Token
ids: ["111-111", "222-222"]
names: ["Snapshot 1", "Snapshot 2"]

• Find the Percy Project Token under the Project Settings section in Percy.
• Generate the Figma Account Access Token from the Personal Access Tokens section in Account Settings, or generate it from here.
• Locate the Figma File Token (i.e., the figma_file_token parameter) in your Figma file URL. Example: https://www.figma.com/file/file-token/MockUpName.
• In the ids array, provide a list of node IDs, which can be found in the Figma file URL. Example: https://www.figma.com/file/file-token/MockUpName?type=design&node-id=1-100.
• The names array should contain names corresponding to the ids array. Snapshots will be uploaded to Percy using these names.

Alternatively, you can provide the tokens as environment variables.

Percy project token

export PERCY_TOKEN="your-percy-project-token"

set PERCY_TOKEN="your-percy-project-token"

Figma Account Access Token

export FIGMA_TOKEN="your-figma-user-token"

set FIGMA_TOKEN="your-figma-user-token"

Figma File Token:

export FIGMA_FILE_TOKEN="your-figma-file-token"

set FIGMA_FILE_TOKEN="your-figma-file-token"

Step 3: Uploading designs to Percy

Run the following command:

npx percy-figma

By default, the package looks for the percyFigma.yml config file. If you are using a different config file, specify it using the –config flag:

npx percy-figma --config your-config-file.yml

Once complete, a build is generated under your Percy project, and the Figma images are uploaded to it. You can now run your test script to generate a Percy build, which will be compared with the Figma build.