[polaris.shopify.com] Add best practices for Text, AlphaStack, and AlphaCard (#8614)

### WHY are these changes introduced?

There are repos in the Shopify org that link best practices on Text,
Stack, and Card. AlphaCard has best practices but AlphaStack and Text
don't.

### WHAT is this pull request doing?

Adds:
- Best practices to Text from Heading, Caption, TextStyle, and
VisuallyHidden
- Best practices to AlphaStack from LegacyStack

Supplements:
- Best practices for AlphaCard from LegacyCard

<!-- ℹ️ Delete the following for small / trivial changes -->

### How to 🎩

🖥 [Local development
instructions](https://github.com/Shopify/polaris/blob/main/README.md#local-development)
🗒 [General tophatting
guidelines](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md)
📄 [Changelog
guidelines](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#changelog)

### 🎩 checklist

- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [ ] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [ ] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [ ] Updated the component's `README.md` with documentation changes
- [x] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

---------

Co-authored-by: Nayeob Kim <[email protected]>

Author: laurkim

.changeset/sharp-keys-march.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Added best practices to `Text`, `AlphaCard`, and `AlphaStack`

polaris.shopify.com/content/components/layout-and-structure/alpha-card.md

@@ -46,3 +46,7 @@ Cards should:
 
 - Group related information
 - Display information in a way that prioritizes what the merchant needs to know most first
+- Use headings that set clear expectations about the card’s purpose
+- Stick to single user flows or break more complicated flows into multiple sections
+- Avoid too many call-to-action buttons or links and only one primary call to action per card
+- Use calls to action on the bottom of the card for next steps and use the space in the upper right corner of the card for persistent, optional actions (such as Edit)

polaris.shopify.com/content/components/layout-and-structure/alpha-stack.md

@@ -26,6 +26,15 @@ examples:
       Use to horizontally align Stack.
 ---
 
+## Best practices
+
+Stacks should:
+
+- Not be used for complex or unique arrangements of components
+- Not be used for large-scale page layout
+
+---
+
 ## Related components
 
 - To display elements horizontally, [use the Inline component](https://polaris.shopify.com/components/inline)

polaris.shopify.com/content/components/typography/text.md

@@ -172,3 +172,46 @@ These are suggested replacements for existing text style components, but ultimat
 - </VisuallyHidden>
 + <Text visuallyHidden as="h2">Title and description</Text>
 ```
+
+---
+
+## Best practices
+
+### Headings
+
+Headings use all the variants with `heading` in the name, such as `headingMd`. Headings should:
+
+- Clearly describe the section of interface they refer to
+- Highlight the most important concept or piece of information merchants need to know
+- Sit at the top of the section of interface they’re referring to
+
+### Captions
+
+Captions use the `bodySm` Text variant.
+
+- Use for secondary labels in graphs and charts
+- May be used for timestamps in lists of content
+- Don’t use this variant for other cases
+- Don’t use this variant for text longer than a few words
+- Don’t use this variant for aesthetic effect or to break from the standard text size
+
+### Text styles
+
+Text styles should be:
+
+- Used when enhancing the text to help merchants understand its meaning
+- Subdued if the text is less important than its surrounding text
+- Warning if the text denotes something that needs attention, or that merchants need to take action on.
+- Semibold for input fields, or for a row total in a price table
+- Paired with symbols, like an arrow or dollar sign, when using success or critical styles
+
+### Visually hidden
+
+Visually hidden text should:
+
+- Not be used if semantic markup can make content understandable to people using assistive technology
+- Be used to provide extra context when semantic markup isn’t enough
+- Be used on any content that is normally present but is being omitted
+- Make sense in context when used with a screen reader
+
+---