[Layout foundations] Update AlphaStack component docs and guidance

.changeset/heavy-eagles-train.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Updated `AlphaStack` component docs

polaris.shopify.com/content/components/alpha-stack.md

@@ -1,6 +1,6 @@
 ---
 title: Alpha stack
-description: Use to lay out a vertical pile of elements sitting on top of each other. A stack is made of flexible items that wrap each of the stack’s children. Options allow different spacing and alignments.
+description: Use to display elements vertically with items placed directly below the preceding item.
 category: Structure
 keywords:
   - layout
@@ -10,16 +10,22 @@ status:
 examples:
   - fileName: alpha-stack-default.tsx
     title: Default
-  - fileName: alpha-stack-with-align.tsx
-    title: Horizontal alignment
     description: >-
-      Horizontal alignment for children can be set with the align property.
+      By default, stack is left aligned and stacked items are spaced with 16px in between.
   - fileName: alpha-stack-with-spacing.tsx
-    title: Vertical spacing
+    title: Spacing
     description: >-
-      Vertical spacing for children can be set with the spacing property. Spacing options are provided using our spacing tokens.
+      Spacing between stack child can be adjusted using the Space token.
   - fileName: alpha-stack-with-full-width-children.tsx
-    title: Full width children
+    title: Full width
+    description: >-
+      Use a boolean to make Stack full width.
+  - fileName: alpha-stack-with-align.tsx
+    title: Alignment
     description: >-
-      Set children to full width
+      Use to vertically align Stack.
 ---
+
+## Related components
+
+- To display elements horizontally, use [Inline](https://polaris.shopify.com/components/inline).

polaris.shopify.com/pages/examples/alpha-stack-default.tsx

@@ -1,21 +1,47 @@
 import React from 'react';
-import {AlphaStack, Badge, Text} from '@shopify/polaris';
+import {AlphaStack, Text} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function AlphaStackExample() {
   return (
-    <div style={{width: '100%'}}>
-      <AlphaStack>
-        <Text variant="heading4xl" as="h2">
-          AlphaStack
+    <AlphaStack>
+      <Placeholder width="320px" label="Stack child" />
+      <Placeholder width="320px" />
+      <Placeholder width="320px" />
+    </AlphaStack>
+  );
+}
+
+const Placeholder = ({
+  label = '',
+  height = 'auto',
+  width = 'auto',
+  childWidth = 'auto',
+}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        padding: '14px var(--p-space-2)',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <div
+        style={{
+          display: 'inline-block',
+          background: 'rgba(255, 255, 255, 0.3)',
+          color: '#FFFFFF',
+          width: childWidth ?? undefined,
+        }}
+      >
+        <Text as="h2" variant="bodyMd" fontWeight="medium">
+          {label}
         </Text>
-        <Badge>One</Badge>
-        <Badge>Two</Badge>
-        <Badge>Three</Badge>
-      </AlphaStack>
+      </div>
     </div>
   );
-}
+};
 
 export default withPolarisExample(AlphaStackExample);

polaris.shopify.com/pages/examples/alpha-stack-with-align.tsx

@@ -1,66 +1,68 @@
 import React from 'react';
-import {AlphaStack, Badge, Box, Inline, Text} from '@shopify/polaris';
+import {AlphaStack, Box, Page, Inline, Text} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function AlphaStackWithAlignExample() {
   return (
-    <div style={{width: '100%'}}>
-      <Box paddingBottom="2">
-        <Text variant="bodySm" as="h3">
-          with align start
-        </Text>
-      </Box>
-      <Box paddingBottom="2">
+    <Page>
+      <Box paddingBottom="20">
         <AlphaStack align="start">
-          <Text variant="heading4xl" as="h2">
-            AlphaStack
-          </Text>
-          <Inline>
-            <Badge>One</Badge>
-            <Badge>Two</Badge>
-            <Badge>Three</Badge>
-          </Inline>
+          <Placeholder width="320px" label="Start" childAlign="start" />
+          <Placeholder width="320px" childAlign="start" />
+          <Placeholder width="320px" childAlign="start" />
         </AlphaStack>
       </Box>
-      <hr />
-      <Box paddingBottom="2">
-        <Text variant="bodySm" as="h3">
-          with align center
-        </Text>
-      </Box>
-      <Box paddingBottom="2">
+      <Box paddingBottom="20">
         <AlphaStack align="center">
-          <Text variant="heading4xl" as="h2">
-            AlphaStack
-          </Text>
-          <Inline>
-            <Badge>One</Badge>
-            <Badge>Two</Badge>
-            <Badge>Three</Badge>
-          </Inline>
+          <AlphaStack>
+            <Placeholder width="320px" label="Center" childAlign="center" />
+            <Placeholder width="320px" childAlign="center" />
+            <Placeholder width="320px" childAlign="center" />
+          </AlphaStack>
         </AlphaStack>
       </Box>
-      <hr />
-      <Box paddingBottom="2">
-        <Text variant="bodySm" as="h3">
-          with align end
-        </Text>
-      </Box>
-      <Box paddingBottom="2">
+      <Box>
         <AlphaStack align="end">
-          <Text variant="heading4xl" as="h2">
-            AlphaStack
-          </Text>
-          <Inline>
-            <Badge>One</Badge>
-            <Badge>Two</Badge>
-            <Badge>Three</Badge>
-          </Inline>
+          <Placeholder width="320px" label="End" childAlign="end" />
+          <Placeholder width="320px" childAlign="center" />
+          <Placeholder width="320px" childAlign="center" />
         </AlphaStack>
       </Box>
-    </div>
+    </Page>
   );
 }
 
