Design Token Changelog

A design token changelog documents changes between token versions, helping consumers understand what changed, why it changed, and how to adapt. Well-maintained changelogs build trust with consuming teams and reduce support burden by providing self-service answers to update questions.

What Is a Design Token Changelog

A design token changelog is a documented record of changes to the token system across versions. It typically includes added tokens, removed tokens, modified values, renamed tokens, and any breaking changes that require consumer action.

Changelogs serve both as historical documentation and as practical guidance for teams updating their token dependencies.

How Design Token Changelogs Work

Changelog format typically follows Keep a Changelog conventions:

# Changelog

## [2.3.0] - 2024-01-15

### Added
- `color.status.info` - New informational status color
- `spacing.2xs` - Extra extra small spacing value (2px)

### Changed
- `color.primary` - Updated from #3B82F6 to #2563EB for better contrast

### Deprecated
- `color.brand` - Use `color.primary` instead (removal in v3.0)

### Removed
- `spacing.tiny` - Use `spacing.xs` instead

### Fixed
- `shadow.lg` - Corrected blur value from 15px to 16px

Automated changelog generation from commit history:

# Using conventional commits
npx conventional-changelog -p angular -i CHANGELOG.md -s

Commit messages following conventions become changelog entries:

feat(color): add info status color
fix(shadow): correct lg blur value
BREAKING CHANGE: remove spacing.tiny token

Release notes accompany major versions with additional context:

## v3.0.0 Release Notes

### Migration Guide
This release removes deprecated tokens. Update references before upgrading:
- Replace `color.brand` with `color.primary`
- Replace `spacing.tiny` with `spacing.xs`

### Highlights
- New color contrast improvements across primary palette
- Simplified spacing scale

Key Considerations

• Changelog should accompany every release
• Breaking changes need prominent highlighting
• Migration guidance should be actionable
• Automation reduces manual maintenance
• Consumer-facing language aids understanding
• Version numbers should be clearly associated with changes
• Historical changelogs should remain accessible
• Format should be consistent across releases

Common Questions

How should breaking changes be documented?

Breaking changes require special attention due to their consumer impact.

Clear identification:

## [3.0.0] - 2024-03-01

### BREAKING CHANGES

#### Removed Tokens
The following tokens have been removed. Update your code before upgrading:

| Removed Token | Replacement |
|--------------|-------------|
| `color.brand` | `color.primary` |
| `spacing.tiny` | `spacing.xs` |

#### Renamed Tokens
| Old Name | New Name |
|----------|----------|
| `font.body` | `font.family.body` |

#### Value Changes
Significant value changes that may affect layouts:

| Token | Old Value | New Value |
|-------|-----------|-----------|
| `spacing.base` | 4px | 8px |

Migration scripts reference:

### Automated Migration
Run the following codemod to update references:
\`\`\`bash
npx @company/tokens-codemod v3-migration ./src
\`\`\`

What level of detail should changelogs include?

Detail level balances completeness with readability.

Essential information:

• What changed (token name, property)
• Previous value (for modifications)
• New value
• Reason when not obvious

Good example:

### Changed
- `color.primary` - Updated from #3B82F6 to #2563EB
  - Improves contrast ratio with white backgrounds from 3.2:1 to 4.8:1

Overly terse:

### Changed
- `color.primary` - Updated

Overly verbose:

### Changed
- `color.primary` - After extensive design review and accessibility audit...

Group related changes for readability:

### Changed - Color Palette Updates
Multiple colors updated to meet WCAG AA contrast requirements:
- `color.primary`: #3B82F6 → #2563EB
- `color.secondary`: #6366F1 → #4F46E5
- `color.accent`: #8B5CF6 → #7C3AED

How should changelog automation be configured?

Automation uses commit messages to generate changelog entries.

Conventional commits setup:

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat',    // New tokens
      'fix',     // Token corrections
      'refactor', // Token reorganization
      'docs',    // Documentation
      'chore'    // Build/tooling
    ]]
  }
};

Changelog generation script:

// package.json
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
    "version": "npm run changelog && git add CHANGELOG.md"
  }
}

CI integration:

- name: Generate Changelog
  run: npm run changelog

- name: Commit Changelog
  run: |
    git config user.name "CI Bot"
    git add CHANGELOG.md
    git commit -m "docs: update changelog for ${{ github.ref }}"

Summary

Design token changelogs document changes between versions, providing consumers with information to understand and adapt to updates. Standard formats like Keep a Changelog create consistent structure. Breaking changes require prominent documentation with migration guidance. Automation through conventional commits reduces manual maintenance while ensuring complete records. Well-maintained changelogs build consumer trust and reduce support burden.