Versioning
Each system has its own version, changelog and release tag. The version tells people what an upgrade will cost them, and the changelog tells them what changed.
Version numbers
Section titled “Version numbers”Versions follow Semantic Versioning: MAJOR.MINOR.PATCH.
| Bump | When |
|---|---|
| MAJOR | Something that worked before stops working |
| MINOR | Something new is added and everything old still works |
| PATCH | A fix that changes nothing else |
While the major version is 0, anything may change in any release; 1.0.0 is the point where the public API is promised to stay stable.
A design system’s public API is everything other code depends on: token names and the CSS custom properties built from them, the files the package exports, and component props and events. Renaming or removing any of them is a major change. Adding one is a minor change. Changing a token’s value breaks no code but changes what people see, so it goes in the changelog under Changed and ships in at least a minor release.
Changelog
Section titled “Changelog”Each system keeps a CHANGELOG.md in the Keep a Changelog format:
- Newest version first, with an
Unreleasedsection at the top for changes that have not shipped - One heading per version with its date:
## [0.1.0] - 2026-10-25 - Changes grouped as Added, Changed, Deprecated, Removed, Fixed and Security
- Written for the people using the system, not copied from commit messages
Commit messages
Section titled “Commit messages”Commits follow Conventional Commits: type(scope): description, for example feat(personal-website): add a dark theme. A feat commit points to a minor release, a fix to a patch, and a ! after the type or a BREAKING CHANGE: footer to a major one.
Deprecation
Section titled “Deprecation”Remove nothing without warning first:
- Mark the token with
$deprecatedin its DTCG file. It can betrueor a sentence explaining why and what to use instead. - Say so in the docs and under Deprecated in the changelog, naming the replacement.
- Remove it in the next major release, under Removed.
Releases in this repository
Section titled “Releases in this repository”A tag named <system>-v<version>, such as personal-website-v0.1.0, publishes that system as a GitHub Release with the package attached and that version’s changelog section as its notes.
Source
Section titled “Source”Semantic Versioning 2.0.0, Keep a Changelog 1.1.0, Conventional Commits 1.0.0 and the $deprecated property in the DTCG Format.