Reviewing Token Changes in Git

The accent changed on a Tuesday, and nobody decided it. The pull request was titled “regenerate tokens after spacing fix”; the tokens file showed forty-one changed lines, one of which re-pointed accent from brand-600 to secondary-500. The reviewer saw a generated file and a green build, and approved. Three weeks later marketing asked why the signup buttons were a different color in the new screenshots. git log -p found the line in about a minute — which is the bitter comedy of the story: the history was perfect, and the review that history exists to enable took ten seconds nobody spent.

Design tokens belong in version control because they make design decisions behave like code: history records who changed the accent, when, and — in the commit message — why; a pull request becomes a design-review artifact; and a bad change is a git revert rather than an archaeology project. But the benefits only arrive with workflow discipline: diffs kept small and stable, a review checklist that reads token lines as design decisions, and regenerated changes separated from hand edits.

This is the governance chapter of our design tokens guide: what a token diff reads like, what a reviewer should ask of it, and the etiquette that keeps a generated file reviewable. It assumes the project pattern where the tokens file lives in the repository and ships through the same gate as code.

Why do design tokens belong in version control?

Version control gives any file three properties — attributed history, gated change, a restorable past — and tokens are unusual among design artifacts in being able to collect all three. Design decisions otherwise have notoriously thin provenance: the answer to “why is the accent this blue?” tends to live in a retired chat thread, an old deck, or someone’s memory. Once the decision is a line in a versioned file, the commit message is a place where rationale sits permanently next to the change it explains — re-point accent to secondary for the promo quarter; revert after Q3 documents a design decision more durably than most design documentation manages.

Rollback is the same property read backwards. A rebrand that has to be walked back is one revert when it is token-shaped; without the file it is a hunt through stylesheets for every value that changed, weeks after anyone remembers changing them.

The intuitive reason review works here, and not on most design artifacts: review depends on a change being small enough to hold in your head. A design-file change is a picture — the reviewer sees the new state, not the delta. A token change is the delta: a handful of named lines. Tokens compress the design layer down to a size review can actually process, and everything else in this article leans on that compression.

What does a token diff read like?

Here is a six-line diff, trimmed to its changed lines and annotated with the sections they sit in — a spacing step tightened, an accent re-pointed, one semantic role added:

@@ spacing @@
-"space-3":    { "$value": "16px", "$type": "dimension" }
+"space-3":    { "$value": "14px", "$type": "dimension" }
@@ semantic @@
-"accent":     { "$value": "{color.brand.600}",     "$type": "color" }
+"accent":     { "$value": "{color.secondary.500}", "$type": "color" }
+"text-promo": { "$value": "{color.neutral.900}",   "$type": "color" }
@@ semantic-dark @@
+"text-promo": { "$value": "{color.neutral.50}",    "$type": "color" }

Each line should trigger a specific review question:

• space-3, 16px → 14px. A primitive — the change fans out to every consumer. Who reads space-3? If the answer is card padding, list gaps and form rows, does the tightening read as intended in all of them, or was it aimed at one crowded screen? A primitive edited to fix one component is a classic token smell; the targeted fix lives at the component, not in the shared step.
• accent, re-pointed. A semantic — targeted, but load-bearing: which components consume accent, and does the existing on-accent text still clear its contrast floor against the new fill? One line in the diff, a full re-verification behind it. Plus a process question: is this re-pointing what the PR title says the PR does?
• text-promo, added twice. A new role: is it a real job that a second consumer will ever use, or a one-off that belongs closer to its component? Does the name follow the conventions? It appears in both theme sections — good; a light-only semantic is a dark-mode bug on a delay.

Notice what the reviewer never asked: whether the JSON parses. Machines check syntax before the review starts; the reviewer’s entire job is the set of design questions no linter can ask.

Open the file these lines come from in Scale Composer — the canonical tokens file as it lives in a repository, sections in stable order, carrying the same names the diff shows.

What should a token pull request review check?

Four checks cover most of what matters:

1. Blast radius. Which layer changed? A primitive change fans out to everything that references it, directly or through aliases — a one-line edit can be the largest change in the release. A semantic re-pointing is targeted: the consumers of that one role. Read the layer first; it sets the depth the rest of the review needs.
2. Contrast, for every color line. Any changed fill or re-pointed text role means re-verifying the pairings it participates in — one line here, because contrast verification is a discipline of its own; the review is where it gets scheduled.
3. Naming consistency. Check new tokens against the project’s conventions at the last cheap moment: before merge, a rename is a review comment; after merge, it is a breaking change for every consumer.
4. No orphans. A new token should be consumed by something, or it ships as speculation someone will have to name-match later. A deleted token should be referenced by nothing — a dangling {reference} is a failure at the next export, found now or found later.

How do you keep generated diffs readable?

Generated files have a special failure mode in review: if the tool reorders keys or reformats on every save, every diff is a rewrite, and reviewers learn to skim — which is exactly how the Tuesday accent shipped. Three disciplines prevent it:

• Stable serialization. The tool must write the file the same way every time. Scale Composer serializes canonically — stable section order, stable key order; saving, loading and saving again is a tested fixpoint — so a one-value change produces a diff of roughly one line, and forty-one changed lines mean forty-one decisions rather than noise.
• Separate regeneration from hand edits. A commit that re-derives the system (“re-derive after seed change”) and a commit that hand-adds a section call for different review modes — the first is reviewed for its parameters, the second line by line. Mixing them buries judgment inside noise.
• Commit messages that state the decision. “tighten space-3 to 14px — density pass on forms” reads as design rationale a year later; “update tokens” reads as nothing.

One boundary is deliberate: Scale Composer has no diff view. Diffing is git’s job — the tool’s job is to keep the file diffable, which is why canonical serialization is the feature and a diff UI is not.

Put the next change through review

The workflow argues for itself the first time a diff catches something. Retune one value in Scale Composer and export — tighten a spacing step or re-point a role, save over the committed file, and read what git diff shows you: the whole change in a few stable lines, ready for a reviewer’s four questions.