Getting started · ds-bridge

What you’ll learn

Welcome! This is the one tutorial to read first. By the end you’ll have ds-bridge installed, configured through its native preferences dialog, and you’ll have run it once against your own project to see a real finding. We’ve timed it: about ten minutes, and every step here works without a Figma token — so designers, managers, and developers can all follow along on day one.

A quick, honest word on that ten minutes. It’s the install-to-first-finding path, not “master the whole plugin”. The Figma-powered features — drift detection and handoff scoring — need a token and a little more setup, and they each have their own tutorial linked at the end. Today we get you to a green, useful first run.

How to install ds-bridge — from the repository, or straight from a checkout
What the preferences dialog asks, and the safe answer to every field
How to run /ds-bridge:ds-lint on your own code and read what comes back

Setup

You need two things: Claude Code installed, and a project with a design token file (a tokens.json in W3C, Tokens Studio, or Style Dictionary shape). That’s it. No Figma account, no personal access token, no settings.json to hand-edit. If you don’t have a token file yet, ds-bridge still runs — it just has nothing to compare your values against, so it’ll report that it found no token source rather than crashing.

Steps

Install the plugin. ds-bridge ships as a single bundle, so there’s no npm install step afterwards. Pick whichever path fits you:

To install it for keeps, register this repository as a marketplace and install from it:
```
# 1 · point a marketplace at the repository (URL, local path, or owner/repo)
claude plugin marketplace add https://github.com/lucksy/ds-bridge

# 2 · install ds-bridge from that marketplace
claude plugin install ds-bridge
```
To just try it from a local checkout — no marketplace, no install — load it for the current session with --plugin-dir:
```
# great for kicking the tyres or developing against a clone
claude --plugin-dir /path/to/ds-bridge
```
Either way, the slash commands (/ds-bridge:ds-lint, …) are live inside that Claude Code session.
Answer the preferences dialog. The first time you enable the plugin, Claude Code prompts you for ds-bridge’s options natively — no config files to edit. Here’s every field and the safe answer for today:
- Figma library file key — leave blank. It’s optional, and nothing in this tutorial needs it.
- Figma personal access token — leave blank. It’s stored securely in your system keychain when you do add one, but linting your own code needs no token at all. You’ll add this later for the Figma features.
- Design token source file — leave blank to let ds-bridge auto-detect it from common paths. Only fill it in if your token file lives somewhere unusual; then point it at that file.
- Report output — keep the default, both (HTML and terminal).
- Handoff readiness gate — keep the default, 80. It only matters for the handoff feature, which you’ll meet later.
Note
Note: Blank is a perfectly good answer. A missing Figma token is a handled, friendly outcome — never a crash — so you can always fill these in later from the preferences dialog without reinstalling.
Run your first lint. Inside the Claude Code session, point ds-lint at a folder of your own — start small:
```
claude /ds-bridge:ds-lint src
```
ds-bridge scans those files for hard-coded colors, spacing, and radii, checks each one against your detected tokens, and reports back. A finding looks like src/Button.tsx:18:14 exact color: "#3b82f6" — use token color.brand.primary.
Read your first findings. Each finding is tagged with a kind that tells you what to do:
- exact — the value is a token; safe to adopt automatically.
- near — close to a token, but a human should decide.
- off-system — nothing in the system matches it.
That three-way split is the whole idea, and you don’t have to act on anything yet. Reading the list is a complete, successful first run.

Result

In about ten minutes you’ve installed ds-bridge, configured it through the native dialog without touching a config file, and read a real finding from your own project — all with no Figma account. That’s the full install-to-first-finding loop, and everything else builds on it.

Where to go next, in order:

Linting for off-system values — go deeper on the three finding kinds and how --fix safely adopts only exact matches.
Catching token drift — compare your token source against your built CSS and watch the trend over time.
Scoring a frame for handoff — the first Figma-powered feature; this is where a personal access token earns its keep.
Build your component registry and parity matrix — match your Figma components to their code and act on the gaps.

You can also browse the full tutorials index any time.

Troubleshooting

The slash command isn’t there? Make sure you’re in a Claude Code session that loaded the plugin — either installed via the marketplace, or started with --plugin-dir /path/to/ds-bridge. Run claude plugin list to confirm ds-bridge is present.
It says it found no token source? That’s the auto-detect coming up empty. Point it at your file explicitly — claude /ds-bridge:ds-lint src --tokens path/to/tokens.json — or set Design token source file in the preferences dialog so every run picks it up.
Worried about needing Figma? You don’t, not for this. Everything here runs with the Figma personal access token left blank; add it only when you reach the handoff tutorial.