Maturity & lifecycle

Every component, token, pattern and template in PrismDS carries a maturity status so consumers always know what is production-safe. Status is declared in the item's .prompt.md (components) or in COMPONENTS.md / PATTERNS.md (indexes) as a Status: line.

States

Status	Meaning	Safe for production?
experimental	Spike / proof-of-concept. API will change without notice.	No
alpha	Usable, incomplete. Breaking changes likely.	Behind a flag only
beta	Feature-complete, hardening. Breaking changes possible, announced.	Yes, with caution
stable	Locked API, fully documented, a11y-verified.	Yes
deprecated	Superseded; still ships with a migration path. Removed next major.	Migrate away
legacy	Kept for an old product; no new adoption.	Existing use only
internal-only	For Prism's own demos/kits; not part of the public surface.	No

Current snapshot

• Tokens (colours, type, spacing, scales, density, signatures): stable.
• Core / forms / feedback / navigation / overlays / datetime / layout / cards / typography: stable.
• states, data (DataGrid), charts, form-orchestration, lockups, permissions: beta — feature-complete, in real use across the kits, hardening.
• UI kits (CommerceOS, CampusOS, HealthOS, MediaOS, FinanceOS, HospitalityOS): internal-only reference implementations.
• packages/ (@prism/tokens, @prism/ui): alpha — npm distribution is still settling.

Deprecation policy

1. Mark the item deprecated and add a Deprecated: note in its .prompt.md naming the replacement and the version it will be removed in.
2. Keep it shipping, unchanged, for at least one minor release.
3. Remove only in a major release, with a MIGRATION entry.

Migration policy

• Every breaking change ships with a migration note: before/after snippet + a find-and-replace hint where possible.
• Renamed tokens get a temporary alias (--old: var(--new);) for one minor cycle.

Breaking-change policy (semver)

• Patch — fixes, no API/visual change beyond the bug.
• Minor — additive: new components/tokens/props, new optional behaviour. Never removes or renames.
• Major — removals, renames, default-value changes, visual changes that could break layouts.

"Safe for production" checklist

• Status is beta or stable.
• Has .d.ts, .prompt.md, and a @dsCard specimen.
• Passes the QA gates (a11y, RTL, dark, density, long-string).
• No experimental/alpha dependencies.
• Tokens only — no hard-coded colours, sizes or fonts.

Release-readiness checklist

• check_design_system reports no issues.
• README index + relevant docs/ updated.
• Maturity statuses current; deprecations have migration notes.
• packages/ dist rebuilt if tokens/components changed.
• CHANGELOG entry with the semver bump.