Connect ds-bridge to Figma

What you’ll learn

Everything in the first tutorial worked without Figma. This one opens the other half of ds-bridge: drift detection, handoff scoring, parity, impact, docs — all the features that read your design files over Figma’s API. They share one setup, and it’s worth doing once, carefully, so you never fight it again.

By the end you’ll have a token that survives a restart, a library file every teammate shares, and an optional list of product files you can target by name. We’ll also run a one-command check that catches the single most common mistake (the wrong Figma seat) before it wastes your afternoon.

How to create a Figma token with the right seat and scopes
How to connect it durably — and why the preferences dialog alone isn’t enough
How to set your shared library file and register product files
How to confirm everything with one config show

Setup

You need ds-bridge installed (if not, start with Getting started) and a Figma account on a Dev or Full seat. A View seat is rate-limited to roughly a handful of API requests per month — it will look connected and then silently fail, so this is the first thing to get right.

Steps

Create the token. In Figma, open Settings → Security → Personal access tokens and create one. Give it these scopes: file_content:read, library_content:read, file_versions:read, and — only if you want handoff QA to post comments — file_comments:read and file_comments:write. Confirm it’s from a Dev or Full seat.
Connect it — durably. Claude Code does not keep a plugin’s sensitive value across restarts (#62442), so a token typed into the preferences dialog is gone the next time you launch. The durable home is a gitignored .ds-bridge.env the CLI auto-loads on every run. The reliable way to write it is the interactive command, run in your own terminal — it prompts with the input hidden and verifies the result:
```
ds-bridge config connect --verify
```
It asks for the token (hidden), then your library file key, writes .ds-bridge.env (0600, and adds it to .gitignore), and then pings Figma to confirm the token works and your seat can read library content. Inside Claude Code you can also run /ds-bridge:connect, which saves any token already in the session and otherwise points you back here.

Note
Note: --verify is the step that catches a View-seat token. A green “Library readable” line means you’re genuinely good to go; a 429 warning means the seat is throttled and you need a Dev/Full-seat token.
Set your library file. Your design-system library — the Figma file that publishes your components and variables — is shared by everyone, so its key belongs in the committed .ds-bridge.json, not the secret file. Paste the URL or the bare key; a full Figma URL collapses to the key automatically:
```
ds-bridge config set-library https://www.figma.com/design/<KEY>/Your-Library
```
That writes figma_file_key to .ds-bridge.json. Commit it — now every teammate who clones the repo points at the same library and only needs to run their own config connect for the token.
Register product files (optional). A library is consumed by product files — your web app’s designs, the mobile app’s, an admin console’s. Register each under a short alias so you can target it by name later:
```
ds-bridge config add-product web   https://www.figma.com/design/<WEB_KEY>/Web
ds-bridge config add-product mobile https://www.figma.com/design/<MOBILE_KEY>/Mobile
ds-bridge config list
```
Now ds-bridge impact --file-key web or ds-bridge library-health --file-key mobile runs against that file — no pasting keys. A single frame URL (handoff QA, figma-impl) is already self-contained and needs none of this.
Check everything. One command shows the effective configuration — token masked — and, crucially, which source won each value, so there’s no guessing whether a stale dialog value is shadowing your committed file:
```
ds-bridge config show
```
You should see your masked token sourced from .ds-bridge.env, your library key from .ds-bridge.json, and any product aliases listed. That’s a connected repo.

Result

You’ve created a properly-seated Figma token, saved it where it survives restarts, pointed ds-bridge at your shared library, and (optionally) named your product files. config show confirms it in one glance. Every Figma-powered tutorial below now just works — start with whichever matches your role:

Catching token drift — does your built CSS still match your token source?
Scoring a frame for handoff — readiness QA before a design reaches engineering.
Build your component registry and parity matrix — match Figma components to their code and act on the gaps.
Detecting breaking library changes — know what breaks before you pull a new library version.

Working from Figma designs in Claude Code? Implementing a Figma frame in code explains the second Figma login (the MCP server), which is separate from the token you just set.

Troubleshooting

config connect says it needs a terminal? It’s interactive and won’t run through Claude Code’s tool runner — that’s by design, so your token is never echoed. Run it in your own shell. (Already have FIGMA_TOKEN exported? Use ds-bridge config persist-token instead, which is non-interactive.)
--verify reported a 429 / rate limit? Your token is from a View seat. Recreate it from a Dev or Full seat — a View seat can’t read library content.
It worked, then “No token” after a restart? The token only ever lived in the preferences dialog, which doesn’t persist. Run config connect once to write .ds-bridge.env; after that it’s durable.
config show reads the wrong key? Run ds-bridge from your repo root — the CLI loads .ds-bridge.env from the current directory only, and the ← source column in config show tells you exactly which file or env var won.