Update Box component docs and guidance

.changeset/shiny-mangos-tease.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Updated `Box` component guidance and examples

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

@@ -1,27 +1,39 @@
 ---
 title: Box
-description: Box is the most primitive layout component. Box has a set of padding options. Use it to render an individual item.
+description: Box is the most primitive layout component. It’s a way to access Polaris design tokens.
 category: Structure
 keywords:
   - layout
 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.
 examples:
-  - fileName: box-with-padding.tsx
-    title: Padding
+  - 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
     description: >-
-      Spacing inside Box can be set with the padding properties. Padding options are provided using our spacing tokens. There are 5 different padding properties: padding, paddingLeft, paddingRight, paddingTop, and paddingBottom.
+      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
     title: Border radius
     description: >-
-      Border radius can be set with the border radius properties. Border radius options are provided using our shape tokens. There are 5 different padding properties: borderRadius, borderRadiusLeft, borderRadiusRight, borderRadiusTop, and borderRadiusBottom.
-  - fileName: box-with-background.tsx
-    title: Background
+      Border radius can be adjusted using the [Shape tokens](https://polaris.shopify.com/tokens/shape).
+  - fileName: box-with-padding.tsx
+    title: Padding
     description: >-
-      Background color for Box can be set with the background prop. Background color options are provided using our color tokens that relate to background, surface, backdrop, and overlay.
-  - fileName: box-with-border.tsx
-    title: Border
+      Padding can be added to either all sides, left, right, top, and bottom, using the [Spacing tokens](https://polaris.shopify.com/tokens/spacing).
+  - fileName: box-with-shadow.tsx
+    title: Shadow
     description: >-
-      Border color for Box can be set with the border prop. Border color options are provided using our shape tokens.
+      Shadow can be applied using the Shadow token. The base is [--p-shadow-base](https://polaris.shopify.com/tokens/depth).
 ---
+
+## Related components
+
+- For more specific use cases, [use the Card](https://polaris.shopify.com/components/card) component.

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

@@ -0,0 +1,36 @@
+import React from 'react';
+import {Box, Text} from '@shopify/polaris';
+
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function BoxDefaultExample() {
+  return (
+    <Box>
+      <Placeholder label="Content inside a box" />
+    </Box>
+  );
+}
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        height: height,
+        width: width,
+      }}
+    >
+      <div
+        style={{
+          color: '#FFFFFF',
+        }}
+      >
+        <Text as="h2" variant="bodyMd" fontWeight="medium">
+          {label}
+        </Text>
+      </div>
+    </div>
+  );
+};
+
+export default withPolarisExample(BoxDefaultExample);

polaris.shopify.com/pages/examples/box-with-border-radius.tsx

@@ -1,47 +1,37 @@
 import React from 'react';
-import {Box, Stack, Text} from '@shopify/polaris';
+import {Box, Text} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function BoxWithBorderRadiusExample() {
   return (
-    <Stack vertical>
-      <Box
-        background="surface"
-        border="base"
-        borderRadius="2"
-        padding="5"
-        shadow="card"
-      >
-        <Text as="h2" variant="headingMd">
-          Box with uniform border radius
-        </Text>
-      </Box>
-      <Box
-        background="surface"
-        border="base"
-        borderRadiusEndStart="2"
-        borderRadiusEndEnd="2"
-        padding="5"
-        shadow="card"
-      >
-        <Text as="h2" variant="headingMd">
-          Box with bottom border radius
-        </Text>
-      </Box>
-      <Box
-        background="surface"
-        border="base"
-        borderRadius="base"
-        padding="5"
-        shadow="card"
+    <Box background="surface" borderRadius="2">
+      <Placeholder label="Content inside a box" />
+    </Box>
+  );
+}
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        height: height,
+        width: width,
+        borderRadius: 'inherit',
+      }}
+    >
+      <div
+        style={{
+          color: '#FFFFFF',
+        }}
       >
-        <Text as="h2" variant="headingMd">
-          Box with border radius base
+        <Text as="h2" variant="bodyMd" fontWeight="medium">
+          {label}
         </Text>
-      </Box>
-    </Stack>
+      </div>
+    </div>
   );
-}
+};
 
 export default withPolarisExample(BoxWithBorderRadiusExample);

polaris.shopify.com/pages/examples/box-with-border.tsx

@@ -1,68 +1,36 @@
 import React from 'react';
-import {Box, Stack, Text} from '@shopify/polaris';
+import {Box, Text} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function BoxWithBorderExample() {
   return (
-    <Stack vertical>
-      <Box
-        background="surface"
-        border="base"
-        borderRadius="2"
-        padding="5"
-        shadow="card"
-      >
-        <Text as="h2" variant="headingMd">
-          Box with border base
-        </Text>
-      </Box>
-      <Box
-        background="surface"
-        border="divider"
-        borderRadius="2"
-        padding="5"
-        shadow="card"
-      >
-        <Text as="h2" variant="headingMd">
-          Box with border divider
-        </Text>
-      </Box>
-      <Box
-        background="surface"
-        border="dark"
-        borderRadius="2"
-        padding="5"
-        shadow="card"
-      >
-        <Text as="h2" variant="headingMd">
-          Box with border dark
-        </Text>
-      </Box>
-      <Box
-        background="surface"
-        border="transparent"
-        borderRadius="2"
-        padding="5"
-        shadow="card"
-      >
-        <Text as="h2" variant="headingMd">
-          Box with border transparent
-        </Text>
-      </Box>
-      <Box
-        background="surface"
-        border="divider-on-dark"
-        borderRadius="2"
-        padding="5"
-        shadow="card"
+    <Box border="dark">
+      <Placeholder label="Content inside a box" />
+    </Box>
+  );
+}
+
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        background: '#F4E8FD',
+        height: height,
+        width: width,
+      }}
+    >
+      <div
+        style={{
+          color: '#26282C',
+        }}
       >
-        <Text as="h2" variant="headingMd">
-          Box with border divider on dark
+        <Text as="h2" variant="bodyMd" fontWeight="medium">
+          {label}
         </Text>
-      </Box>
-    </Stack>
+      </div>
+    </div>
   );
-}
+};
 
 export default withPolarisExample(BoxWithBorderExample);

polaris.shopify.com/pages/examples/box-with-color.tsx

@@ -0,0 +1,16 @@
+import React from 'react';
+import {Box, Text} from '@shopify/polaris';
+
+import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
+
+function BoxWithColorExample() {
+  return (
+    <Box background="surface-success">
+      <Text as="h2" variant="bodyMd" fontWeight="medium">
+        Content inside a box
+      </Text>
+    </Box>
+  );
+}
+
+export default withPolarisExample(BoxWithColorExample);