[Layout foundations] Update layout component docs and guidance (#8379)

### WHY are these changes introduced?

Resolves #8315.

Updates layout component documentation and guidance in preparation for
marking them beta in v11.

### WHAT is this pull request doing?

Updates `AlphaCard`, `AlphaStack`, `Inline`, `Bleed`, `Columns`, and
`Box` documentation.

### 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)
- [x] 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: aveline <[email protected]>
Co-authored-by: Chaz Dean <[email protected]>
Co-authored-by: Lo Kim <[email protected]>

Author: 4 people

.changeset/popular-coins-occur.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Updated documentation and guidance for `AlphaCard`, `AlphaStack`, `Box`, `Bleed`, `Columns`, and `Inline`

polaris.shopify.com/content/components/deprecated/card.md

@@ -26,55 +26,55 @@ status:
     Card was built prior to layout primitives like box, inline, and alpha stack.
     The new layout primitives can be used in combination to achieve similar results to card, or the existing legacy card.
 examples:
-  - fileName: card-default.tsx
+  - fileName: deprecated-card-default.tsx
     title: Default
     description: Use when you have a simple message to communicate to merchants that doesn’t require any secondary steps.
-  - fileName: card-with-header-actions.tsx
+  - fileName: deprecated-card-with-header-actions.tsx
     title: With header actions
     description: Use for less important card actions, or actions merchants may do before reviewing the contents of the card. For example, merchants may want to add items to a card containing a long list, or enter a customer’s new address.
-  - fileName: card-with-footer-actions.tsx
+  - fileName: deprecated-card-with-footer-actions.tsx
     title: With footer actions
     description: Use footer actions for a card’s most important actions, or actions merchants should do after reviewing the contents of the card. For example, merchants should review the contents of a shipment before an important action like adding tracking information. Footer actions can be left or right aligned with the `footerActionAlignment` prop.
-  - fileName: card-with-multiple-footer-actions.tsx
+  - fileName: deprecated-card-with-multiple-footer-actions.tsx
     title: With multiple footer actions
     description: When multiple secondary footer actions are provided, they will render in an action list popover activated by a disclosure button. The disclosure button text can be customized with the `secondaryFooterActionsDisclosureText` prop.
-  - fileName: card-with-custom-footer-actions.tsx
+  - fileName: deprecated-card-with-custom-footer-actions.tsx
     title: With custom footer actions
     description: Use to present actionable content that is optional or not the primary purpose of the page.
-  - fileName: card-with-destructive-footer-action.tsx
+  - fileName: deprecated-card-with-destructive-footer-action.tsx
     title: With destructive footer action
     description: Use when a card action will delete merchant data or be otherwise difficult to recover from.
-  - fileName: card-with-multiple-sections.tsx
+  - fileName: deprecated-card-with-multiple-sections.tsx
     title: With multiple sections
     description: Use when you have two related but distinct pieces of information to communicate to merchants. Multiple sections can help break up complicated concepts to make them easier to scan and understand.
-  - fileName: card-with-multiple-titled-sections.tsx
+  - fileName: deprecated-card-with-multiple-titled-sections.tsx
     title: With multiple titled sections
     description: Use when you have two related but distinct pieces of information to communicate to merchants that are complex enough to require a title to introduce them.
-  - fileName: card-with-sections-and-actions.tsx
+  - fileName: deprecated-card-with-sections-and-actions.tsx
     title: With sections and actions
     description: Use when your card section has actions that apply only to that section.
-  - fileName: card-with-subsection.tsx
+  - fileName: deprecated-card-with-subsection.tsx
     title: With subsection
     description: Use when your card sections need further categorization.
-  - fileName: card-with-destructive-action.tsx
+  - fileName: deprecated-card-with-destructive-action.tsx
     title: With destructive action
     description: Use when a card action applies only to one section and will delete merchant data or be otherwise difficult to recover from.
-  - fileName: card-with-a-subdued-section.tsx
+  - fileName: deprecated-card-with-a-subdued-section.tsx
     title: With a subdued section
     description: Use to indicate when one of the sections in your card contains inactive or disabled content.
-  - fileName: card-with-subdued-for-secondary-content.tsx
+  - fileName: deprecated-card-with-subdued-for-secondary-content.tsx
     title: With subdued for secondary content
     description: Use for content that you want to deprioritize. Subdued cards don’t stand out as much as cards with white backgrounds so don’t use them for information or actions that are critical to merchants.
-  - fileName: card-with-separate-header.tsx
+  - fileName: deprecated-card-with-separate-header.tsx
     title: With separate header
     description: Use to be able to use custom React elements as header content.
-  - fileName: card-with-custom-react-node-title.tsx
+  - fileName: deprecated-card-with-custom-react-node-title.tsx
     title: With custom React Node title
     description: Use to render custom content such as icons, links, or buttons in a card section’s header.
-  - fileName: card-with-all-elements.tsx
+  - fileName: deprecated-card-with-all-elements.tsx
     title: With all elements
     description: Use as a broad example that includes most props available to card.
-  - fileName: card-with-flushed-sections.tsx
+  - fileName: deprecated-card-with-flushed-sections.tsx
     title: With flushed sections
     description: Use when you need further control over the spacing of your card sections.
 ---

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

@@ -4,6 +4,8 @@ description: Cards are used to group similar concepts and tasks together for mer
 category: Layout and structure
 keywords:
   - layout
+  - card
+  - responsive
   - container
   - box
   - grid
@@ -26,18 +28,20 @@ status:
 examples:
   - fileName: alpha-card-default.tsx
     title: Default
+    description: >-
+      By default, cards have an 8px border radius and uses `--p-surface` as the background and `--p-shadow-card` as the shadow. There is padding of `space-5` (20px) around children and `space-4` (16px) for small screens.
   - fileName: alpha-card-with-subdued-background.tsx
     title: With subdued background
     description: >-
       Use for content that you want to deprioritize. Subdued cards don’t stand out as much as cards with white backgrounds so don’t use them for information or actions that are critical to merchants.
   - fileName: alpha-card-with-varying-padding.tsx
     title: With varying padding
     description: >-
-      Use the `padding` property to adjust the spacing within a card. You can also specify spacing values at different breakpoints.
+      Use the `padding` property to adjust the spacing of content within a card. The `padding` prop supports responsive spacing with the [Breakpoints tokens](https://polaris.shopify.com/tokens/breakpoints).
   - fileName: alpha-card-with-rounded-corners.tsx
     title: Rounded corners
     description: >-
-      Cards have an 8px border radius by default. Rounding may also be applied responsively with the roundedAbove prop. This enables cards to be softened on larger screens, but squared off when they are full bleed on smaller devices.
+      Cards can have a border radius applied responsively with the `roundedAbove` prop.
 ---
 
 ## Best practices
@@ -50,3 +54,9 @@ Cards should:
 - 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)
+
+---
+
+## Related components
+
+- For more flexibility on styling, [use the Box component](https://polaris.shopify.com/components/layout-and-structure/box)

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

@@ -1,29 +1,28 @@
 ---
 title: Alpha stack
-description: Use to display elements vertically with items placed directly below the preceding item.
+description: Use to display children vertically with full width by default. Based on CSS Flexbox.
 category: Layout and structure
 keywords:
   - layout
+  - stack spacing
+  - vertical centering
+  - fill available space
+  - fill space
+  - equal width
+  - right-aligned stack
+  - stack layout
 status:
   value: Alpha
   message: This component is a work in progress and ready for exploratory usage, with breaking changes expected in minor version updates. Please use with caution. Learn more about our [component lifecycles](/getting-started/components-lifecycle).
 examples:
-  - fileName: alpha-stack-default.tsx
-    title: Default
-    description: >-
-      By default, stack is left aligned and stacked items are spaced with 16px in between.
   - fileName: alpha-stack-with-gap.tsx
     title: Gap
     description: >-
-      Gaps between stack children can be adjusted using the Space token.
-  - fileName: alpha-stack-with-full-width-children.tsx
-    title: Full width
-    description: >-
-      Use a boolean to make Stack full width.
+      Control the vertical space between children using the `gap` prop.
   - fileName: alpha-stack-with-align.tsx
-    title: Alignment
+    title: Align
     description: >-
-      Use to horizontally align Stack.
+      Control the horizontal alignment of children using the `align` prop.
 ---
 
 ## Best practices

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

@@ -8,22 +8,18 @@ status:
   value: Alpha
   message: This component is a work in progress and ready for exploratory usage, with breaking changes expected in minor version updates. Please use with caution. Learn more about our [component lifecycles](/getting-started/components-lifecycle).
 examples:
-  - fileName: bleed-vertical.tsx
-    title: Vertical
-    description: >-
-      Content will bleed vertically into the surrounding layout using the vertical prop.
   - fileName: bleed-horizontal.tsx
     title: Horizontal
     description: >-
-      Content will bleed horizontally into the surrounding layout using the horizontal prop.
+      Content will bleed horizontally into the surrounding layout using the `marginInline` prop.
+  - fileName: bleed-vertical.tsx
+    title: Vertical
+    description: >-
+      Content will bleed vertically into the surrounding layout using the `marginBlock` prop.
   - fileName: bleed-specific-direction.tsx
     title: Specific direction
     description: >-
-      Content will bleed into the surrounding layout in a specific direction using the top, bottom, left, or right prop.
-  - fileName: bleed-all-directions.tsx
-    title: All directions
-    description: >-
-      Content will bleed into the surrounding layout in all directions using the spacing prop.
+      Negative margins can be added in a specific direction using the [Spacing tokens](https://polaris.shopify.com/tokens/spacing).
 ---
 
 ## Bleed values

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

@@ -4,20 +4,19 @@ description: Box is the most primitive layout component. It’s a way to access
 category: Layout and structure
 keywords:
   - layout
+  - box
+  - responsive
+  - tokens
 status:
   value: Alpha
   message: This component is a work in progress and ready for exploratory usage, with breaking changes expected in minor version updates. Please use with caution. Learn more about our [component lifecycles](/getting-started/components-lifecycle).
 examples:
-  - fileName: box-default.tsx
-    title: Default
-    description: >-
-      By default, box has no padding, borders, border radius, background, or shadows.
   - fileName: box-with-color.tsx
     title: Color
     description: >-
       Background color of box and text color inside a box can be adjusted using the [Color tokens](https://polaris.shopify.com/tokens/colors).
   - fileName: box-with-border.tsx
-    title: Border
+    title: Border width
     description: >-
       Border width can be adjusted using the [Shape tokens](https://polaris.shopify.com/tokens/shape), and a subset of tokens allows different types of border.
   - fileName: box-with-border-radius.tsx
@@ -27,11 +26,11 @@ examples:
   - fileName: box-with-padding.tsx
     title: Padding
     description: >-
-      Padding can be added to either all sides, left, right, top, and bottom, using the [Spacing tokens](https://polaris.shopify.com/tokens/spacing).
+      Padding can be added to either all sides, left, right, top, and bottom, using the [Spacing tokens](https://polaris.shopify.com/tokens/spacing). The `padding` prop supports responsive spacing with the [Breakpoints tokens](https://polaris.shopify.com/tokens/breakpoints).
   - fileName: box-with-shadow.tsx
     title: Shadow
     description: >-
-      Shadow can be applied using the Shadow token. The base is [--p-shadow-base](https://polaris.shopify.com/tokens/depth).
+      Shadow can be applied using the [Depth tokens](https://polaris.shopify.com/tokens/depth).
 ---
 
 ## Related components

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

@@ -1,29 +1,28 @@
 ---
 title: Columns
-description: Displays content horizontally in one or more columns with equal spacing between.
+description: Use to lay out children horizontally with equal gap between columns. Based on [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/grid).
 category: Layout and structure
 keywords:
   - layout
+  - columns
+  - grid
+  - responsive
 status:
   value: Alpha
   message: This component is a work in progress and ready for exploratory usage, with breaking changes expected in minor version updates. Please use with caution. Learn more about our [component lifecycles](/getting-started/components-lifecycle).
 examples:
-  - fileName: columns-default.tsx
-    title: Default
-    description: >-
-      By default, there are 6 columns with 16px spacing between them.
   - fileName: columns-with-varying-gap.tsx
     title: Gap
     description: >-
-      Use the gap prop to set the amount of space between columns.
+      Use the `gap` prop to set the amount of space between columns. The `gap` prop supports responsive spacing with the [Breakpoints tokens](https://polaris.shopify.com/tokens/breakpoints).
   - fileName: columns-with-fixed-widths.tsx
     title: Column width
     description: >-
-      Individual column width can be adjusted.
+      The `columns` property accepts CSS column shorthand syntax, or an array of strings mapping to common widths in the admin such as `oneThird`, `oneHalf`, and `twoThirds`. For responsive columns, use the same syntax passed into an object with the breakpoints.
   - fileName: columns-with-set-number.tsx
     title: Number of columns
     description: >-
-      Use the columns prop to set the number and width of columns across breakpoints.
+      Control the number of columns using the `columns` prop. Column numbers can be responsively set using the [Breakpoints tokens](https://polaris.shopify.com/tokens/breakpoints).
 ---
 
 ## Related components

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

@@ -1,9 +1,11 @@
 ---
 title: Divider
-description: Use to separate or group content
+description: Use to separate or group content.
 category: Layout and structure
 keywords:
   - layout
+  - divider
+  - border
 status:
   value: Alpha
   message: This component is a work in progress and ready for exploratory usage, with breaking changes expected in minor version updates. Please use with caution. Learn more about our [component lifecycles](/getting-started/components-lifecycle).

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

@@ -1,35 +1,42 @@
 ---
 title: Inline
-description: Use to arrange items in a horizontal row with equal spacing around them. Items wrap onto multiple lines when needed.
+description: Use to display children horizontally in a row. Based on CSS Flexbox.
 category: Layout and structure
 keywords:
   - layout
+  - inline
+  - flexbox
+  - flex
+  - responsive
+  - flexible items
+  - row of components
+  - rows
+  - vertical centering
+  - horizontal row of components
+  - stack
 status:
   value: Alpha
   message: This component is a work in progress and ready for exploratory usage, with breaking changes expected in minor version updates. Please use with caution. Learn more about our [component lifecycles](/getting-started/components-lifecycle).
 examples:
-  - fileName: inline-default.tsx
-    title: Default
-    description: >-
-      Items are vertically centered with 16px of space around them. They’ll wrap onto multiple lines when needed.
   - fileName: inline-with-non-wrapping.tsx
     title: Non-wrapping
     description: >-
-      Use to create Inline where the children will not wrap to new rows on small screens.
+      The default wrapping behavior of children can be overridden using the `wrap` prop.
   - fileName: inline-with-gap.tsx
     title: Gap
     description: >-
-      Use to control gaps around items in inline in standard increments.
-  - fileName: inline-with-vertical-alignment.tsx
-    title: Vertical alignment
+      Control the horizontal and vertical space between children using the `gap` prop. The `gap` prop supports responsive spacing with the [Breakpoints tokens](https://polaris.shopify.com/tokens/breakpoints).
+  - fileName: inline-with-block-align.tsx
+    title: Block align
     description: >-
-      Use to vertically align Inline.
-  - fileName: inline-with-horizontal-alignment.tsx
-    title: Horizontal alignment
+      Control the vertical alignment of children using the `blockAlign` prop.
+  - fileName: inline-with-align.tsx
+    title: Align
     description: >-
-      Use to horizontally align Inline.
+      Control the horizontal alignment of children using the `align` prop.
 ---
 
 ## Related components
 
-- To display elements vertically, [use the AlphaStack component](https://polaris.shopify.com/components/layout-and-structure/alpha-stack)
+- To create the large-scale structure of pages, [use the Columns component](https://polaris.shopify.com/components/layout-and-structure/columns)
+- To display elements vertically, [use the AlphaStack component](https://polaris.shopify.com/components/alphastack)

polaris.shopify.com/next.config.js

@@ -440,6 +440,11 @@ const layoutAndStructure = [
     destination: '/components/layout-and-structure/stack',
     permanent: false,
   },
+  {
+    source: '/components/layout-and-structure/stack',
+    destination: '/components/layout-and-structure/alpha-stack',
+    permanent: false,
+  },
 ];
 
 const lists = [