ds/bridge

Build your component registry and parity matrix

Build a Figma↔code component registry, read matches versus unmatched-with-candidates, and turn the four-status parity matrix into an issue you can act on — without ever guessing.

parity-audit

What you’ll learn

The other tutorials watched your values — colors, spacing, drift. This one zooms out to your components. Most teams keep two parallel lists: the components Figma publishes, and the components the codebase exports. The question nobody can answer by hand is “do those two lists agree?” ds-bridge answers it by building a registry — a saved map of which Figma component corresponds to which code component — and then projecting that map into a parity matrix.

A note for designers and managers: think of this as Figma’s Code Connect, but owned by your repo and reviewable in a pull request. You don’t read any code to use it — the matrix names each component and tells you which side is missing.

Setup

You’ll need the ds-bridge plugin, a Figma library file key, and a Dev- or Full-seat personal access token — the same token the handoff tutorial walks you through creating. New here? Start with Getting started for install and setup.

# Scan code components, fetch the Figma library, and save the registry.
ds-bridge registry build .

Steps

  1. Build the registry first. The parity matrix is a projection of a saved file, so step one is always to build that file. This is a real run against a small project with five code components and a two-component Figma library:

    Registry written to ./.ds-bridge/registry.json
  matched:        0
  unmatched code: 5
  unmatched figma:2

Closest near-misses:
  Button — closest: Button / Primary (10:42) @ 0.542
  IconButton — closest: Button / Primary (10:42) @ 0.5
  Card — closest: Button / Primary (10:42) @ 0.15

    Zero matches looks alarming — but it’s honest, and it’s the whole lesson. ds-bridge only records a match when confidence clears the bar. Button scored 0.542 against Button / Primary: close, but below threshold. So rather than pretend, it files Button as unmatched and keeps the candidate attached. That’s the never-silently-wrong principle: a low-confidence guess becomes a candidate to review, never an asserted truth.

  2. Read the parity matrix. Run parity over the saved registry. It sorts worst-first and ends with a summary bar chart:

    missing-in-code   Button / Primary  No code component matched Button / Primary (10:42); closest is Button @ 0.542.
missing-in-code   Input / Text      No code component matched Input / Text (10:58); closest is Card @ 0.15.
missing-in-figma  Badge             No Figma component matched Badge (components/badge.tsx); closest is Button / Primary (10:42) @ 0.075.
missing-in-figma  Button            No Figma component matched Button (components/button.tsx); closest is Button / Primary (10:42) @ 0.542.
missing-in-figma  IconButton        No Figma component matched IconButton (components/icon-button.tsx); closest is Button / Primary (10:42) @ 0.5.

Summary:
ok               │ 0
prop-mismatch    │ 0
missing-in-code  │█████████▋ 2
missing-in-figma │████████████████████████ 5

7 of 7 component(s) out of parity.

  3. Learn the four statuses. Every row carries exactly one:

    • ok — matched with high shape agreement. Code and Figma agree; nothing to do.
    • prop-mismatch — matched, but the prop/variant shapes diverge. Both sides exist; their contracts need aligning.
    • missing-in-code — Figma publishes it, the codebase doesn’t. Engineering needs to build it. Notice the detail still names the closest code candidate — Button @ 0.542 — so you can see why it didn’t auto-match.
    • missing-in-figma — the codebase has it, Figma doesn’t publish it. Design needs to publish it (or it should be retired).

    Here every row is missing-* because nothing cleared the bar — a brand-new pairing where the names don’t line up yet. As you align names and shapes, rows graduate to ok.

Result

You can now answer the parity question for your whole library at a glance, and — crucially — trust that a blank matched line means “no confident match,” not “no problem.” Low-confidence pairs are never hidden; they ride along as candidates with a score, so a human makes the call.

To turn the matrix into something you can paste into an issue or PR, add --markdown:

ds-bridge parity . --markdown

| Component | Status | Detail |
| --- | --- | --- |
| Button / Primary | missing-in-code | No code component matched Button / Primary (10:42); closest is Button @ 0.542. |
| Badge | missing-in-figma | No Figma component matched Badge (components/badge.tsx); closest is Button / Primary (10:42) @ 0.075. |

_ok: 0 · prop-mismatch: 0 · missing-in-code: 2 · missing-in-figma: 5_

When you want more than a list — prop contracts for missing-in-code, publishing steps for missing-in-figma, shape diffs for prop-mismatch — the /ds-bridge:parity-audit command offers to hand off to the parity-auditor subagent. It reads the registry and your component source, then writes a prioritized, evidence-backed reconciliation plan. Like every command here, it reports only: it proposes the plan and leaves the changes to you. That closes the loop — values in linting and drift, the design side in handoff, and now components end to end.

With the registry in place, you’re ready for the capstone: From a Figma frame to on-system code turns a design into code assembled only from the components and tokens your system actually has.

Troubleshooting