Docs / Best practices

Versioning

DESIGN.md supports a version field in the front matter. Treating your design system like software — with a version number and a diff history — prevents silent drift between design and code.

The version field

Add a version key to your front matter using Semantic Versioning (semver). The linter validates that the value is a valid semver string.

---
name: "Pebble Banking"
version: "1.2.0"
colors:
  ...
---

When to bump the version

Change type

Version bump

Example

Breaking — token removed or renamed

Major (1.0.0 → 2.0.0)

Renaming colors.brand to colors.primary

New token added

Minor (1.0.0 → 1.1.0)

Adding a new spacing.2xl token

Value change, same key

Patch (1.0.0 → 1.0.1)

Adjusting a color from #E63946 to #D32F2F

Prose-only update

Patch or none

Editing the Do's and Don'ts section

Breaking changes matter for teams. If multiple people or tools reference your DESIGN.md (e.g., via a shared repository), a major version bump signals that token references in existing code may need updating.

Diffing versions with the CLI

The diff command compares two versions of a DESIGN.md file and reports what changed:

# Compare two committed versions
npx @google/design.md diff [email protected] [email protected]

# Compare the current file against a saved copy
npx @google/design.md diff DESIGN.md.old DESIGN.md

The diff output is structured — it groups changes by token category (colors, typography, spacing, components) and flags:

Added tokens (new keys)
Removed tokens (keys that no longer exist)
Changed values (same key, different value)
Broken token references (a referenced key was removed)

Storing version history in Git

Because DESIGN.md is a plain text file, Git provides full version history for free. The recommended workflow for a breaking change:

# 1. Make changes to DESIGN.md
# 2. Run the linter to verify
npx @google/design.md lint DESIGN.md

# 3. Bump the version in the front matter (major bump for breaking changes)
# version: "1.2.0" → "2.0.0"

# 4. Commit with a descriptive message
git add DESIGN.md
git commit -m "design: v2.0.0 — rename brand tokens to semantic names"

# 5. Tag the release for easy diffing later
git tag design-v2.0.0

Changelog in the file

For teams that want a human-readable changelog inside the file itself, you can add a non-standard ## Changelog section at the bottom of the markdown body. The linter ignores unknown sections — it only validates the front matter and checks that the standard sections contain valid content.

## Changelog

### 2.0.0 — 2026-03-15
Breaking: renamed colors.brand → colors.primary
Breaking: removed colors.light-grey, colors.dark-grey (use text-1, text-2, text-3)
Added: colors.success (#388E3C), colors.error (#D32F2F)

### 1.2.0 — 2026-02-10
Added: spacing.2xl (128px)
Changed: rounded.lg 12px → 16px

### 1.0.0 — 2026-01-20
Initial release.

Naming tokens CLI