docs: Add info to maintaining doc about deprecations

modules/docs/mdx/MAINTAINING.mdx

@@ -27,6 +27,7 @@ Kit!
   - [Canary Releases](#canary-releases)
 - [Codemods](#codemods)
   - [Add a New Codemod](#add-a-new-codemod)
+- [Deprecations](#deprecations)
 
 ## Branches
 
@@ -270,12 +271,13 @@ last release tag. So for example, a V8 canary would look something like this:
 ## Codemods
 
 We use codemods to reduce friction for consumers as they make changes and do upgrades. Codemods are
-accompany major version releases since v5, and can also be released in minor releases if users want to apply some changes sooner.
+accompany major version releases since v5, and can also be released in minor releases if users want
+to apply some changes sooner.
 
 ### Add a New Codemod
 
-Adding a new codemod is pretty straightforward, but this guide will make sure you don't miss any steps
-along the way.
+Adding a new codemod is pretty straightforward, but this guide will make sure you don't miss any
+steps along the way.
 
 First, you need to add a new command to the root CLI. For this example, we'll pretend you're adding
 a new v10 codemod.
@@ -380,3 +382,80 @@ describe('Example Codemod', () => {
 ```
 
 And that's it! You're done. Stage your changes, commit, and push up a PR.
+
+## Deprecations
+
+We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) JSDoc tag to code we plan to remove
+in a future major release. This signals consumers to migrate to a more stable alternative before the
+deprecated code is removed.
+
+Add the `@deprecated` tag to the JSDoc comment directly above all exported declarations you wish to
+deprecate. Create a new JSDoc comment if one doesn't already exist.
+
+```tsx
+/**
+ * ...existing JSDoc comment, if present...
+ *
+ * @deprecated ⚠️ ${Deprecated Name} has been deprecated and will be removed in a future major release. ${Provide a migration strategy}
+ */
+export...
+```
+
+The provided migration strategy can take on any form as long as it gives the consumer a path forward
+once the deprecated code is removed.
+
+For example, we'll deprecate a component in our Main package before replacing it with an updated
+version of the component in our Preview or Labs packages. Note the inclusion of package names
+(Main/Preview/Labs) for disambiguation as well as the optional Storybook link to the updated
+component.
+
+```tsx
+/**
+ * @deprecated ⚠️ Status Indicator in Main has been deprecated and will be removed in a future major release. Please use [Status Indicator in Preview](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) instead.
+ */
+export class StatusIndicator...
+```
+
+Here's an example of a deprecated utility function.
+
+```tsx
+/**
+ * @deprecated ⚠️ `subModelHook` has been deprecated and will be removed in a future major release. Please use `createSubModelElemPropsHook` instead.
+ */
+export const subModelHook...
+```
+
+You may share the same `@deprecation` note for multiple deprecations related to the same component.
+
+```tsx
+/**
+ * @deprecated ⚠️ Status Indicator in Main has been deprecated and will be removed in a future major release. Please use [Status Indicator in Preview](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) instead.
+ */
+export enum StatusIndicatorType...
+
+/**
+ * @deprecated ⚠️ Status Indicator in Main has been deprecated and will be removed in a future major release. Please use [Status Indicator in Preview](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) instead.
+ */
+export interface StatusIndicatorProps...
+
+/**
+ * @deprecated ⚠️ Status Indicator in Main has been deprecated and will be removed in a future major release. Please use [Status Indicator in Preview](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) instead.
+ */
+export class StatusIndicator...
+```
+
+Finally, be sure to notify users of the deprecation in the corresponding
+[Upgrade Guide](https://github.com/Workday/canvas-kit/tree/master/modules/docs/mdx) MDX.
+
+```md
+## Deprecations
+
+...
+
+### ${Deprecated Name}
+
+**PR:** [#${PR number where the deprecation took place}](https://github.com/Workday/canvas-kit/pull/${PR number})
+
+We've deprecated ${Deprecated Name} ${Optional: Include package name to disambiguate (e.g., "from Labs")} ${Provide a
+migration strategy}
+```

modules/labs-react/common/lib/theming/useThemeRTL.ts

@@ -18,9 +18,6 @@ const getConvertedStyles = (
 };
 
 /**
- * @deprecated Now that IE11 is no longer supported, we encourage consumers to use [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
- *
- *
  * A helpful hook for supporting bidirectional styles.
  * * Read below for more detail or [view the docs](https://github.com/Workday/canvas-kit/blob/master/modules/labs-react/common/README.md#useThemeRTL).
  *
@@ -48,6 +45,8 @@ const getConvertedStyles = (
  *
  *   return <span css={errorTextStyles} {...props} />;
  * }
+ *
+ * @deprecated ⚠️ `useThemeRTL` has been deprecated and will be removed in a future major version. Now that IE11 is no longer supported, we encourage consumers to use [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties).
  */
 export function useThemeRTL() {
   const theme = useTheme();

modules/preview-react/menu/lib/Menu.tsx

@@ -7,12 +7,7 @@ import {commonColors, space, borderRadius} from '@workday/canvas-kit-react/token
 import {hideMouseFocus, GrowthBehavior, generateUniqueId} from '@workday/canvas-kit-react/common';
 
 /**
- * ### Deprecated Menu
- *
- * As of Canvas Kit v8, Menu is being deprecated.
- * It will be removed in v10. Please see the
- * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
- * for more information.
+ * @deprecated ⚠️ `DeprecatedMenuProps` has been deprecated and will be removed in a future major version. Please use [Menu in Main](https://workday.github.io/canvas-kit/?path=/docs/components-popups-menu--basic) instead.
  */
 export interface DeprecatedMenuProps
   extends GrowthBehavior,
@@ -55,12 +50,8 @@ export interface DeprecatedMenuProps
 }
 
 /**
- * ### Deprecated Menu State
  *
- * As of Canvas Kit v8, Menu is being deprecated.
- * It will be removed in v10. Please see the
- * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
- * for more information.
+ * @deprecated ⚠️ `DeprecatedMenuState` has been deprecated and will be removed in a future major version. Please use [Menu in Main](https://workday.github.io/canvas-kit/?path=/docs/components-popups-menu--basic) instead.
  */
 export interface DeprecatedMenuState {
   selectedItemIndex: number;
@@ -78,19 +69,14 @@ const List = styled('ul')({
 });
 
 /**
- * As of Canvas Kit v8, Menu is being deprecated.
- * It will be removed in v10. Please see the [upgrade
- * guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page) for
- * more information.
- *
  * `DeprecatedMenu` renders a styled `<ul role="menu">` element within a {@link Card} and follows
  * the [Active Menu
  * pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/examples/menu-button-actions-active-descendant/)
  * using `aria-activedescendant`.
  *
  * Undocumented props are spread to the underlying `<ul>` element.
  *
- * @deprecated
+ * @deprecated ⚠️ Deprecated Menu has been deprecated and will be removed in a future major version. Please use [Menu in Main](https://workday.github.io/canvas-kit/?path=/docs/components-popups-menu--basic) instead.
  */
 export class DeprecatedMenu extends React.Component<DeprecatedMenuProps, DeprecatedMenuState> {
   private id = generateUniqueId();

modules/preview-react/menu/lib/MenuItem.tsx

@@ -12,12 +12,7 @@ import {CanvasSystemIcon} from '@workday/design-assets-types';
 import {SystemIcon, SystemIconProps} from '@workday/canvas-kit-react/icon';
 
 /**
- * ### Deprecated Menu Item Props
- *
- * As of Canvas Kit v8, Menu is being deprecated.
- * It will be removed in v10. Please see the
- * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
- * for more information.
+ * @deprecated ⚠️ `DeprecatedMenuItemProps` has been deprecated and will be removed in a future major version. Please use [Menu in Main](https://workday.github.io/canvas-kit/?path=/docs/components-popups-menu--basic) instead.
  */
 export interface DeprecatedMenuItemProps extends React.LiHTMLAttributes<HTMLLIElement> {
   /**
@@ -262,14 +257,10 @@ const scrollIntoViewIfNeeded = (elem: HTMLElement, centerIfNeeded = true): void
  * - `tabindex={-1}`
  * - `id`s following this pattern: `${MenuId}-${index}`
  *
- * As of Canvas Kit v8, Menu is being deprecated.
- * It will be removed in v10. Please see the [upgrade
- * guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page) for
- * more information.
- *
  * Undocumented props are spread to the underlying `<li>` element.
  *
- * @deprecated
+ * @deprecated ⚠️ `DeprecatedMenuItem` has been deprecated and will be removed in a future major version. Please use [Menu in Main](https://workday.github.io/canvas-kit/?path=/docs/components-popups-menu--basic) instead.
+ *
  */
 export class DeprecatedMenuItem extends React.Component<DeprecatedMenuItemProps> {
   ref = React.createRef<HTMLLIElement>();

modules/preview-react/text-input/lib/hooks/useTextInputModel.ts

@@ -1,4 +1,4 @@
 import {useFormFieldModel} from '@workday/canvas-kit-preview-react/form-field';
 
-/** @deprecated Please use `useFormFieldModel` instead */
+/** @deprecated ⚠️ `useTextInputModel` is deprecated and will be removed in a future major version. Please use `useFormFieldModel` instead. */
 export const useTextInputModel = useFormFieldModel;

modules/react/common/lib/utils/components.ts

@@ -388,7 +388,7 @@ export const createSubcomponent = <
   elemPropsHook,
   subComponents,
 }: {
-  /** @deprecated You no longer need to use displayName. A `displayName` will be automatically added if it belongs to a container */
+  /** @deprecated ⚠️ `displayName` has been deprecated and will be removed in a future major version. You no longer need to use `displayName`. A `displayName` will be automatically added if it belongs to a container. */
   displayName?: string;
   modelHook: TModelHook;
   elemPropsHook?: TElemPropsHook;
@@ -661,7 +661,7 @@ export const createHook = <M extends Model<any, any>, PO extends {}, PI extends
 };
 
 /**
- * @deprecated use `createSubModelElemPropsHook` instead
+ * @deprecated ⚠️ `subModelHook` has been deprecated and will be removed in a future major version. Please use `createSubModelElemPropsHook` instead.
  */
 export const subModelHook = <M extends Model<any, any>, SM extends Model<any, any>, O extends {}>(
   fn: (model: M) => SM,

modules/react/common/lib/utils/models.ts

@@ -2,7 +2,7 @@
 import React from 'react';
 
 /**
- * @deprecated The returned model is now inferred from `createModelHook`
+ * @deprecated ⚠️ `Model` has been deprecated and will be removed in a future major version. The returned model is now inferred from `createModelHook`.
  */
 export type Model<State, Events extends IEvent> = {
   state: State;
@@ -64,7 +64,7 @@ type ToCallbackConfig<
  *   id?: string
  * } & Partial<ToModelConfig<State, Events, typeof eventMap>>
  *
- * @deprecated `createModelHook` now infers the config type
+ * @deprecated ⚠️ `ToModelConfig` has been deprecated and will be removed in a future major version. Please use `createModelHook` instead since it infers the config type.
  */
 export type ToModelConfig<
   TState extends Record<string, any>,
@@ -97,7 +97,7 @@ export type ToModelConfig<
  *   }
  * })
  *
- * @deprecated `createModelHook` uses Template Literal Types to create event map types
+ * @deprecated ⚠️ `createEventMap` has been deprecated and will be removed in a future major version. Please use `createModelHook` instead. It uses Template Literal Types to create event map types.
  */
 export const createEventMap = <TEvents extends IEvent>() => <
   TGuardMap extends Record<string, keyof TEvents>,
@@ -131,7 +131,7 @@ const keys = <T extends object>(input: T) => Object.keys(input) as (keyof T)[];
  *     }
  *   }
  * })
- * @deprecated Use `createModelHook` instead
+ * @deprecated ⚠️ `useEventMap` has been deprecated and will be removed in a future major version. Please use `createModelHook` instead.
  */
 export const useEventMap = <
   TEvents extends IEvent,

modules/react/common/lib/utils/useUniqueId.ts

@@ -32,8 +32,7 @@ export const useUniqueId = (id?: string) => {
 
 /**
  * Backwards-compatible change to converting to hook
- * @deprecated
- * TODO: Remove in major release
+ * @deprecated ⚠️ `uniqueId` has been deprecated and will be removed in a future major version. Please use `useUniqueId` instead.
  */
 export const uniqueId = useUniqueId;
 

modules/react/status-indicator/lib/StatusIndicator.tsx

@@ -6,9 +6,7 @@ import {borderRadius, colors, type, space, CSSProperties} from '@workday/canvas-
 import styled from '@emotion/styled';
 
 /**
- * ### ⚠️ Status Indicator has been deprecated and will be removed in v11 ⚠️
- * - Please consider using [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in preview
- * @deprecated
+ * @deprecated ⚠️ Status Indicator has been deprecated and will be removed in a future major version. Please use [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in Preview instead.
  */
 export enum StatusIndicatorType {
   Gray = 'gray',
@@ -20,19 +18,15 @@ export enum StatusIndicatorType {
 }
 
 /**
- * ### ⚠️ Status Indicator has been deprecated and will be removed in v11 ⚠️
- * - Please consider using [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in preview
- * @deprecated
+ * @deprecated ⚠️ Status Indicator has been deprecated and will be removed in a future major version. Please use [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in Preview instead.
  */
 export enum StatusIndicatorEmphasis {
   High = 'high',
   Low = 'low',
 }
 
 /**
- * ### ⚠️ Status Indicator has been deprecated and will be removed in v11 ⚠️
- * - Please consider using [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in preview
- * @deprecated
+ * @deprecated ⚠️ Status Indicator has been deprecated and will be removed in a future major version. Please use [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in Preview instead.
  */
 export interface StatusIndicatorGenericStyle extends GenericStyle {
   styles: CSSProperties;
@@ -44,9 +38,7 @@ export interface StatusIndicatorGenericStyle extends GenericStyle {
 }
 
 /**
- * ### ⚠️ Status Indicator has been deprecated and will be removed in v11 ⚠️
- * - Please consider using [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in preview
- * @deprecated
+ * @deprecated ⚠️ Status Indicator has been deprecated and will be removed in a future major version. Please use [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in Preview instead.
  */
 export const statusIndicatorStyles: StatusIndicatorGenericStyle = {
   classname: 'status-indicator',
@@ -126,9 +118,7 @@ export const statusIndicatorStyles: StatusIndicatorGenericStyle = {
 };
 
 /**
- * ### ⚠️ Status Indicator has been deprecated and will be removed in v11 ⚠️
- * - Please consider using [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in preview
- * @deprecated
+ * @deprecated ⚠️ Status Indicator has been deprecated and will be removed in a future major version. Please use [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in Preview instead.
  */
 export interface StatusIndicatorProps extends React.HTMLAttributes<HTMLSpanElement> {
   /**
@@ -172,9 +162,7 @@ const StatusLabel = styled('span')({
 });
 
 /**
- * ### ⚠️ Status Indicator has been deprecated and will be removed in v11 ⚠️
- * - Please consider using [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in preview
- * @deprecated
+ * @deprecated ⚠️ Status Indicator has been deprecated and will be removed in a future major version. Please use [`Status Indicator`](https://workday.github.io/canvas-kit/?path=/docs/preview-status-indicator--basic) in Preview instead.
  */
 export class StatusIndicator extends React.Component<StatusIndicatorProps> {
   public static Type = StatusIndicatorType;

modules/react/tabs/lib/Tabs.tsx

@@ -112,7 +112,7 @@ export const Tabs = createContainer()({
      */
     OverflowButton: TabsOverflowButton,
     /**
-     * @deprecated Use `Tabs.Menu.Popper` instead
+     * @deprecated ⚠️ `MenuPopper` has been deprecated and will be removed in a future major version. Please use `Tabs.Menu.Popper` instead.
      */
     MenuPopper: TabsMenuPopper,
     /**