ds-bridge is a Claude Code plugin that measures how much of your styling uses your design tokens, and keeps design and code on the same system — token-aware linting, drift detection, handoff QA, parity, and design-to-code. Each check you run on your project is saved to .ds-bridge/history.jsonl in your repo (single-file lints are left out), CI can record it on every push, and the dashboard, the manager report and the org rollup turn that history into trends. Every slash command is a thin wrapper over the bundled CLI, so anything you run in Claude you can also run in CI.
Commands01
The commands.
Sixteen slash commands ship in this plugin, all namespaced /ds-bridge:<name>. Most run a matching CLI command and interpret its --format=json output — with a --format=term default for humans. Three are different: dashboard opens the rendered HTML report, figma-impl orchestrates several CLI calls around the Figma MCP connection, and analytics hands the full report to subagents. In these pages ds-bridge <command> is the bundled CLI — on the PATH inside Claude Code, and in your own terminal after npm i -g github:lucksy/ds-bridge#release. The first six are the daily drivers; the rest are the v2 additions. Open Example output under a command to see what it reports, or browse them all on Examples.
Slash command
CLI underneath
What it does
/ds-bridge:connect
ds-bridge config persist-token
Save the Figma token from this session into a gitignored .ds-bridge.env (0600) so it survives restarts, and point you at config connect --verify to check it.
Example output
> ds-bridge config showexample · acme-shop
ds-bridge configuration Figma token figd_…XXXX ← .ds-bridge.env Library file key L5ZCpigEnN9MxJwa8AORmH ← .ds-bridge.env Token source — (auto-detect) ← auto-detected at run time Report style both ← default Readiness gate 80 ← default
After `ds-bridge config connect --verify`: the effective config with the token masked, and which source won each value.
/ds-bridge:ds-lint
ds-bridge lint
Find hardcoded values that should be design tokens; --fix rewrites exact matches only, never near-misses.
12 findings · --fix rewrites the 4 exact matches in place
Every raw color and size checked against your tokens: exact matches you can fix automatically, values with no token, and the on-system share.
/ds-bridge:token-check
ds-bridge tokens check
Detect drift between the token source and built outputs — stale, missing, and orphan values.
Example output
> /ds-bridge:token-checkexample · acme-shop
In sync86tokens match the built CSS
0stale
0missing
0orphan
Source tokens/tokens.json · modes lightdark
Your token source compared with the built CSS — stale, missing and orphan variables.
/ds-bridge:dashboard [--setup] [path]
ds-bridge report [--view] [--artifacts]
Render the offline, self-contained HTML dashboard from history.jsonl and open it; --setup composes a persona view — one of six roles (ds-designer, ds-manager, ds-engineer, product-designer, product-manager, product-engineer) or everything — from the same history. --format also renders md (a markdown scorecard; add --delta <ref> for a PR/CI diff), terminal (a selection-aware text report), or site (a static dashboard site for GitHub Pages). See an example dashboard →
Before writing code: how much of the frame resolves to your tokens and components, and exactly what doesn’t.
/ds-bridge:a11y-check
ds-bridge a11y
Audit token-level WCAG contrast over semantic color pairings across every mode, and surface the failing ones.
Example output
> /ds-bridge:a11y-checkexample · acme-shop
Pass AA19/20pairs across light and dark
Fail1one fix
Aamuted-foreground on mutedlight4.34:1fail · try #707070
Aamuted-foreground on muteddark5.83:1pass
Aaprimary-foreground on primarydark14.22:1pass
Aaforeground on backgrounddark18.96:1pass
Every semantic foreground/background pair, in every mode, against WCAG AA — with a suggested fix for each failure.
/ds-bridge:impact
ds-bridge impact
Detect breaking Figma library changes since the last snapshot and map them to the code that uses them.
/ds-bridge:ds-changelog
ds-bridge changelog
Generate an audience-segmented changelog from git log, labeled Figma versions, and token changes.
Example output
> /ds-bridge:ds-changelogexample · acme-shop
0breaking
1notable
4minor
3Figma versions
Oct 7minorFindings status after v1.16.0code
Oct 6minorConfigure ds-bridge (library key, gitignore token)code
Oct 6notableAcme shop on shadcn/ui with Tokens Studio tokenscode
Code, Figma and token changes in one list, by severity and audience.
/ds-bridge:ds-docs
ds-bridge docs
Generate component MDX pages plus an llms.txt summary from the saved registry and tokens.
/ds-bridge:analytics
ds-bridge analytics
The analytics front door: the headline — health, adoption, consistency and debt, replayed from history — then a fan-out report across the Figma, code, token and git domains, a prioritised list of fixes, the manager one-pager (report --format exec) or the JSON artifacts (analytics --emit all).
Four numbers replayed from recorded history — health, import coverage, consistency and debt — with the trend and the status of every data domain.
/ds-bridge:record
ds-bridge record
Run every configured check as one batch sharing a runId and store the system score with the weights used; --figma adds registry build, parity and library health. Skipped checks name the command that un-skips them.
/ds-bridge:rollup
ds-bridge rollup
The org view across repos: rank several repos’ recorded history by system score, with on-system share, drift, contrast, readiness and freshness, as paste-ready markdown. Local only — it reads history that was already recorded.
Recorded history from several repos, ranked by system score — local only, nothing hosted.
/ds-bridge:library-health
ds-bridge library-health
Assess the Figma library’s hygiene — override hotspots, deprecated-component usage, and (heuristically) detached instances. The detached count is a heuristic; expect false positives.
Example output
> /ds-bridge:library-healthexample · acme-shop
Placed instances21
Override hotspots1Legacy Button · fills
Deprecated in use1Legacy Button
Detached?1Badge (heuristic)
Override hotspots, deprecated components still in use, and instances that look detached (a heuristic).
/ds-bridge:exceptions
ds-bridge report --artifacts exceptions-review
Review recurring exceptions: components overridden, deprecated or detached run after run. Each one either needs an owner or carries the decision logged in .ds-bridge.json (investigating, fix-implementation, evolve-component), and turns overdue or resolved as later runs come in. It helps log a decision, editing the file only after you confirm. Exceptions never change a count or a score.
Example output
> /ds-bridge:exceptionsexample · acme-shop
Recorded runs2
Need an owner1
Decided1
Legacy Buttonneeds an owneroverrides · 1 latest · 2 of 2 runsfix the usage, or evolve the component?
Legacy Buttonfix the implementationdeprecated · 1 latest · 2 of 2 runs@acme-design · review by Oct 31 · “Swap the last instance for Button”
Deviations that keep coming back, run after run — each one either waiting for an owner or carrying the decision someone made. Logging one never changes a score.
Exit codes are uniform: 0 clean / pass · 1 findings / below-gate · 2 usage or config error. The two generators — ds-changelog and ds-docs — only ever exit 0 on success or 2 on error; they have nothing to fail a gate on.
dashboard still opens the rendered HTML report — but which artifacts it renders is now yours to compose. The ds-bridge dashboard group manages that selection. It is CLI-only — there is no slash wrapper for the individual commands (the slash surface stays sixteen); instead /ds-bridge:dashboard --setup drives dashboard set for you. Reach for these directly in CI or scripts.
CLI command
Exit codes
What it does
ds-bridge dashboard list
0 · 2
Print the artifact catalog — id, title, persona tags — with a marker on the ones the current config enables.
ds-bridge dashboard setup
0 · 2
Interactive wizard: pick a preset, optionally customize, and write the choice to .ds-bridge.json. Needs a TTY.
ds-bridge dashboard set
0 · 2
Non-interactive equivalent — --view <preset> or --artifacts <a,b,…> (mutually exclusive). CI-safe; it is what the wizard calls.
ds-bridge dashboard add
0 · 2
Add one artifact to the persisted list, materializing the active preset into an explicit list first. Idempotent.
ds-bridge dashboard remove
0 · 2
Remove one artifact from the persisted list, materializing the preset first. Idempotent — removing an absent one is a no-op.
ds-bridge library-health
0 · 2
Crawl a Figma file for hygiene signals — override hotspots, deprecated-component usage, and (heuristically) detached instances. CLI-only, cached, never in a hook; needs a Figma token + file key.
ds-bridge digest
0 · 2
Summarize what moved in a time window — drift, lint, readiness, contrast, adoption — as paste-anywhere markdown segmented by audience, ending in up to three concrete actions. The Monday-morning update, generated. --audience managers puts every movement in one section; --since 30d --format html makes the monthly page for your Pages site.
ds-bridge adoption
0 · 2
Measure import coverage — which registry components your code actually imports (resolved .tsx imports only) — and record it for the adoption artifacts. Needs a built registry.
ds-bridge badge
0 · 2
Render the system score — a weighted blend of drift, lint, readiness, contrast, and adoption replayed from run history — as a self-contained SVG badge for your README.
History02
History and analytics.
Every check you run on your project appends one record to .ds-bridge/history.jsonl. Each record carries an envelope — when it ran, its source (local, ci or hook), the git commit and branch, the tool version and a runId — so the series can be plotted per commit and filtered by branch. Older lines without the envelope still read; ds-bridge history migrate upgrades them.
ds-bridge record runs every configured check as one batch and stores the composite system score with the weights used, so changing the weights later never rewrites the past.
CI recording. The ds-bridge composite GitHub Action runs record --source ci on every push to your default branch and publishes the history to a separate ds-bridge-data branch, so your main branch gets no bot commits. Its sample workflow adds a weekly Figma run and a monthly Pages site with the manager digest. On pull requests, a scorecard comment is opt-in (pr-comment), and gate fails a red target.
Out of the repo. The manager one-pager (report --format exec), the JSON report and artifacts, and a CSV export for spreadsheets — see the table below.
Across repos.ds-bridge rollup ranks several repos from their recorded history — a folder, a history file, or <path>@origin/ds-bridge-data — with a mean, a size-weighted aggregate and a per-team breakdown. It runs locally only: nothing is hosted, and it never writes into a repo.
CLI command
Exit codes
What it does
ds-bridge report --format exec
0 · 2
The manager one-pager as paste-ready markdown: system score with trend and change, on-system share, import coverage, consistency, the design-debt index, handoff readiness per frame, targets, the top three risks and next actions, and which checks are fresh. --format exec-html writes the same page as one offline file; --view exec is the leadership dashboard. Numbers never recorded read “not measured”, never 0.
ds-bridge report --format json
0 · 2
The full dashboard data as a versioned JSON document, described by a published schema (schemas/report.v1.schema.json).
ds-bridge analytics --emit
0 · 2
Write byte-stable, schema-versioned JSON per domain — figma, code, token, git, score or all — to .ds-bridge/analytics/.
ds-bridge history export
0 · 2
One row per metric per run as csv (default) or jsonl, for Sheets, Looker or BigQuery — with date, commit, branch, source and the frame for per-frame records; --kind, --since and --until filter it.
ds-bridge history stats|compact|migrate|init
0 · 2
Keep the history healthy: counts and date range, drop the copies inside a run of identical records (the first and last stay), upgrade v1 lines to the v2 envelope, and (opt-in) add merge=union for the history file to .gitattributes. Rewrites are atomic and locked.
hooks/hooks.json runs three small scripts on two events. All are fail-quiet — they always exit 0 and never block your workflow.
PostToolUse (matcher Write|Edit) lints just the file you wrote or edited, on a ≤ 1.5 s budget. On findings it adds a one-line context summary; on clean files, non-lintable files, errors, or a timeout it exits silently.
SessionStart runs a cheap freshness probe: if your token source changed since the last check — or was never checked — it nudges you to run /ds-bridge:token-check. Otherwise it stays silent, and it never spawns the linter or the CLI.
SessionStart also checks whether a Figma token in the session is saved anywhere that survives a restart; if not, it suggests /ds-bridge:connect once. It never writes a file itself.
The same file lists the insights pane under modules: a Claude Code mod, described next.
Insights04
The insights pane.
On Claude Code v2.1.287 and later, ds-bridge also opens a pane beside the transcript. /ds-insights charts the live Figma selection (layers, components, variables and token adoption, over the Figma desktop MCP) and your check history from .ds-bridge/history.jsonl; /ds-insights --library adds library health. Ask Claude for a chart and it draws one through the pane’s show_insights tool. The pane only reads: it never changes Figma or your code.
The data picks the chart: a gauge for one value out of a scale, a donut (a waffle in the terminal) for the parts of a whole, a line for values run by run, a heatmap for rows × columns, bars for a ranking. Claude Desktop draws them as Nivo-style SVG; the terminal draws them in text and coloured cells. Colours come from insights_palette (default harvest), with insights_share_style and insights_corner_radius beside it.
State05
Project state.
ds-bridge keeps project state in your repo, where it’s PR-reviewable, and keeps rebuildable caches out of it. The .ds-bridge/ directory is meant to be committed.
bash
<project>/.ds-bridge/
├── registry.json # component registry (schema-versioned, stable diff order)
├── history.jsonl # one record per check run (v2 envelope) — feeds the trends
├── analytics/ # analytics --emit JSON artifacts (byte-stable)
├── rollup.json # optional: the repos ds-bridge rollup reads
├── docs/ # generated component MDX + llms.txt (ds-docs output)
└── reports/
├── dashboard.html # latest self-contained HTML report (offline, no CDN)
└── exec.html # report --format exec-html: the manager one-pager
reports/dashboard.html is one offline file — open the example dashboard to see what it looks like with every section filled in.
Rebuildable caches — the Figma version cursor and the REST cache — live under CLAUDE_PLUGIN_DATA (~/.claude/plugins/data/<id>/), which survives plugin updates. ds-bridge never writes to CLAUDE_PLUGIN_ROOT, which is ephemeral across those updates.
Your dashboard view lives in the project’s .ds-bridge.json, alongside the other committed config, through one of three mutually exclusive keys:
dashboard_view — a persona preset, one of ds-designer, ds-manager, ds-engineer, product-designer, product-manager, product-engineer, everything (the default when nothing is set), or one of the two non-persona views: exec (leadership) and org (one repo of a rollup).
dashboard_artifacts — an explicit ordered list drawn from the 31-artifact catalog (ds-bridge dashboard list prints every id). Set this when a preset isn’t quite your view.
dashboard_default — the name of a saved dashboard under dashboards/ (see dashboard save / load).
The three keys are mutually exclusive — set one, or you get a config error. All are written for you by ds-bridge dashboard set/load or the --setup wizard, which validate ids and keep the diff minimal; hand-editing is discouraged.
Next
Get it running.
Install the plugin, then walk a real workflow end to end — both take a couple of minutes.
