ds-bridge

Compose a dashboard for your role

Pick a persona view — owner, engineering, design, consumer, or everything — so ds-bridge report opens the dashboard you actually read, from one shared history.

What you’ll learn: dashboard

What you’ll learn

One repository, many readers. The people who fix things — engineers and designers — want lists: which lint rules fired, which frames aren’t ready, where the parity grid has holes. The people who fund things — design-system owners and managers — want trends: is drift going down, is contrast holding, is the system getting adopted. For a long time a dashboard had to pick a side. This wave stops making it choose. There is one history under .ds-bridge/, and now there are many lenses onto it. You pick a view, and from then on ds-bridge report renders your dashboard — without changing anyone else’s.

A word for designers and managers: nothing here asks you to think about files. A view is just a saved preference for which panels you want to see. You can pick a ready-made one named after your role, or hand-build a list, and either way the choice lives in a small, readable file your team reviews in a pull request like any other change.

Setup

You’ll need the ds-bridge plugin (Getting started covers install and the preferences dialog) and a project you’ve run ds-bridge in at least once, so there’s a .ds-bridge/history.jsonl to render. No Figma token is required to pick a view — that’s purely a preference. The dashboard reads whatever history you already have.

# Render the dashboard with whatever view is configured (everything, by default).
ds-bridge report

Steps

  1. Meet the seven artifacts. Run dashboard list to see the whole catalog — every panel a dashboard can show, its id, and which personas tend to care about it. With no view set, everything is on:

    View: everything (default)
┌────┬──────────────┬───────────────────┬──────────────────────────────────────┐
│ on │ id           │ title             │ personas                             │
├────┼──────────────┼───────────────────┼──────────────────────────────────────┤
│ ✓  │ system-score │ System score      │ owner, engineering, design, consumer │
│ ✓  │ drift-trend  │ Token drift       │ owner, engineering                   │
│ ✓  │ lint-summary │ Lint violations   │ engineering                          │
│ ✓  │ readiness    │ Handoff readiness │ design                               │
│ ✓  │ parity       │ Component parity  │ owner, design, consumer              │
│ ✓  │ a11y         │ Contrast (a11y)   │ design, owner                        │
│ ✓  │ impact       │ Change impact     │ engineering, consumer                │
└────┴──────────────┴───────────────────┴──────────────────────────────────────┘

    system-score is the one number atop every view — a weighted blend of drift, lint, readiness, and contrast, replayed from your run history (and available as a README badge via ds-bridge badge).

    The personas column is a hint, not a rule — it’s how the presets were drawn. You’re free to compose any list you like.

  2. Pick a view in conversation. The friendliest path is the slash command. Inside Claude Code, run:

    /ds-bridge:dashboard --setup

    It asks who the dashboard is for, offers to add or drop any artifact, saves your choice with ds-bridge dashboard set, and offers to open the result. It’s the same outcome as the steps below — just guided in plain language.

  3. Or run the raw wizard. Prefer the terminal? ds-bridge dashboard setup runs the same flow with no AI in the loop. Here’s a complete session — pick a preset by number, decline customizing, and save:

    Pick a dashboard view:
  1) owner
  2) engineering
  3) design
  4) consumer
  5) everything
View number: 1
Customize the "owner" view? (y/N) n
Save preset "owner"? (y/N) y
Saved. Your dashboard view is now preset "owner".
Render it now? ds-bridge report --open

    The wizard needs a real terminal — it reads your answers from the keyboard. In a script or CI, reach for dashboard set instead (Step 5).

  4. Read the five presets. Each preset is a named, ordered list drawn from the seven artifacts. The ids are a stable contract — so what you pick today keeps meaning the same thing tomorrow (presets may gain new artifacts as the catalog grows; the system score now leads every one):

    owner         system-score · drift-trend · parity · a11y
