Component Stability Index

WHY IT EXISTS A design system is never finished; new components arrive rough and stabilize over time. Without an explicit signal, consumers cannot tell a battle-tested Button from a one-week-old experimental DatePicker, so they either over-trust immature components and suffer breaking changes, or distrust everything and reinvent the wheel. A stability index exists to communicate maturity and expected churn so adoption decisions are informed.

THE MENTAL MODEL Think of it as a label on each component describing the strength of its API contract. Experimental means the API may change without notice; beta means it is largely settled but may shift; stable means breaking changes will follow a deprecation process and major-version discipline; deprecated means it is on a path to removal with a recommended replacement.

HOW IT WORKS Maintainers assign a status to each component, surface it in documentation and often in the type system or runtime warnings, and define what each status promises about versioning. Promotion criteria, such as accessibility audits passed, test coverage, real-world usage, and design sign-off, gate movement from experimental to stable. The status feeds into release notes and migration guides.

WHEN IT MATTERS It matters most in large organizations where many teams depend on the library and need to make risk-aware bets. Product teams shipping critical flows lean on stable components, while early adopters can opt into experimental ones knowing the tradeoff. It also gives maintainers room to iterate publicly without breaking trust.

ONE CONCRETE EXAMPLE A new Combobox ships as experimental with a documented warning that its props may change. Several teams trial it and give feedback; after accessibility and test thresholds are met and the API settles, it is promoted to stable. From then on, any breaking change requires a deprecation period and a major version, so critical product teams can adopt it confidently.