ds-bridge

Track design-system health over time

Turn the checks you already run into numbers you can watch — on-system share and a system score, recorded run after run and on every push in CI — then set targets, share a one-page manager report, and export the numbers.

What you’ll learn: dashboard

What you’ll learn

A single lint tells you what’s wrong today. What a design-system team really wants to know is whether things are getting better: is more of the product using the system this month than last month? ds-bridge answers that from your repo’s own history. Each check you run on your project is saved to .ds-bridge/history.jsonl, and the dashboard turns those saved runs into trends.

This tutorial is for anyone who looks after a design system — the manager who reports on it, and the developers and designers who keep it healthy.

Setup

You’ll need the ds-bridge plugin and a project with a token file (Getting started covers both). No Figma token is needed for the lint and drift numbers; handoff and parity numbers appear once you’ve connected Figma and run those checks.

# Install the plugin, if you haven't yet.
claude plugin install ds-bridge

Each step shows the slash command to use in Claude Code and the ds-bridge CLI command it wraps. Use whichever you prefer.

Steps

  1. Record a run. One command runs every check that’s configured — lint, token drift, contrast, and component adoption once you have a registry — as one batch, and stores the 0–100 system score with it:

    ds-bridge record          # or /ds-bridge:record in Claude Code
ds-bridge record --figma  # also library health and parity (needs Figma)

    Each check adds one line to .ds-bridge/history.jsonl, stamped with the time, the git commit and branch, and a shared run id. The lint part ends with the on-system share — how much of your styling uses tokens rather than hardcoded values. That number is the heart of the adoption trend.

    You can still run checks one at a time (ds-bridge lint src, ds-bridge tokens check); each folder run is saved too. A single-file lint (what the hook runs as Claude writes) is left out on purpose.

    To measure the designer side too, list the Figma frames you hand off in .ds-bridge.json. record --figma then scores each one with handoff in the same run, so handoff readiness gets a trend without anyone running it by hand:

    {
  "tracked_frames": [
    "https://www.figma.com/design/<file-key>/<name>?node-id=12-34"
  ]
}

  2. Let CI record for you. A trend needs a point every week, not whenever someone remembers. The ds-bridge GitHub Action runs record --source ci on every push to your default branch and saves the history on a separate ds-bridge-data branch, so your main branch gets no bot commits. Copy the sample workflow into your repo:

    mkdir -p .github/workflows
curl -o .github/workflows/ds-bridge-record.yml \
  https://raw.githubusercontent.com/lucksy/ds-bridge/v1.12.0/examples/ds-bridge-record.yml

    The sample pins the action to the matching ds-bridge release tag (@v1.12.0, the first release that ships it). Give the workflow contents: write. The sample also records the Figma side weekly (when a FIGMA_TOKEN secret is set) and publishes the dashboard and a manager digest to GitHub Pages once a month. The CI recording guide lists every option.

  3. Open the dashboard. The dashboard reads the whole history and draws the trends: the 0–100 system score, on-system share, drift and parity. The latest handoff readiness sits beside them.

    /ds-bridge:dashboard          # in Claude Code: renders it and opens it
ds-bridge report --open       # the same, from the terminal

    The report is written to .ds-bridge/reports/dashboard.html. It’s one self-contained file that works offline. You can see a finished example built from a sample project’s history.

  4. Pick the ds-manager view. By default the dashboard shows everything. If you look after the system and report on it, the ds-manager view keeps the panels that matter to you: adoption, the adoption leaderboard, targets, score velocity and ownership.

    /ds-bridge:dashboard --setup                  # a guided pick, in Claude Code
ds-bridge dashboard set --view ds-manager     # or set it directly

    When a component keeps getting overridden run after run, the Recurring exceptions panel flags it as needing an owner, so the team can decide whether to fix the usage or evolve the component. Turn recurring exceptions into decisions shows how.

    There are six role views in all, plus everything. Compose a dashboard for your role covers them in depth.

  5. Set targets. Tell ds-bridge what “good” looks like, and each number gets a red, amber or green verdict. Add metric_targets to .ds-bridge.json in your project root:

    {
  "metric_targets": {
    "on-system": { "op": ">=", "value": 90, "warn": 80 },
    "system-score": { "op": ">=", "value": 80 }
  }
}

    Green means the target is met. Amber means it’s missed but within the warn line (or within 10% of the target when there’s no warn). Red means it’s further off. The metrics you can target are on-system, system-score, drift, parity, contrast and readiness; op is one of >=, <= or ==.

  6. Compare against a branch or tag. The markdown scorecard shows how each number has moved since another point in your history. Point --delta at a branch or tag whose .ds-bridge/history.jsonl is committed — or at the CI series:

    ds-bridge report --format md --delta main
ds-bridge report --format md --delta origin/ds-bridge-data --gate

    Add --gate and the command exits with code 1 when any target is red. In CI, the action can post this scorecard as one comment on each pull request and update it on later pushes — it’s opt-in: set pr-comment: "true" (and gate: "true" to fail a red target).

  7. Share the manager report. One page answers “how healthy is the system, and is it getting better?”: the system score with its trend, on-system share, import coverage, consistency, the design-debt index, handoff readiness for each frame, your targets, the top three risks and the next three actions.

    ds-bridge report --format exec                  # markdown, ready to paste
ds-bridge report --format exec-html --open      # the same, as one page

    Anything never recorded reads “not measured”, never 0. For the full dashboard, ds-bridge report --view ds-manager --out design-system-health.html writes a single HTML file you can send to anyone. In Claude Code, /ds-bridge:analytics offers the one-pager as option (c).

  8. Export the numbers. Managers often live in a spreadsheet. Export the history as one row per metric per run — date, commit, branch, the check and the value — and paste it into Sheets, or load it into Looker or BigQuery:

    ds-bridge history export --format csv --since 90d --out ds-health.csv
ds-bridge analytics --emit all     # JSON per domain in .ds-bridge/analytics/

  9. Look across repos. If you look after the system for several product repos, ds-bridge rollup ranks them side by side from their recorded history, on your machine. Roll up analytics across repos walks through it.

Result

> /ds-bridge:analyticsexample · acme-shop
Health65/100▲ 14 since Oct 6
Import coverage79%11 of 14 components
Consistency80/100tokens · matches · overrides
Design debt29/100lower is better
  • okfigmalibrary health, parity, per-frame readiness
  • okcodelint, import coverage, custom components
  • oktokendrift and contrast
  • okgitchange activity
  • okscoresystem score and its weights
Four numbers replayed from recorded history — health, import coverage, consistency and debt — with the trend and the status of every data domain.

You now have a design system you can measure, not just check. record adds a batch of points to your repo’s history, and CI adds one on every push; the dashboard turns those points into trends; targets say at a glance what’s on track; --delta shows what moved on each pull request; and the manager report and the export carry the numbers to whoever needs them.

Troubleshooting