diff --git a/.changeset/slimy-tips-smash.md b/.changeset/slimy-tips-smash.md
new file mode 100644
index 00000000000..b99b7631d3e
--- /dev/null
+++ b/.changeset/slimy-tips-smash.md
@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Deprecated `heading2xl` and `heading3xl` variants in `Text` component
diff --git a/documentation/Deprecation guidelines.md b/documentation/Deprecation guidelines.md
index 89668d53927..324785cbeb2 100644
--- a/documentation/Deprecation guidelines.md
+++ b/documentation/Deprecation guidelines.md
@@ -42,6 +42,26 @@ Follow these guidelines for deprecating [components](#components), [props](#prop
## Prop values
- Mark the prop value(s) as deprecated
+
+ - Add a console.warn() for deprecated prop value(s) to component
+
+ ```tsx
+ const deprecatedVariants: {[V in Variant]?: Variant} = {
+ heading2xl: 'headingXl',
+ heading3xl: 'headingXl',
+ };
+
+ if (
+ process.env.NODE_ENV === 'development' &&
+ variant &&
+ Object.prototype.hasOwnProperty.call(deprecatedVariants, variant)
+ ) {
+ console.warn(
+ `Deprecation: . The value "${variant}" will be removed in a future major version of Polaris. Use "${deprecatedVariants[variant]}" instead.`,
+ );
+ }
+ ```
+
- Add component, prop, and deprecated prop value(s) to `componentUnionTypeDeprecations` ([example](https://github.com/Shopify/polaris/tree/main/polaris.shopify.com/pages/components/%5Bgroup%5D/%5Bcomponent%5D/index.tsx#L80))
```tsx
const componentUnionTypeDeprecations: {
@@ -55,6 +75,7 @@ Follow these guidelines for deprecating [components](#components), [props](#prop
};
```
- Check documentation is updated on polaris.shopify.com
+
- Create automated migration(s) ([examples](https://github.com/Shopify/polaris/tree/main/polaris-migrator/src/migrations))
- Add supporting documentation for deprecation in next major version guide ([examples](https://github.com/Shopify/polaris/tree/main/polaris.shopify.com/content/version-guides/migrating-from-v11-to-v12.mdx#L122))
- Document deprecation reason
diff --git a/polaris-react/src/components/Text/Text.tsx b/polaris-react/src/components/Text/Text.tsx
index 400caa9f73e..666acf3d7d3 100644
--- a/polaris-react/src/components/Text/Text.tsx
+++ b/polaris-react/src/components/Text/Text.tsx
@@ -47,6 +47,10 @@ type Tone =
type TextDecorationLine = 'line-through';
+const deprecatedVariants: {[V in Variant]?: Variant} = {
+ heading2xl: 'headingXl',
+ heading3xl: 'headingXl',
+};
export interface TextProps {
/** Adjust horizontal alignment of text */
alignment?: Alignment;
@@ -88,6 +92,17 @@ export const Text = ({
visuallyHidden = false,
textDecorationLine,
}: TextProps) => {
+ if (
+ process.env.NODE_ENV === 'development' &&
+ variant &&
+ Object.prototype.hasOwnProperty.call(deprecatedVariants, variant)
+ ) {
+ // eslint-disable-next-line no-console
+ console.warn(
+ `Deprecation: . The value "${variant}" will be removed in a future major version of Polaris. Use "${deprecatedVariants[variant]}" instead.`,
+ );
+ }
+
const Component = as || (visuallyHidden ? 'span' : 'p');
const className = classNames(