Design-Token Changes Need a Changelog (or RFC), Not Only Figma

I used to treat Figma as the source of truth for design tokens. Update the color, publish the library, ping eng in Slack. That worked until three teams shipped the same week with three different meanings of “primary.”

Figma showed the new value. Nobody owned the migration story. Half the codebase still imported the old name. Reviews turned into archaeology.

So I started treating token changes like API changes. Same discipline: a short changelog, and for anything breaking, a tiny RFC before the paint hits production.

Why Figma alone isn’t enough

Figma is great at what it looks like. It’s weak at:

• Who consumes this? Mobile, web, email, a Storybook that still hard-codes hex
• What breaks if we rename? color.brand.500 → color.brand.primary is a find-and-replace tax across packages
• When do we cut over? Soft alias for two sprints, or big-bang rename on Friday
• What do we tell QA? Contrast changed on dark mode; screenshot diffs will scream

Designers aren’t supposed to write migration plans in a comment thread. That’s on us — frontend owns the contract between tokens and code.

What I put in a token changelog

Keep it boring and scannable. One entry per change, in the repo (not only Slack):

## 2026-10-20

### Changed
- `color.text.muted`: `#6B7280` → `#4B5563` (darker for AA on white)
  - Migration: none (same token name)
  - Risk: screenshot diffs in empty states
  - Owners: design + web a11y

### Deprecated
- `spacing.cardPadding` → use `spacing.4` (alias kept until 2026-11-15)
  - Call sites: ~40 in `packages/ui`
  - Codemod: `scripts/tokens/rename-card-padding.ts`

Rules that stuck:

1. Name + old → new + why in one line
2. Migration path even when it’s “none”
3. Expiry date on every alias / deprecation
4. Link the PR that updates the token package, not a Figma version number alone

If the change is “we added a new token,” still log it. Future-you will ask when color.success.subtle showed up.

When I open a tiny RFC instead

Changelog is enough for safe tweaks (same name, better contrast, new optional token).

I write a short RFC when any of these are true:

• Rename or remove a token used outside one package
• Semantic meaning shifts (e.g. primary stops meaning “CTA” and starts meaning “brand accent”)
• Cross-platform (web + iOS + Android need the same cutover)
• AI / codegen will rewrite call sites — then the RFC is the constraint list for the agent

My RFC template is one page max:

1. Problem — what hurts today
2. Proposal — new names / values / aliases
3. Migration — steps, codemod, alias window
4. Non-goals — what we’re not redesigning this week
5. Rollback — how we undo if contrast or brand complains

No essays. If it needs a slide deck, the change is too big for a token PR.

How this plays with AI in the workflow

Agents love renaming tokens. They will “clean up” gray.400 into three new semantic names without asking who still uses the old ones.

I paste the RFC (or the changelog entry) into the agent prompt and say:

Only edit call sites listed in Migration. Do not invent new token names. Do not delete aliases before the expiry date.

That one paragraph has saved more review time than any fancy prompt about “follow the design system.”

Human still merges. The changelog is the audit trail when someone asks “why did empty-state text get darker last Tuesday?”

A lightweight loop that actually ships

1. Designer proposes the visual change in Figma (still required).
2. Frontend drafts the changelog entry before merging the token package.
3. If breaking → 1-page RFC, async approval from design + one eng per consumer app.
4. Ship alias + codemod (or none) with the PR.
5. Delete the alias on the expiry date — calendar reminder, not vibes.

Figma remains where we see the system. The changelog/RFC is where we own the contract.

If your team still ships token renames only via a Figma library bump, try one changelog for the next change. The first time QA can point at a dated entry instead of a Slack scrollback, you’ll keep the habit.