Version control for design systems: lessons from software

In most engineering teams, it's unthinkable to change production code without a commit message, a diff and a way to roll back. In most design teams, the brand primary color can change in a Figma file on a Tuesday afternoon with no record at all. The asymmetry is strange, because the consequences are similar: a color change can touch hundreds of screens.

Lesson 1: every change needs a reason

Good commit messages explain why, not what — the diff already shows what. The same applies to palettes. '#1D5563 → #1F4E5A' is a diff. 'Darkened primary for AA compliance on small-text links' is a reason. Six months later, only the second one prevents someone from reverting it.

Lesson 2: separate spec from working state

Git distinguishes between committed history and your working directory. Palettos borrows this: each role has a spec value (what was last approved) and a current value (what you're experimenting with). When they differ, that's drift, and the interface says so. You either commit the change with a reason or revert it.

Lesson 3: semantic versioning maps surprisingly well

• Patch (1.0.x): a value adjustment within the same intent — slightly darker primary for contrast.
• Minor (1.x.0): a new role or ramp added without breaking existing ones.
• Major (x.0.0): roles renamed or removed, or a rebrand that changes identity.

If a consumer of your tokens needs to change their code, it's a major version. If they don't, it isn't.

Lesson 4: diffs should be visual

A text diff of hex values is nearly useless to a designer. Palettos shows diffs as before/after swatches per role, which is how humans actually evaluate color changes.

Lesson 5: know your dependents

Package managers know which projects depend on a library. The design-system equivalent is a usage map: which screens and components use which roles. It turns 'can we change the accent?' from a guess into a lookup.

None of this requires heavyweight tooling. It requires the habit of writing things down at the moment of change — which is exactly the moment when you still remember why.