When Northwind released version 3.4.0 of its UI package, eleven teams’ builds failed the next morning. The release notes said “minor improvements”. One of those improvements renamed the --nw-color-text-light token, because the team had (correctly) decided the name was misleading. It was a good change released under the wrong number, and it cost us more trust than any bug that year. Versioning is how a design system makes promises to its consumers, and broken promises are expensive.
Semantic versioning gives every release a number MAJOR.MINOR.PATCH. A patch (4.7.2 → 4.7.3) fixes bugs without changing the public API. A minor (4.7.2 → 4.8.0) adds functionality in a backward-compatible way. A major (4.7.2 → 5.0.0) contains changes that can break existing usage. Package managers rely on this: a dependency written as ^4.7.2 accepts any 4.x.x from 4.7.2 upward, but never 5.0.0. Before 1.0.0, anything may change at any time, so a system that teams depend on should reach 1.0 early.
Semver means nothing until you’ve written down what “the public API” is. For Northwind UI it is:
\ndata-variant, data-size and the component tokens;Anything not on that list, such as internal class names, the DOM nesting inside a component, or private helpers, can change in any release. Write the list in your docs, and tell teams plainly that depending on undocumented internals is at their own risk.
\nWith the API defined, most decisions become mechanical:
\n| Change | \nBump | \n
|---|---|
| Fix Dialog not returning focus on close | \nPatch | \n
Add a loading prop to Button | \nMinor | \n
| Add a new Tabs component or a new token | \nMinor | \n
| Refine a token’s value within the same role | \nMinor, with a note and visual diffs | \n
| Rename or remove a token, prop or component | \nMajor | \n
| Change a default, such as Button’s default variant | \nMajor | \n
Two rows deserve a comment. Changing a default is major because code that relied on the default now renders differently without a single line changing. And value refinements are minor because the token’s contract is its role, not its exact color; if “subtle text” gets slightly darker to pass contrast, every screen that used it still gets subtle text. Treat those as design updates: call them out in the changelog with before-and-after images, because teams with screenshot tests will see their baselines change.
\n\nRemembering the right bump at release time doesn’t scale across many contributors. Northwind uses Changesets: every pull request that changes a package adds a small file stating the bump type and a summary written for consumers.
\n---\n\"@northwind/ui\": minor\n---\n\nButton: add a `loading` prop. While loading, the button keeps its width, sets `aria-busy`, and ignores clicks.When a release is cut, the tool takes the highest bump among pending changesets, updates the version, and turns the summaries into CHANGELOG.md. Here is the same logic in miniature:
const order = { patch: 0, minor: 1, major: 2 };\n\nfunction nextVersion(current, changes) {\n const [major, minor, patch] = current.split('.').map(Number);\n const bump = changes.reduce((top, c) => (order[c.bump] > order[top] ? c.bump : top), 'patch');\n if (bump === 'major') return `${major + 1}.0.0`;\n if (bump === 'minor') return `${major}.${minor + 1}.0`;\n return `${major}.${minor}.${patch + 1}`;\n}\n\nconst pending = [\n { bump: 'patch', summary: 'Dialog returns focus to its trigger on close.' },\n { bump: 'minor', summary: 'Button: add a `loading` prop.' },\n];\nconsole.log(nextVersion('4.7.2', pending));\nconsole.log(nextVersion('4.7.2', [...pending, { bump: 'major', summary: 'Remove Button `kind`.' }]));A good changelog groups entries by impact (breaking, added, fixed), is written for the people upgrading, and gives every breaking entry its migration steps. “Refactored Button internals” tells a product team nothing; “Button kind removed, use variant, a codemod is available” tells them exactly what to do.
In the exercise, you assign version numbers to a batch of changes. Next, you plan how to remove things without breaking forty teams in one morning.
\n","toc":[{"id":"sec-1","text":"Semver in one paragraph","level":2},{"id":"sec-2","text":"Define your public API first","level":2},{"id":"sec-3","text":"Classifying real changes","level":2},{"id":"sec-4","text":"Changesets and changelogs","level":2}],"takeaways":["Semver only works when you have written down what your public API is; for a design system that includes component props, exported names, token names and documented CSS hooks.","Removing or renaming anything public, or changing a default, is a major change, even when it feels small.","Adding props, components or tokens is minor; fixing behavior to match the documentation is a patch.","A changelog is written for consumers, grouped by impact, and every breaking entry includes migration steps."],"further":[{"title":"About semantic versioning (npm Docs)","url":"https://docs.npmjs.com/about-semantic-versioning"},{"title":"Semantic Versioning specification (source)","url":"https://github.com/semver/semver/blob/master/semver.md"},{"title":"Changesets (official repository)","url":"https://github.com/changesets/changesets"}],"quiz":[{"q":"@northwind/ui is at 4.7.2. A release removes the deprecated kind prop from Button (replaced by variant in 4.3.0). What’s the next version?
kind breaks when it disappears."},{"text":"4.8.0, because only one prop changed.","why":"The number of changes doesn’t matter; any removal from the public API is breaking."},{"text":"5.0.0, because removing a public prop breaks code that still uses it.","why":"Correct. Removals belong in a major release, ideally batched with other planned removals."}],"answer":2},{"q":"Northwind darkens --nw-color-text-subtle slightly so it passes contrast in dark mode. The name and role stay the same. How should it be released?
Which changelog entry is most useful to a product team?
","options":[{"text":"“Refactored Button internals and cleaned up styles.”","why":"It describes the maintainers’ work, not what changes for the consumer or whether they need to act."},{"text":"“Bumped dependencies.”","why":"Accurate but empty; it doesn’t say whether anything visible or behavioral changed."},{"text":"“Various fixes and improvements.”","why":"It forces every team to read the diff to find out whether they’re affected."},{"text":"“Breaking: Buttonkind prop removed. Replace kind="primary" with variant="primary", or run the codemod nw-codemods button-kind.”","why":"Correct. It says what changed, who is affected, and exactly how to migrate."}],"answer":3}],"exercise":{"kind":"fill","language":"text","template":"@northwind/ui is at 4.7.2. Each line is a separate release from 4.7.2.\n\nFix: Dialog now returns focus to its trigger on close -> {{0}}\nAdd a `loading` prop to Button -> {{1}}\nRemove the old token name --nw-color-text-light -> {{2}}\nChange Button's default variant from \"primary\" to \"secondary\" -> {{3}}\nA Dialog focus fix plus a new Tabs component -> {{4}}\nDarken --nw-color-text-subtle slightly (same name and role) -> {{5}}","blanks":[{"answers":["4.7.3"]},{"answers":["4.8.0"]},{"answers":["5.0.0"]},{"answers":["5.0.0"]},{"answers":["4.8.0"]},{"answers":["4.8.0"]}],"title":"Number the releases","prompt":"Apply Northwind’s versioning policy from the lesson. Each line is its own release starting from 4.7.2. Write the full next version number for each one, such as 4.7.3.
The focus fix restores documented behavior, so it’s a patch (4.7.3). A new prop is a backward-compatible addition (4.8.0). Removing a token name breaks anyone still using it, and changing a default changes rendering without any code change, so both are majors (5.0.0). A release mixing a fix and a new component takes the higher bump, minor (4.8.0). A value refinement that keeps the token’s name and role is a minor design update (4.8.0), shipped with a changelog note and visual diffs.
\n","checkLabels":{}},"words":689,"readMinutes":3}