Token Diff guide

Token Diff compares two versions of a design system’s tokens and tells you what changed, what breaks for the people who use them, and which version number the release needs. Open Token Diff

Why you need it

A token release is usually reviewed as a JSON diff in a pull request. That diff hides the things that hurt consumers:

• Renames look like a removal plus an addition. Nobody notices that space-sm became space-small until builds fail.
• Alias chains hide the blast radius. Changing one base color silently changes every semantic token that points to it.
• Themes are easy to miss. A value can change only in dark mode, in one file out of twenty.
• The version number is a guess. A removal shipped as a minor release breaks everyone who upgrades.

Token Diff reads both versions the way a consumer would: it resolves every alias in every theme, matches tokens across versions and judges each change by its effect.

Every figure on this page is live: dsgraph runs in your browser on a small example design system, two versions of one CSS file with a light and a dark theme, and the figures show what Token Diff shows.

Who it is for

How to use it

1. Pick the two versions. For each side, choose one of:
   • npm: a package name; the versions load by themselves, and the latest release is compared with the one before it.
   • GitHub: owner/repo/folder and a branch, tag or commit. Without a token GitHub allows 60 requests an hour; for a private repository, open Token and paste a token with read access. It stays in the tab and never goes into a link.
   • Files: drop token files or a whole folder onto the row, or choose them.
2. Add your code, if you like. Drop your project folder on Your code, or switch it to GitHub and give the repository: styles, JSX and TSX, Tailwind classes, Vue and Svelte are read in the browser, never uploaded. A repository also goes into the link, so the result can be shared. The result then shows the places in your code each change breaks or alters, how much of the code is on tokens, and what to write instead of values written by hand.
3. Press Compare (⌘ ↵).
4. Read the result and export what you need.

Token Diff understands DTCG 2025.10 JSON (including resolver documents with sets and themes, and modes in $extensions.mode from Figma variable exports), older token JSON with value and type (token sets, theme files and .value references included), CSS custom properties with themes in :root, [data-theme], .dark or prefers-color-scheme, and dsgraph snapshots. Math such as {space.base} * 2 and color modifiers are calculated, so a change to a base value shows up in everything built on it. If a package ships many files, put the ones you mean in Files, for example dist/tokens.css or tokens/**/*.json.

What you get

• A verdict: breaking, minor, patch or no impact, with the counts behind it.
• What breaks comes first: removed tokens, renames with a confidence score, type changes, tokens missing from a theme.
• Value changes per theme: colors as swatches with ΔE, sizes with the difference in pixels, the alias each value came from.
• The blast radius: for each changed token, the tokens that changed through references because of it, drawn as a graph.
• Checks on the new version: broken references, alias cycles, legacy syntax, naming collisions, grouped so that 300 identical warnings take one line.
• Your code, if you add it: the places each change breaks or alters, how much of the code is on tokens, and what to write instead of values written by hand.
• Exports: Markdown for a changelog or a pull request, the full changeset as JSON, and a 1200×630 card for a post.

The graph

Tokens point to each other. In JSON, "value": "{color.blue.500}" means the token takes its value from color.blue.500; in CSS the same is var(--color-blue-500). dsgraph reads every token as a point and every such reference as a line between two points, separately for each theme, because a theme can replace a reference with a value of its own.

That is what lets Token Diff tell a change from its consequences. When color-blue-500 changes, color-accent changes with it, although nobody edited it. Token Diff shows color-accent under the change that caused it, not as a separate change, and draws the chain: above, where the token takes its value from; below, which tokens use it. Changed tokens are outlined in the color of their impact; click one to open its change.

Reading the result

The verdict above the list is the highest impact of all changes. In the example it is breaking, because one token was removed and one renamed.

The list is grouped by what a change means for the people who use the tokens: Breaks, Looks different, New, Deprecated, and Hard to notice, folded when there are many. What breaks comes first. A removed token shows the value it had. A rename is detected from the same values in every theme and similar names; a confidence under 80% means “check this one”.

Value changes show both values and the difference in words: lighter · noticeable, +2px. For colors the words come from ΔE, the distance in OKLab, scaled so that 1 is about the smallest difference people notice; under 1 counts as a patch. Through aliases means a token was not edited itself, but something it points to was.

Themes. Choose one in the filter bar to see only what changes there. Changes that apply everywhere stay visible.

Checks run on the new version. Identical problems are grouped, so a file written the pre-2025 way gives a few lines, not hundreds.

Sharing

• Copy Markdown (⌘ ⇧ C) gives a changelog section grouped by impact. It is the same text the dsgraph CLI writes, so it fits a pull request comment as is.
• Copy link shares the comparison. For npm and GitHub the link is just the address. Your own files go into the part of the link after #, which browsers never send to a server; large files cannot be shared this way, so share the Markdown or JSON instead.
• Card for a post makes a PNG with the verdict, the counts and the changed colors.

Keyboard

On Windows and Linux, use Ctrl instead of ⌘.

Privacy

Everything runs in your browser tab. Dropped files are never uploaded. Packages are downloaded from jsDelivr and repositories from GitHub directly by your browser. There is no account and nothing is stored.

In CI

On GitHub, the action compares every pull request with its base branch and keeps one comment up to date with the same report:

- uses: actions/checkout@v4
- uses: specsure/dsgraph-action@v1
  with:
    path: tokens
    fail-on: major

With fail-on: major the check fails when the change is breaking, so a breaking change cannot slip out as a minor version. Elsewhere, the CLI does the same:

npx @dsgraph/cli diff npm:@scope/tokens@1.4.0 ./tokens --format markdown --fail-on major

In your app

If your app uses someone’s token package, check an upgrade before you take it. In Token Diff, put the version you use and the new one side by side and add your app on Your code, as a folder or a GitHub repository. In a terminal, in the project folder:

npx @dsgraph/cli upgrade-check @scope/tokens

It compares the version you use with the latest and lists the places in your code that break or look different, with file and line: CSS, SCSS and Sass, style objects and CSS-in-JS in JSX and TSX, Tailwind classes, Vue, Svelte and Astro. On GitHub, the action with package: '@scope/tokens' posts the same list on the pull request that bumps the version.

Coming next

• Figma plugin. Check Figma variables and styles against your tokens, inside Figma. Soon.
• Tailwind’s own palette and spacing (bg-blue-500, p-3) in a project with its own design system: values outside the system, with the token to use.