Deprecation Guidance

This page outlines general guidance for deprecating and removing components, component APIs (property, method, slot, event, etc.), and design tokens.

General guidance

Deprecations should:

• Clearly communicate what is changing
• Provide a migration path when possible
• Include both the deprecation version and removal target version
• Be documented consistently across implementation, documentation, and release notes

Deprecation notices

There are two ways to document deprecations, depending on the API reference. In both cases a deprecated chip will be displayed in the SDK site within the component's API reference section.

• Properties, events, and methods: The @deprecated JSDoc tag is used for JavaScript properties, events, and methods in the <component-name>.tsx file. Notes can accompany the JSDoc tag, such as "use <property> instead".
• Slots and Design tokens: The [Deprecated] text is added at the beginning of the JSDoc description for slots (@slots) in a <component-name>.tsx file and design tokens in a <component-name>.scss file. The text is parsed and removed from the description in the SDK site.

Deprecation and removal versions must be included when documenting deprecations in the following formats:

• @deprecated in v2.0.0, removal target v3.0.0 - Use the <property|event|method> instead.
• [Deprecated] in v2.0.0, removal target v3.0.0 - Use the <slot|token> instead.

Recommended removal timelines

These are general guidelines and may vary depending on impact, migration complexity, and user feedback.

Type	Recommended support window
Components	At least 2 major release cycles
Component API	Closest or next major release depending on deprecation timing
Design tokens	1 to 2 major release cycles depending on impact

Example removal targets

Deprecated item	Deprecated in	Example removal target	Notes
Component	5.0	7.0	Components should generally remain available for at least 2 major release cycles
Component API	5.0	6.0	APIs are typically removed in the closest or next major release depending on timing and impact
Design token	4.0	5.0 or 6.0	Token removals depend on migration impact and adoption