[Typography foundations] Add README for new Text component

.changeset/curly-llamas-bathe.md

@@ -3,4 +3,4 @@
 'polaris.shopify.com': major
 ---
 
-Added new `Text` and `InlineCode` components, update `typography` token references in styleguide, and updated `/tokens/typography` page in styleguide to `/tokens/font`
+Added new `Text` and `InlineCode` components, updated `typography` token references in styleguide, updated `/tokens/typography` page in styleguide to `/tokens/font`, add docs and examples for `Text` component

polaris-react/.storybook/polaris-readme-loader.js

@@ -142,6 +142,7 @@ import {
   Subheading,
   Tabs,
   Tag,
+  Text,
   TextContainer,
   TextField,
   TextStyle,

polaris-react/src/components/InlineCode/InlineCode.scss

@@ -1,8 +1,8 @@
 .Code {
-  background-color: var(--p-surface-subdued);
-  border-radius: var(--p-border-radius-base);
-  border: var(--p-border-base);
+  background-color: var(--p-surface-neutral);
+  border-radius: var(--p-border-radius-05);
   font-family: var(--p-font-family-mono);
-  font-size: 0.9em;
-  padding: 0 var(--p-space-1);
+  font-size: 0.85em;
+  font-weight: var(--p-font-weight-medium);
+  padding: var(--p-space-025) var(--p-space-1);
 }

polaris-react/src/components/Text/README.md

@@ -0,0 +1,272 @@
+---
+name: Text
+category: Titles and text
+keywords:
+  - titles
+  - text
+  - typographic
+  - spacing
+  - display
+  - heading
+  - body
+  - success
+  - critical
+  - warning
+  - subdued
+  - regular
+  - medium
+  - semibold
+  - bold
+  - list
+status:
+  value: Alpha
+  message: This component is in development. There could be breaking changes made to it in a non-major release of Polaris. Please use with caution.
+---
+
+# Text
+
+Typography helps establish hierarchy and communicate important content by creating clear visual patterns.
+
+---
+
+## Examples
+
+### Heading small
+
+Use to create a small heading text.
+
+```jsx
+<Text variant="headingSm" as="h6">
+  Online store dashboard
+</Text>
+```
+
+### Heading medium
+
+Use to create a medium heading text.
+
+```jsx
+<Text variant="headingMd" as="h6">
+  Online store dashboard
+</Text>
+```
+
+### Heading large
+
+Use to create a large heading text.
+
+```jsx
+<Text variant="headingLg" as="h5">
+  Online store dashboard
+</Text>
+```
+
+### Heading extra large
+
+Use to create an extra large heading text.
+
+```jsx
+<Text variant="headingXl" as="h4">
+  Online store dashboard
+</Text>
+```
+
+### Heading 2xl
+
+Use to create a 2xl heading text.
+
+```jsx
+<Text variant="heading2xl" as="h3">
+  Online store dashboard
+</Text>
+```
+
+### Heading 3xl
+
+Use to create a 3xl heading text.
+
+```jsx
+<Text variant="heading3xl" as="h2">
+  Online store dashboard
+</Text>
+```
+
+### Heading 4xl
+
+Use to create a 4xl heading text.
+
+```jsx
+<Text variant="heading4xl" as="h1">
+  Online store dashboard
+</Text>
+```
+
+### Body small
+
+Use to create a small body text.
+
+```jsx
+<Text variant="bodySm" as="p">
+  Shopify POS is the easiest way to sell your products in person. Available for
+  iPad, iPhone, and Android.
+</Text>
+```
+
+### Body medium
+
+Use to create a medium body text.
+
+```jsx
+<Text variant="bodyMd" as="p">
+  Shopify POS is the easiest way to sell your products in person. Available for
+  iPad, iPhone, and Android.
+</Text>
+```
+
+### Body large
+
+Use to create a large body text.
+
+```jsx
+<Text variant="bodyLg" as="p">
+  Shopify POS is the easiest way to sell your products in person. Available for
+  iPad, iPhone, and Android.
+</Text>
+```
+
+### With align inherit
+
+Use to inherit parent alignment.
+
+```jsx
+<Text variant="bodyLg" as="p" alignment="inherit">
+  Manage your Shopify store on-the-go with real-time notifications, access to
+  your dashboard, and order management, all from your smartphone.
+</Text>
+```
+
+### With align start
+
+Use to align text at start of horizontal line.
+
+```jsx
+<Text variant="bodyLg" as="p" alignment="start">
+  Manage your Shopify store on-the-go with real-time notifications, access to
+  your dashboard, and order management, all from your smartphone.
+</Text>
+```
+
+### With align center
+
+Use to align text at center of horizontal line.
+
+```jsx
+<Text variant="bodyLg" as="p" alignment="center">
+  Manage your Shopify store on-the-go with real-time notifications, access to
+  your dashboard, and order management, all from your smartphone.
+</Text>
+```
+
+### With align end
+
+Use to align text at end of horizontal line.
+
+```jsx
+<Text variant="bodyLg" as="p" alignment="end">
+  Manage your Shopify store on-the-go with real-time notifications, access to
+  your dashboard, and order management, all from your smartphone.
+</Text>
+```
+
+### With align justify
+
+Use to align text on a vertical line.
+
+```jsx
+<Text variant="bodyLg" as="p" alignment="justify">
+  Manage your Shopify store on-the-go with real-time notifications, access to
+  your dashboard, and order management, all from your smartphone.
+</Text>
+```
+
+### With font weight regular
+
+Use to give text a regular font weight.
+
+```jsx
+<Text variant="bodyMd" as="p" fontWeight="regular">
+  Sales this year
+</Text>
+```
+
+### With font weight medium
+
+Use to give text a medium font weight.
+
+```jsx
+<Text variant="bodyMd" as="p" fontWeight="medium">
+  Sales this year
+</Text>
+```
+
+### With font weight semibold
+
+Use to give text a semibold font weight.
+
+```jsx
+<Text variant="bodyMd" as="p" fontWeight="semibold">
+  Sales this year
+</Text>
+```
+
+### With font weight bold
+
+Use to give text a bold font weight.
+
+```jsx
+<Text variant="bodyMd" as="p" fontWeight="bold">
+  Sales this year
+</Text>
+```
+
+### With color success
+
+Use in combination with a symbol showing an increasing value to indicate an upward trend.
+
+```jsx
+<Text variant="bodyMd" as="p" color="success">
+  Orders increased
+</Text>
+```
+
+### With color critical
+
+Use in combination with a symbol showing a decreasing value to indicate a downward trend.
+
+```jsx
+<Text variant="bodyMd" as="p" color="critical">
+  Orders decreased
+</Text>
+```
+
+### With color warning
+
+Use to denote something that needs attention, or that merchants need to take action on.
+
+```jsx
+<Text variant="bodyMd" as="p" color="warning">
+  Scheduled maintenance
+</Text>
+```
+
+### With color subdued
+
+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.
+
+```jsx
+<Text variant="bodyMd" as="p" color="subdued">
+  No supplier listed
+</Text>
+```
+
+---

polaris-react/src/components/Text/Text.scss

@@ -67,22 +67,6 @@
   font-weight: var(--p-font-weight-bold);
 }
 
-.displaySm {
-  font-size: var(--p-font-size-75);
-  line-height: var(--p-font-line-height-5);
-}
-
-.displayMd {
-  font-size: var(--p-font-size-600);
-  line-height: var(--p-font-line-height-6);
-}
-
-.displayLg {
-  font-size: var(--p-font-size-700);
-  font-weight: var(--p-font-weight-semibold);
-  line-height: var(--p-font-line-height-7);
-}
-
 .headingSm {
   font-size: var(--p-font-size-75);
   line-height: var(--p-font-line-height-1);
@@ -103,6 +87,21 @@
   line-height: var(--p-font-line-height-3);
 }
 
+.heading2xl {
+  font-size: var(--p-font-size-500);
+  line-height: var(--p-font-line-height-5);
+}
+
+.heading3xl {
+  font-size: var(--p-font-size-600);
+  line-height: var(--p-font-line-height-6);
+}
+
+.heading4xl {
+  font-size: var(--p-font-size-700);
+  line-height: var(--p-font-line-height-7);
+}
+
 .bodySm {
   font-size: var(--p-font-size-75);
   line-height: var(--p-font-line-height-1);