engineering   system-score · lint-summary · impact · drift-trend
design        system-score · readiness · a11y · parity
consumer      system-score · parity · impact
everything    all seven, in catalog order   (the default)

    consumer is intentionally the thinnest — the score plus two panels. A consumer of the system — someone building with it rather than on it — mostly wants to know two things: does the component I need exist and match (parity), and will a change to the system ripple into my code (impact)? That restraint is the point, not an omission. A short, honest dashboard beats a long one nobody reads.

  5. Set a view without prompts. dashboard set is the non-interactive writer — what the slash command calls under the hood, and what you’d use in CI. Save the owner preset:

    ds-bridge dashboard set --view owner

    View set to "owner".

    Now dashboard list shows the resolved selection — the same catalog, with only the owner panels marked on, and the source named as project (it came from .ds-bridge.json, not the default):

    View: owner (project)
┌────┬──────────────┬───────────────────┬─────────────────────────┐
│ on │ id           │ title             │ personas                │
├────┼──────────────┼───────────────────┼─────────────────────────┤
│ ✓  │ drift-trend  │ Token drift       │ owner, engineering      │
│    │ lint-summary │ Lint violations   │ engineering             │
│    │ readiness    │ Handoff readiness │ design                  │
│ ✓  │ parity       │ Component parity  │ owner, design, consumer │
│ ✓  │ a11y         │ Contrast (a11y)   │ design, owner           │
│    │ impact       │ Change impact     │ engineering, consumer   │
└────┴──────────────┴───────────────────┴─────────────────────────┘

  6. Override for a single run. A persisted view is your everyday default, but any one render can wear a different lens with --view — nothing is written to disk. An engineer on an owner-configured repo can glance at their own panels without disturbing the saved choice:

    ds-bridge report --view engineering --open

    ~/acme-app/.ds-bridge/reports/dashboard.html

    Run it again with no flag and you’re back to the owner dashboard. Flags win for that invocation; the project file wins everywhere else. The resolution order is simple: a --view/--artifacts flag, then the project config, then everything.

  7. Add or remove one artifact — and meet materialization. Sometimes a preset is almost right. dashboard add and dashboard remove tweak it by a single panel. The first time you do this on top of a preset, ds-bridge materializes the preset into an explicit list, then makes the edit. Starting from the saved owner view, add impact:

    ds-bridge dashboard add impact

    Your view is now an explicit list and will not auto-gain future preset artifacts.
Added "impact". View: drift-trend, parity, a11y, impact.

    That notice is the important part, and it’s a promise — not a warning. The moment your view becomes an explicit list, it stops tracking the preset. If a future release adds a seventh artifact to owner, your list won’t silently grow to include it, because you’ve said exactly what you want. Explicit means explicit. That’s intent, not a bug — and if you’d rather follow the preset again, just dashboard set --view owner to go back.

    Under the hood, the edit lands in .ds-bridge.json as a plain, reviewable list:

    {
  "dashboard_artifacts": [
    "drift-trend",
    "parity",
    "a11y",
    "impact"
  ]
}

    This file is yours to read but not to hand-edit for this purpose: the wizard, dashboard set, add, and remove are the sanctioned writers, and they keep the file tidy and your other settings untouched. Because it’s committed, your teammates see the dashboard change in the same pull request as the work that prompted it.

Result

You can now answer “whose dashboard is this?” with “mine — and yours, from the same history.” You’ve seen the full catalog, the five frozen presets, and three ways to choose: a conversational --setup, the raw terminal wizard, and a one-off --view flag for a single render. A saved view lives in .ds-bridge.json as a small, PR-reviewable preference; a --view flag overrides it just for that run; and the resolution order — flag, then project config, then everything — is the same everywhere.

The two view choices map to two keys, and only one is ever set at a time: a preset persists as dashboard_view (a single name like owner), while a hand-built or materialized list persists as dashboard_artifacts (an ordered list of ids). Picking a preset clears any explicit list, and editing with add/remove converts a preset to a list — so the two never fight. Let dashboard set and the wizard manage them; that’s what keeps the file honest.

Troubleshooting