ds-bridge

One changelog for designers and developers

Turn your git history, Figma versions, and token changes into a single audience-segmented changelog — one document everyone on the team can read.

What you’ll learn: ds-changelog

What you’ll learn

Every release leaves a trail in three different places: the commits developers push, the versions designers publish in Figma, and the design tokens that change underneath both. Most teams stitch those together by hand, badly, the night before a release. This tutorial teaches ds-bridge’s changelog command, which reads all three sources and prints one changelog split into a For designers section and a For developers section — so each audience reads the half that matters to them without missing the changes that matter to everyone.

A reassuring word for designers and managers reading along: you don’t need to understand git to use this. The command does the reading; you get a tidy, plain-language summary. And it’s safe by design — changelog only ever prints to your terminal. It writes nothing to your repo, Figma, Confluence, or Slack on its own.

Setup

You’ll need the ds-bridge plugin and a project that is a git repository — that’s the one hard requirement, because local git history is the always-present source. New to ds-bridge? Getting started covers install and the preferences dialog first; come back here when you’re set up.

Everything below was captured by running the command against the ds-bridge repository itself, so the output is real git history — your own runs will look the same shape against your own commits.

# A changelog of everything since a date, as markdown.
ds-bridge changelog --since 2026-06-05 --format=md

Steps

  1. Run a full changelog and read the split. With --format=md, ds-bridge prints a markdown document already divided into the two audience sections. Here’s a real run against the ds-bridge repo (trimmed — the full window had 86 entries):

    # Changelog

## For developers

### 2026-06-06

- **[notable]** a11y + impact dashboard sections, history lines, six-artifact acceptance (T7.22) — lucksy
- **[minor]** build dist once via vitest globalSetup - kill concurrent-rebuild race (T7.23) — lucksy
- **[notable]** ds-docs command (T7.20) — lucksy
- **[notable]** docs generation command (T7.19) — lucksy
- **[notable]** a11y-check command (T7.4) — lucksy

### 2026-06-05

- **[notable]** a11y contrast command (T7.3) — lucksy
- **[notable]** impact command (T7.10) — lucksy
…

    Notice the shape: a ## For designers and a ## For developers heading, each with entries grouped by date (newest first), and every line led by a severity badge — [breaking], [notable], or [minor].

  2. Read how commits become severities. This is the heart of the code side. ds-bridge classifies each git commit by its conventional-commit prefix:

    • feat: → a notable change, filed under developers. New features are worth announcing.
    • fix: → a minor change, filed under developers. Bug fixes are real but quieter.
    • feat!: or a BREAKING CHANGE: footer → a breaking change, and breaking changes are surfaced first in their section so they’re impossible to miss.
    • Anything that isn’t a recognised conventional header (a checkpoint tag, a plain subject) falls back to minor.

    You can see this in the run above: the one fix(tests): build dist once… commit landed as [minor], while every feat(…) commit landed as [notable]. This repo’s window happened to contain no breaking commits, so you won’t spot a [breaking] badge here — the first feat! or BREAKING CHANGE: you ship is the first one you’ll see.

  3. Narrow to one audience. Pass --audience designers (or developers, or the default both) to render only that section. Here’s the honest result of asking this repo for the designers’ view:

    # Changelog

_No changes in the selected window._

    That isn’t a bug — it’s the truth. The ds-bridge repo has lots of developer commits but no labeled Figma versions and no token changes in this window, so the designers’ half is genuinely empty. On a real product repo, where designers publish named Figma versions, this is exactly where their milestones would appear.

  4. Watch the Figma side skip itself, honestly. Run the same command with the human-readable --format=term and look at what ds-bridge prints to stderr:

    Figma side skipped (no token / file key configured) — code + token changes only.

    This one-line note is a feature, not an error. With no Figma personal access token and file key configured, ds-bridge can’t read Figma version history — so instead of failing, it tells you plainly that it’s reporting code and token changes only, and carries on. That’s what makes changelog work completely offline, straight from a plain git repo. Add a token (see Getting started) and labeled Figma versions start flowing into the For designers section automatically.

Result

You can now produce one changelog that two audiences will actually read. The developers section carries the commit story, severity-tagged; the designers section carries published Figma milestones and the token changes that cross both worlds. A breaking change is never buried — it leads its section.

A few things worth knowing for everyday use:

Troubleshooting