When marking APIs, components, or features as deprecated, use consistent JSDoc @deprecated tags with clear alternative guidance. This ensures smooth migration paths for users and maintains backward compatibility during version transitions.

Follow this format:

/** @deprecated [ComponentName] is deprecated, please use [AlternativeName] instead */

Key principles:

Example:

/** @deprecated Please use `iconPlacement` instead */
icon?: React.ReactNode;

/** @deprecated DropdownButton is deprecated, please use Space.Compact + Dropdown + Button instead */

This approach helps maintain library stability while guiding users toward modern APIs and prevents breaking changes from surprising developers during upgrades.