+const Placeholder = ({
+  label = '',
+  height = 'auto',
+  width = 'auto',
+  childAlign,
+}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        padding: '14px var(--p-space-2)',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align={childAlign}>
+        <div
+          style={{
+            display: 'inline-block',
+            background: 'rgba(255, 255, 255, 0.3)',
+            color: '#FFFFFF',
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="medium">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
 export default withPolarisExample(AlphaStackWithAlignExample);

polaris.shopify.com/pages/examples/alpha-stack-with-full-width-children.tsx

@@ -1,21 +1,47 @@
 import React from 'react';
-import {AlphaStack, Badge, Text} from '@shopify/polaris';
+import {AlphaStack, Text} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function AlphaStackWithFullWidthChildrenExample() {
   return (
-    <div style={{width: '100%'}}>
-      <AlphaStack fullWidth>
-        <Text variant="heading4xl" as="h2">
-          AlphaStack
+    <AlphaStack fullWidth>
+      <Placeholder label="Stack child" childWidth="100%" />
+      <Placeholder />
+      <Placeholder />
+    </AlphaStack>
+  );
+}
+
+const Placeholder = ({
+  label = '',
+  height = 'auto',
+  width = '100%',
+  childWidth = 'auto',
+}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        padding: '14px var(--p-space-2)',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <div
+        style={{
+          display: 'inline-block',
+          background: 'rgba(255, 255, 255, 0.3)',
+          color: '#FFFFFF',
+          width: childWidth ?? undefined,
+        }}
+      >
+        <Text as="h2" variant="bodyMd" fontWeight="medium">
+          {label}
         </Text>
-        <Badge>One</Badge>
-        <Badge>Two</Badge>
-        <Badge>Three</Badge>
-      </AlphaStack>
+      </div>
     </div>
   );
-}
+};
 
 export default withPolarisExample(AlphaStackWithFullWidthChildrenExample);

polaris.shopify.com/pages/examples/alpha-stack-with-spacing.tsx

@@ -1,66 +1,64 @@
 import React from 'react';
-import {AlphaStack, Badge, Box, Inline, Text} from '@shopify/polaris';
+import {AlphaStack, Text} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function AlphaStackWithSpacingExample() {
   return (
-    <div style={{width: '100%'}}>
-      <Box paddingBottom="2">
-        <Text variant="bodySm" as="h3">
-          with spacing 0
-        </Text>
-      </Box>
-      <Box paddingBottom="2">
-        <AlphaStack spacing="0">
-          <Text variant="heading4xl" as="h2">
-            AlphaStack
-          </Text>
-          <Inline>
-            <Badge>One</Badge>
-            <Badge>Two</Badge>
-            <Badge>Three</Badge>
-          </Inline>
-        </AlphaStack>
-      </Box>
-      <hr />
-      <Box paddingBottom="2">
-        <Text variant="bodySm" as="h3">
-          with spacing 4
-        </Text>
-      </Box>
-      <Box paddingBottom="2">
-        <AlphaStack spacing="4">
-          <Text variant="heading4xl" as="h2">
-            AlphaStack
-          </Text>
-          <Inline>
-            <Badge>One</Badge>
-            <Badge>Two</Badge>
-            <Badge>Three</Badge>
-          </Inline>
-        </AlphaStack>
-      </Box>
-      <hr />
-      <Box paddingBottom="2">
-        <Text variant="bodySm" as="h3">
-          with spacing 10
+    <SpacingBackground width="320px">
+      <AlphaStack spacing="5">
+        <Placeholder width="320px" label="Stack child" />
+        <Placeholder width="320px" />
+        <Placeholder width="320px" />
+      </AlphaStack>
+    </SpacingBackground>
+  );
+}
+
+const SpacingBackground = ({children, width}) => {
+  return (
+    <div
+      style={{
+        background:
+          'repeating-linear-gradient(-45deg, #7B47F1, #7B47F1 1px, #E8D1FA 1px, #E8D1FA 7px)',
+        width: width ?? '100%',
+        height: 'auto',
+      }}
+    >
+      {children}
+    </div>
+  );
+};
+
+const Placeholder = ({
+  label = '',
+  height = 'auto',
+  width = 'auto',
+  childWidth = 'auto',
+}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        padding: '14px var(--p-space-2)',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <div
+        style={{
+          display: 'inline-block',
+          background: 'rgba(255, 255, 255, 0.3)',
+          color: '#FFFFFF',
+          width: childWidth ?? undefined,
+        }}
+      >
+        <Text as="h2" variant="bodyMd" fontWeight="medium">
+          {label}
         </Text>
-      </Box>
-      <Box paddingBottom="2">
-        <AlphaStack spacing="10">
-          <Text variant="heading4xl" as="h2">
-            AlphaStack
-          </Text>
-          <Inline>
-            <Badge>One</Badge>
-            <Badge>Two</Badge>
-            <Badge>Three</Badge>
-          </Inline>
-        </AlphaStack>
-      </Box>
+      </div>
     </div>
   );
-}
+};
 
 export default withPolarisExample(AlphaStackWithSpacingExample);