Getting started

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 its marketplace
• 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 three things: Claude Code installed, Node 22 or later, and a project with design tokens — a tokens.json (or .json5) in W3C, Tokens Studio, or Style Dictionary shape, a folder of token files, or a Figma variables export. 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

1. Install the plugin. In your terminal — ds-bridge ships as a single bundle, so there’s no npm install step afterwards. Add the ds-bridge marketplace and install from it:

   # 1 · add the marketplace (GitHub owner/repo)
   claude plugin marketplace add lucksy/ds-bridge
   
   # 2 · install the plugin
   claude plugin install ds-bridge
   

2. Open Claude Code in your project. Start a new session from your project folder — the slash commands are live inside it:

   cd your-project
   claude
   

3. 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. Linting your own code needs no token at all. When you’re ready for the Figma-powered features, the Connect ds-bridge to Figma tutorial walks you through adding one — there’s a quick /ds-bridge:connect step because Claude Code doesn’t keep the dialog value across restarts.
   • 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.
   • Insights pane: chart palette, share charts, corner radius — keep the defaults (harvest, donut, 4). They only change how the insights pane draws its charts.

4. Run your first lint. Inside the Claude Code session, point ds-lint at a folder of your own — start small:

   /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 — var(--color-brand-primary), and the run ends with your on-system %: the share of styling values that already use a token.

5. 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.
• Track design-system health over time — turn your runs into trends, set targets, and share one HTML report.
• Catching token drift — compare your token source against your built CSS and watch the trend over time.
• Connect ds-bridge to Figma — save your token so it survives restarts, set your library file, and register product files. The one-time gateway to every Figma-powered feature below.
• 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 started after the install. 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 — /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 when you’re ready via Connect ds-bridge to Figma.