Versioning And Stability
The design system uses semver through Changesets.
Package Stability
| Status | Meaning |
|---|---|
stable | Production API. Breaking changes require migration notes. |
beta | Usable, but API can change in a minor release before 1.0. |
experimental | Trial surface. Do not build critical flows on it without owner approval. |
deprecated | Still present, but migration is expected. |
Semver Rules
| Change | Bump |
|---|---|
| New component | minor before 1.0, minor after 1.0 |
| New prop with backward-compatible default | minor |
| Bug fix with same API | patch |
| Visual fix preserving documented behavior | patch |
| Token value change with visible impact | minor before 1.0; major after 1.0 if breaking |
| Removed/renamed prop | minor before 1.0; major after 1.0 |
| AI-UI descriptor schema change | minor before 1.0; major after 1.0 if breaking |
| MCP new tool | minor before 1.0; minor after 1.0 |
| MCP request/response contract change | minor before 1.0; major after 1.0 |
| Agent skill behavior change | docs change unless packaged; version if distributed as package |
Changeset Required
Add a changeset when changing any publishable package:
@mihcm/ui@mihcm/theme@mihcm/tokens@mihcm/icons@mihcm/ai-ui@mihcm/cli@mihcm/mcp@mihcm/eslint-config
No changeset is required for docs-only changes unless they ship in a package.
Deprecation Policy
When deprecating:
- mark the docs page;
- add migration guidance;
- keep the old API for at least one minor release before 1.0 when practical;
- add tests for the migration path when code behavior changes.
Release Notes
Every release should answer:
- what changed;
- who is affected;
- whether migration is needed;
- whether security posture changed;
- whether MCP, skills, or AI-UI descriptors changed.