Skip to content

Design

Figma

Link screenshots to Figma frames so the build review shows the design a screenshot implements.

The Figma integration links screenshots to the Figma frames they implement. In the build review, a screenshot with a linked frame shows a Figma frame chip that opens the frame in Figma.

You get Where
A Figma frame chip, with the frame's name The build review, on a screenshot whose name matches a link
A Frame links table The Figma integration's page, under each project

Only linking is supported: CirCI never writes to Figma, and there is no view that shows a screenshot beside its frame yet.

An owner or admin of the workspace opens Workspace settings › Integrations › Add integration › Figma.

  1. In Figma, create a personal access token: Settings › Security. It must be able to read your files.
  2. In CirCI, paste it into Access token (figd_…) and connect. CirCI checks it with Figma and names the connection after the Figma handle.

The token is stored encrypted. A Figma account can be connected in one CirCI workspace of the instance, but a workspace can connect several Figma accounts. If Figma rejects the token later, the integration is flagged as needing attention and asks you to remove it and connect again with a new token.

On the Figma integration's page, give each project the Figma File it's designed in. Paste the file's address (https://www.figma.com/design/…) or just the file key. CirCI reads the file with your token and saves its key and name. It tells you when Figma can't find the file or the token has no access to it. The address of a Figma branch is a different file from its main file. A project without a file doesn't use Figma.

Under each mapped project the page shows a Frame links table (screenshot name or pattern, the frame, whether the link is Auto or Manual, and Remove). There are two ways to fill it.

Manually. Enter a Screenshot name and a Frame address, then Add link. In Figma, select the frame and choose Copy link to selection to get the address; it must include a frame (node-id), not just the file. The screenshot name can be a pattern: * matches within a folder and ** across folders, as in checkout/*. CirCI looks up the frame's name for the table. If Figma is down at that moment, the link is still saved without a name.

Automatically. Link automatically matches the project's screenshot names to the names of the frames in the file:

  1. First, whole names that are equal once case, spaces, slashes, dashes and underscores are ignored (Checkout / Cart matches checkout-cart).
  2. Then, for screenshots left over, a frame named like the last path part of the screenshot name (Cart for checkout/cart).

It never guesses. A screenshot that fits two frames gets no link, a frame that several screenshots claim by their last part is skipped, and existing links are never replaced. Automatic links show as Auto.

If you change the project's file, the automatic links made for the old file are dropped. Clearing the file drops them all. Manual links stay.

A screenshot whose name matches a link shows the Figma frame chip in the review view, with the frame's name when CirCI has it.

What you see Why, and what to do
Saving the file fails with a message that Figma can't find it The address or key is wrong, or the token has no access to that file. Check the token's account can open it
A frame link is refused The address has no node-id. In Figma, select the frame and use Copy link to selection
Link automatically links nothing for a screenshot Its name fits two frames, or no frame, so it's left alone by design. Add the link by hand
The integration shows needs attention Figma rejected the token. Remove the integration and connect again with a new token
  • A view that shows a screenshot beside its frame, with the differences marked.
  • Frames as first baselines: comparing a new screenshot with its frame when no baseline exists.
  • Posting results on frames, such as a comment when a build is approved.
  • Penpot is a Planned tile and has no backend.

Not yet verified against Figma.