[Typography foundations] Deprecate existing typography components on polaris.shopify.com (#6915)

Author: laurkim

.changeset/grumpy-donuts-agree.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': minor
+---
+
+Deprecated `DisplayText`, `Heading`, `Subheading`, `Caption`, `TextStyle`, and `VisuallyHidden` pages and removed examples

polaris.shopify.com/content/components/caption/index.md

@@ -15,10 +15,18 @@ keywords:
   - time text
   - compact text
   - small text
-examples:
-  - fileName: caption-default.tsx
-    title: Default
-    description: Use to provide details in situations where content is compact and space is tight.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+```diff
+- <Caption>Received April 21, 2017</Caption>
++ <Text variant="bodySm" as="p">Received April 21, 2017</Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/content/components/display-text/index.md

@@ -23,19 +23,41 @@ keywords:
   - visual story telling
   - visual storytelling
   - visual statements
-examples:
-  - fileName: display-text-extra-large.tsx
-    title: Extra large
-    description: Use this size sparingly and never multiple times on the same page.
-  - fileName: display-text-large.tsx
-    title: Large
-    description: Use for display text that’s more important than the medium size, but less important than extra large.
-  - fileName: display-text-medium.tsx
-    title: Medium
-    description: Use for display text that’s more important than the small size, but less important than large.
-  - fileName: display-text-small.tsx
-    title: Small
-    description: Use for text that would otherwise use body text, but that needs to scale with other display text.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+### Small
+
+```diff
+- <DisplayText size="small">Sales this year</DisplayText>
++ <Text variant="headingLg" as="p">Sales this year</Text>
+```
+
+### Medium
+
+```diff
+- <DisplayText size="medium">Sales this year</DisplayText>
++ <Text variant="headingXl" as="p">Sales this year</Text>
+```
+
+### Large
+
+```diff
+- <DisplayText size="large">Sales this year</DisplayText>
++ <Text variant="heading2xl" as="p">Sales this year</Text>
+```
+
+### Extra large
+
+```diff
+- <DisplayText size="extraLarge">Sales this year</DisplayText>
++ <Text variant="heading4xl" as="p">Sales this year</Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/content/components/heading/index.md

@@ -14,10 +14,18 @@ keywords:
   - section headings
   - heading text
   - heading font
-examples:
-  - fileName: heading-default.tsx
-    title: Default
-    description: Use for the title of each top-level page section.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+```diff
+- <Heading>Online store dashboard</Heading>
++ <Text variant="headingMd" as="h2">Online store dashboard</Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/content/components/subheading/index.md

@@ -10,10 +10,18 @@ keywords:
   - titles of sub-sections
   - subsection titles
   - titles of subsections
-examples:
-  - fileName: subheading-default.tsx
-    title: Default
-    description: Used for the title of any sub-sections in top-level page sections.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+```diff
+- <Subheading>Accounts</Subheading>
++ <Text variant="headingXs" as="h3">Accounts</Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/content/components/text-style/index.md

@@ -19,25 +19,55 @@ keywords:
   - decrease
   - input
   - fields
-examples:
-  - fileName: text-style-subdued.tsx
-    title: Subdued
-    description: Use to de-emphasize a piece of text that is less important to merchants than other nearby text. May also be used to indicate when normal content is absent, for example, “No supplier listed”. Don’t use only for aesthetic effect.
-  - fileName: text-style-strong.tsx
-    title: Strong
-    description: Use to mark text representing user input, or to emphasize the totals row in a price table.
-  - fileName: text-style-positive.tsx
-    title: Positive
-    description: Use in combination with a symbol showing an increasing value to indicate an upward trend.
-  - fileName: text-style-negative.tsx
-    title: Negative
-    description: Use in combination with a symbol showing a decreasing value to indicate a downward trend.
-  - fileName: text-style-warning.tsx
-    title: Warning
-    description: Use to denote something that needs attention, or that merchants need to take action on.
-  - fileName: text-style-code.tsx
-    title: Code
-    description: Use to display inline snippets of code or code-like text.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+### Subdued
+
+```diff
+- <TextStyle variation="subdued">No supplier listed</TextStyle>
++ <Text variant="bodyMd" as="span" color="subdued">No supplier listed</Text>
+```
+
+### Strong
+
+```diff
+- <TextStyle variation="strong">No supplier listed</TextStyle>
++ <Text variant="bodyMd" as="span" fontWeight="semibold" >No supplier listed</Text>
+```
+
+### Positive
+
+```diff
+- <TextStyle variation="positive">No supplier listed</TextStyle>
++ <Text variant="bodyMd" as="span" color="success">No supplier listed</Text>
+```
+
+### Negative
+
+```diff
+- <TextStyle variation="negative">No supplier listed</TextStyle>
++ <Text variant="bodyMd" as="span" color="critical">No supplier listed</Text>
+```
+
+### Warning
+
+```diff
+- <TextStyle variation="warning">No supplier listed</TextStyle>
++ <Text variant="bodyMd" as="span" color="warning">No supplier listed</Text>
+```
+
+### Code
+
+```diff
+- <TextStyle variation="code">No supplier listed</TextStyle>
++ <Text variant="bodyMd" as="span"><InlineCode>No supplier listed</InlineCode></Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/content/components/visually-hidden/index.md

@@ -17,13 +17,20 @@ keywords:
   - accessibility
   - a11y
   - assistive technology
-examples:
-  - fileName: visually-hidden-default.tsx
-    title: Default
-    description: Always provide a heading for a major page section such as a card. In rare cases the heading is visually redundant and the meaning is conveyed by context. Rather than omit the heading, wrap the heading in the visually hidden component.
-  - fileName: visually-hidden-table-headers.tsx
-    title: Table headers
-    description: Whenever one or more table columns has no need for a visible header, hide the header content rather than omitting it. Note that due to browser quirks the visually hidden component must go inside each `<th>`.
+status:
+  value: Deprecated
+  message: This component is no longer supported. Please use the Text component instead.
+---
+
+## Mapping to the Text component
+
+```diff
+- <VisuallyHidden>
+-   <Heading>Title and description</Heading>
+- </VisuallyHidden>
++ <Text visuallyHidden variant="bodySm" as="h2">Title and description</Text>
+```
+
 ---
 
 ## Best practices

polaris.shopify.com/pages/components/[component].tsx

@@ -56,8 +56,10 @@ const Components = ({
       <Longform>
         <Markdown text={description} />
         {typedStatus && <StatusBanner status={typedStatus} />}
-        <ComponentExamples examples={examples} />
-        {propsForComponent && <PropsTable props={propsForComponent} />}
+        {Boolean(examples.length) && <ComponentExamples examples={examples} />}
+        {propsForComponent && typedStatus?.value !== 'deprecated' && (
+          <PropsTable props={propsForComponent} />
+        )}
         <Markdown text={readme.body} />
       </Longform>
     </Layout>