[Layout foundations] Update Columns component docs and guidance

.changeset/rich-cooks-attend.md

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

polaris.shopify.com/content/components/columns.md

@@ -1,6 +1,6 @@
 ---
 title: Columns
-description: Use to lay out a vertical row of components with equal spacing between and wrapping onto multiple lines.
+description: Displays content horizontally in one or more columns with equal spacing between.
 category: Structure
 keywords:
   - layout
@@ -10,8 +10,23 @@ status:
 examples:
   - fileName: columns-default.tsx
     title: Default
+    description: >-
+      By default, there are 6 columns with 16px spacing between them.
   - fileName: columns-with-varying-spacing.tsx
-    title: With varying spacing
-  - fileName: columns-with-free-and-fixed-widths.tsx
-    title: With free and fixed widths
+    title: Spacing
+    description: >-
+      Use the spacing prop to set the amount of space between columns.
+  - fileName: columns-with-fixed-widths.tsx
+    title: Column width
+    description: >-
+      Individual column width can be adjusted.
+  - 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.
 ---
+
+## Related components
+
+- For more control over padding and widths, [use the Box](https://polaris.shopify.com/components/box) component
+- To lay out a set of smaller components horizontally, [use the Inline](https://polaris.shopify.com/components/inline) component

polaris.shopify.com/pages/examples/columns-default.tsx

@@ -1,21 +1,45 @@
 import React from 'react';
-import {Columns} from '@shopify/polaris';
+import {Columns, Text, Inline} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function ColumnsExample() {
   return (
-    <div style={{width: '100%'}}>
-      <Columns columns={{xs: 1, sm: 2, md: 3, lg: 6}} spacing={{xs: '2'}}>
-        <div style={{background: 'var(--p-surface-success)'}}>Column one</div>
-        <div style={{background: 'var(--p-surface-success)'}}>Column two</div>
-        <div style={{background: 'var(--p-surface-success)'}}>Column three</div>
-        <div style={{background: 'var(--p-surface-success)'}}>Column four</div>
-        <div style={{background: 'var(--p-surface-success)'}}>Column five</div>
-        <div style={{background: 'var(--p-surface-success)'}}>Column six</div>
-      </Columns>
-    </div>
+    <Columns>
+      <Placeholder height="320px" label="01" />
+      <Placeholder height="320px" label="02" />
+      <Placeholder height="320px" label="03" />
+      <Placeholder height="320px" label="04" />
+      <Placeholder height="320px" label="05" />
+      <Placeholder height="320px" label="06" />
+    </Columns>
   );
 }
 
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        display: 'inherit',
+        background: '#7B47F1',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align="center" alignY="center">
+        <div
+          style={{
+            color: '#FFFFFF',
+            width: width ?? undefined,
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="medium" alignment="center">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
 export default withPolarisExample(ColumnsExample);

polaris.shopify.com/pages/examples/columns-with-fixed-widths.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import {Columns, Text, Inline} from '@shopify/polaris';
+
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function ColumnsWithFreeAndFixedWidthsExample() {
+  return (
+    <Columns columns={{xs: '2.5fr 1fr 1fr 1fr 1fr 1fr'}}>
+      <Placeholder height="320px" label="01" />
+      <Placeholder height="320px" label="02" />
+      <Placeholder height="320px" label="03" />
+      <Placeholder height="320px" label="04" />
+      <Placeholder height="320px" label="05" />
+      <Placeholder height="320px" label="06" />
+    </Columns>
+  );
+}
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        display: 'inherit',
+        background: '#7B47F1',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align="center" alignY="center">
+        <div
+          style={{
+            color: '#FFFFFF',
+            width: width ?? undefined,
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="medium" alignment="center">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
+export default withPolarisExample(ColumnsWithFreeAndFixedWidthsExample);

polaris.shopify.com/pages/examples/columns-with-set-number.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import {Columns, Text, Inline} from '@shopify/polaris';
+
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function ColumnsWithSetNumberExample() {
+  return (
+    <SpacingBackground>
+      <Columns
+        columns={{
+          xs: '3fr 3fr',
+          md: '4fr 2fr',
+        }}
+        spacing={{
+          xs: '4',
+          md: '2',
+        }}
+      >
+        <Placeholder height="320px" label="01" />
+        <Placeholder height="320px" label="02" />
+      </Columns>
+    </SpacingBackground>
+  );
+}
+
+const SpacingBackground = ({children, width = '100%'}) => {
+  return (
+    <div
+      style={{
+        background:
+          'repeating-linear-gradient(-45deg, #7B47F1, #7B47F1 1px, #E8D1FA 1px, #E8D1FA 7px)',
+        width: width ?? undefined,
+        height: 'auto',
+      }}
+    >
+      {children}
+    </div>
+  );
+};
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        display: 'inherit',
+        background: '#7B47F1',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align="center" alignY="center">
+        <div
+          style={{
+            color: '#FFFFFF',
+            width: width ?? undefined,
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="medium" alignment="center">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
+export default withPolarisExample(ColumnsWithSetNumberExample);

polaris.shopify.com/pages/examples/columns-with-varying-spacing.tsx

@@ -1,21 +1,62 @@
 import React from 'react';
-import {Columns} from '@shopify/polaris';
+import {Columns, Text, Inline} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function ColumnsWithVaryingGapExample() {
   return (
-    <div style={{width: '100%'}}>
-      <Columns
-        columns={{xs: 3}}
-        spacing={{xs: '025', sm: '05', md: '1', lg: '2', xl: '4'}}
-      >
-        <div style={{background: 'var(--p-surface-success)'}}>Column one</div>
-        <div style={{background: 'var(--p-surface-success)'}}>Column two</div>
-        <div style={{background: 'var(--p-surface-success)'}}>Column three</div>
+    <SpacingBackground>
+      <Columns spacing={{xs: '2'}}>
+        <Placeholder height="320px" label="01" />
+        <Placeholder height="320px" label="02" />
+        <Placeholder height="320px" label="03" />
+        <Placeholder height="320px" label="04" />
+        <Placeholder height="320px" label="05" />
+        <Placeholder height="320px" label="06" />
       </Columns>
-    </div>
+    </SpacingBackground>
   );
 }
 
+const SpacingBackground = ({children, width = '100%'}) => {
+  return (
+    <div
+      style={{
+        background:
+          'repeating-linear-gradient(-45deg, #7B47F1, #7B47F1 1px, #E8D1FA 1px, #E8D1FA 7px)',
+        width: width ?? undefined,
+        height: 'auto',
+      }}
+    >
+      {children}
+    </div>
+  );
+};
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        display: 'inherit',
+        background: '#7B47F1',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align="center" alignY="center">
+        <div
+          style={{
+            color: '#FFFFFF',
+            width: width ?? undefined,
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="medium" alignment="center">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
 export default withPolarisExample(ColumnsWithVaryingGapExample);