Versioning.

Version numbers

Releases follow semantic versioning. Until 1.0, minor versions may break things; the changelog says how to update.

From 1.0 on, these changes need a major version:

• renaming or removing a CSS class, a token, or an Astro component prop;
• changing what a token means (moving --ply-color-accent from fills to text, for example);
• reordering the categorical chart colors, which would repaint every existing figure.

Changing a token's value is a minor version when its meaning holds. Fixing contrast or a bug is a patch.

Stability labels

Each component page carries one of three labels:

• Stable safe to use; changes follow the rules above.
• Experimental may change in any minor version.
• Deprecated still works, with a named replacement and a removal version.

When something joins the kit

Build new parts in the project that needs them, using the tokens. Move a part into the kit when a second project needs it. Before it moves, it needs:

• a page in these docs with a live example, the HTML, and the Astro usage;
• light and dark checked, keyboard focus visible, and contrast passing npm run check:contrast;
• no hard-coded colors or sizes: only tokens.

Releasing

npm run build && git add dist   # installs read dist/ as committed
npm version minor               # bumps package.json and tags
git push --follow-tags
gh release create v0.6.3        # publishing the release sends it to npm and PyPI

Update python/pyproject.toml to the same version first, so both halves of the kit move together. The release workflow publishes through trusted publishing, so no tokens are stored anywhere, and npm attaches a provenance record that ties each version to the commit it was built from.