Component Lifecycle
Every Sitka component carries a lifecycle badge — Alpha, Beta, Stable, or Deprecated. The badge tells you how stable the API is, what testing has been done, and whether it's safe to ship.
Lifecycle stages
Experimental — API will change
- →Component exists in code but API is not final
- →Not covered by semver guarantees
- →May be removed without a deprecation period
- →Feedback actively sought from early adopters
Internal projects and prototypes only. Do not ship to production.
Stable API, gathering real-world feedback
- →API is stable — no breaking changes without a major version bump
- →Core use cases are tested
- →Documentation is complete but may be updated
- →Accessibility review is in progress or complete
Safe to ship to production with the expectation of minor updates.
Production-ready, fully supported
- →Full test coverage across platforms (React, HTML, SwiftUI)
- →WCAG 2.1 AA accessibility audit passed
- →Token pipeline verified
- →Complete doc page: Preview, States, Motion, Implementation, Props, ARIA, Keyboard, Accessibility
The default state for all shipped components. Breaking changes require a semver major.
Scheduled for removal — migrate now
- →A successor component or pattern exists
- →Migration guide is published on the component page
- →Component remains functional for at least one major version
- →All internal usages have been updated or scheduled
Stop using in new code. Migrate existing usages to the recommended replacement before the next major version.
Promotion criteria
| Transition | Required before promoting |
|---|---|
| Alpha → Beta | API design review, one real product adoption, basic test coverage |
| Beta → Stable | Full accessibility audit, complete doc page, token pipeline, design sign-off |
| Stable → Deprecated | Successor identified, migration guide written, removal version set |
| Deprecated → Removed | All internal usages migrated, one full major version has passed since deprecation |
Changelog convention
Deprecations and removals must be recorded in CHANGELOG.md with the successor component and removal target version.
## [2.0.0] - 2026-08-01
### Deprecated
- **OldButton**: use Button variant="primary" instead.
Migration: replace <OldButton> with <Button>.
Removal target: v3.0.
### Removed
- **LegacyCard**: deprecated in v1.x. Use Card + CardHeader.
Semver policy
- →Patch (x.x.N): bug fixes and visual tweaks that don't change props or tokens.
- →Minor (x.N.0): new components, new props, new tokens — all backwards-compatible.
- →Major (N.0.0): breaking changes to existing props, removed components, token renames.
- →Alpha components are excluded from semver — they can break in any release.
- →Beta components follow semver for breaking changes only from the point they're labelled Beta.