Releases
How the packages are versioned, what counts as breaking, and how to take an update.
Two packages publish publicly to npm from this repo:
| Package | What it ships |
|---|---|
@plainconceptsplatform/ui-theme | Design tokens, CSS only |
@plainconceptsplatform/ui-components | Shared React components |
Both follow semver, with one wrinkle worth stating plainly.
What counts as a breaking change
A token package breaks things in a way types cannot catch. The version reflects visual impact, not just API impact.
| Change | Bump | Why |
|---|---|---|
| Adding a token or a component | minor | Nothing existing moves. |
| Changing a token's value | minor | Every consuming app changes appearance on upgrade, but nothing fails to build. Read the changelog before taking it. |
| Removing or renaming a token | major | Utilities and var() references stop resolving. |
| Changing a component's props | major | Ordinary API break. |
| Neutralising a whole utility scale (for example shadows) | major | Existing markup silently renders differently. |
A minor bump can still change how your app looks. That is the nature of a shared token package: the alternative is calling every palette adjustment a major, which would stop anyone from upgrading. Check the changelog for a "visual change" note.
Taking an update
pnpm up @plainconceptsplatform/ui-theme @plainconceptsplatform/ui-componentsThen look at the app in both light and dark before merging. Token changes are exactly the kind of thing that looks fine in one mode and wrong in the other.
Never fork the theme in an app to avoid an upgrade. If an update is wrong for you, that is a bug worth reporting, because it is probably wrong for the other apps too.
Changelogs
Each package keeps its own, generated from changesets:
How a release happens
Contributors add a changeset describing the change and the bump. Merging to main opens a
"Version Packages" pull request that collects pending changesets into version bumps and changelog
entries. Merging that publishes to npm with provenance.
Nobody publishes from a laptop. See Contributing for the contributor side.
Deprecation
Deprecated tokens and components keep working for at least one minor release, with the replacement named in the changelog. Removal is a major bump. If a deprecation window would be genuinely painful for an app, say so on the pull request rather than pinning an old version.