From ac541e9b2b9fa2ca571d8bb2b8797d278f4d265c Mon Sep 17 00:00:00 2001
From: Chaz Dean <59836805+chazdean@users.noreply.github.com>
Date: Fri, 28 Oct 2022 15:26:43 -0400
Subject: [PATCH 1/3] Update `Bleed` docs

---
 .changeset/wild-seas-notice.md                |  5 ++
 .../content/components/bleed.md               | 14 ++--
 .../pages/examples/bleed-all-directions.tsx   | 52 ++++++++-----
 .../pages/examples/bleed-horizontal.tsx       | 52 ++++++++-----
 .../examples/bleed-specific-direction.tsx     | 76 +++++++++----------
 .../pages/examples/bleed-vertical.tsx         | 52 ++++++++-----
 6 files changed, 143 insertions(+), 108 deletions(-)
 create mode 100644 .changeset/wild-seas-notice.md

diff --git a/.changeset/wild-seas-notice.md b/.changeset/wild-seas-notice.md
new file mode 100644
index 00000000000..98681faa539
--- /dev/null
+++ b/.changeset/wild-seas-notice.md
@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': patch
+---
+
+Updated `Bleed` component docs
diff --git a/polaris.shopify.com/content/components/bleed.md b/polaris.shopify.com/content/components/bleed.md
index 89e075862ca..301f139bb7b 100644
--- a/polaris.shopify.com/content/components/bleed.md
+++ b/polaris.shopify.com/content/components/bleed.md
@@ -1,6 +1,6 @@
 ---
 title: Bleed
-description: Used to create a container that applies negative margins to allow content to extend into the surrounding layout.
+description: Applies negative margin to allow content to bleed out into the surrounding layout.
 category: Structure
 keywords:
   - layout
@@ -11,17 +11,21 @@ examples:
   - fileName: bleed-vertical.tsx
     title: Vertical
     description: >-
-      Use to set bleed vertically.
+      Content will bleed vertically into the surrounding layout using the vertical prop.
   - fileName: bleed-horizontal.tsx
     title: Horizontal
     description: >-
-      Use to set bleed horizontally.
+      Content will bleed horizontally into the surrounding layout using the horizontal prop.
   - fileName: bleed-specific-direction.tsx
     title: Specific direction
     description: >-
-      Use to set bleed in a specific direction
+      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: >-
-      Use to set bleed in all directions
+      Content will bleed into the surrounding layout in all directions using the spacing prop.
 ---
+
+## Bleed values
+
+Content should never go beyond the edges of the parent container. Choose a bleed value that works within the containing layout.
diff --git a/polaris.shopify.com/pages/examples/bleed-all-directions.tsx b/polaris.shopify.com/pages/examples/bleed-all-directions.tsx
index 3ddbae24c76..613fefb0e65 100644
--- a/polaris.shopify.com/pages/examples/bleed-all-directions.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-all-directions.tsx
@@ -1,31 +1,41 @@
 import React from 'react';
-import {Bleed, Box, Text} from '@shopify/polaris';
+import {Bleed, Box, Text, Inline} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
-const styles = {
-  background: 'var(--p-background-selected)',
-  borderRadius: 'var(--p-border-radius-05)',
-  border: '1px solid var(--p-surface-dark)',
-  padding: 'var(--p-space-4)',
-  height: 'var(--p-space-12)',
-  opacity: 0.7,
-};
-
 function BleedAllDirectionsExample() {
   return (
-    <div style={{width: '100%'}}>
-      <Box background="surface" border="base" padding="4">
-        <Bleed spacing="6">
-          <div style={styles}>
-            <Text variant="bodySm" as="h3" alignment="center" fontWeight="bold">
-              All directions
-            </Text>
-          </div>
-        </Bleed>
-      </Box>
-    </div>
+    <Box background="surface" border="base" padding="4">
+      <Bleed spacing="4">
+        <Placeholder label="All directions" />
+      </Bleed>
+    </Box>
   );
 }
 
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        padding: '14px var(--p-space-2)',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align="center">
+        <div
+          style={{
+            color: '#FFFFFF',
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="regular">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
 export default withPolarisExample(BleedAllDirectionsExample);
diff --git a/polaris.shopify.com/pages/examples/bleed-horizontal.tsx b/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
index 8aecbd305a2..fb925355c23 100644
--- a/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
@@ -1,31 +1,41 @@
 import React from 'react';
-import {Bleed, Box, Text} from '@shopify/polaris';
+import {Bleed, Box, Text, Inline} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
-const styles = {
-  background: 'var(--p-background-selected)',
-  borderRadius: 'var(--p-border-radius-05)',
-  border: '1px solid var(--p-surface-dark)',
-  padding: 'var(--p-space-4)',
-  height: 'var(--p-space-12)',
-  opacity: 0.7,
-};
-
 function BleedHorizontalExample() {
   return (
-    <div style={{width: '100%'}}>
-      <Box background="surface" border="base" padding="4">
-        <Bleed horizontal="6">
-          <div style={styles}>
-            <Text variant="bodySm" as="h3" alignment="center" fontWeight="bold">
-              horizontal
-            </Text>
-          </div>
-        </Bleed>
-      </Box>
-    </div>
+    <Box background="surface" border="base" padding="4">
+      <Bleed vertical="4">
+        <Placeholder label="Horizontal" />
+      </Bleed>
+    </Box>
   );
 }
 
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        padding: '14px var(--p-space-2)',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align="center">
+        <div
+          style={{
+            color: '#FFFFFF',
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="regular">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
 export default withPolarisExample(BleedHorizontalExample);
diff --git a/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx b/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx
index f43f6c91965..feba7cb2c6e 100644
--- a/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx
@@ -1,62 +1,58 @@
 import React from 'react';
-import {Bleed, Box, Text} from '@shopify/polaris';
+import {AlphaStack, Bleed, Box, Text, Inline} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
-const styles = {
-  background: 'var(--p-background-selected)',
-  borderRadius: 'var(--p-border-radius-05)',
-  border: '1px solid var(--p-surface-dark)',
-  padding: 'var(--p-space-4)',
-  height: 'var(--p-space-12)',
-  opacity: 0.7,
-};
-
 function BleedSpecificDirectionExample() {
   return (
-    <div style={{width: '100%'}}>
+    <AlphaStack spacing="6" fullWidth>
       <Box background="surface" border="base" padding="4">
-        <Bleed top="6">
-          <div style={styles}>
-            <Text variant="bodySm" as="h3" alignment="center" fontWeight="bold">
-              top
-            </Text>
-          </div>
+        <Bleed top="4">
+          <Placeholder label="Top" />
         </Bleed>
       </Box>
-      <br />
       <Box background="surface" border="base" padding="4">
-        <Bleed right="6">
-          <div style={styles}>
-            <Text variant="bodySm" as="h3" alignment="center" fontWeight="bold">
-              right
-            </Text>
-          </div>
+        <Bleed bottom="4">
+          <Placeholder label="Bottom" />
         </Bleed>
       </Box>
-      <br />
       <Box background="surface" border="base" padding="4">
-        <Bleed left="6">
-          <div style={styles}>
-            <Text variant="bodySm" as="h3" alignment="center" fontWeight="bold">
-              left
-            </Text>
-          </div>
+        <Bleed left="4">
+          <Placeholder label="Left" />
         </Bleed>
       </Box>
-      <br />
       <Box background="surface" border="base" padding="4">
-        <Bleed bottom="6">
-          <div style={styles}>
-            <Text variant="bodySm" as="h3" alignment="center" fontWeight="bold">
-              bottom
-            </Text>
-          </div>
+        <Bleed right="4">
+          <Placeholder label="Right" />
         </Bleed>
       </Box>
-      <br />
-    </div>
+    </AlphaStack>
   );
 }
 
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        padding: '14px var(--p-space-2)',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align="center">
+        <div
+          style={{
+            color: '#FFFFFF',
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="regular">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
 export default withPolarisExample(BleedSpecificDirectionExample);
diff --git a/polaris.shopify.com/pages/examples/bleed-vertical.tsx b/polaris.shopify.com/pages/examples/bleed-vertical.tsx
index e52ec0251cc..4abf9538258 100644
--- a/polaris.shopify.com/pages/examples/bleed-vertical.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-vertical.tsx
@@ -1,31 +1,41 @@
 import React from 'react';
-import {Bleed, Box, Text} from '@shopify/polaris';
+import {Bleed, Box, Text, Inline} from '@shopify/polaris';
 
 import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
-const styles = {
-  background: 'var(--p-background-selected)',
-  borderRadius: 'var(--p-border-radius-05)',
-  border: '1px solid var(--p-surface-dark)',
-  padding: 'var(--p-space-4)',
-  height: 'var(--p-space-12)',
-  opacity: 0.7,
-};
-
 function BleedVerticalExample() {
   return (
-    <div style={{width: '100%'}}>
-      <Box background="surface" border="base" padding="4">
-        <Bleed vertical="6">
-          <div style={styles}>
-            <Text variant="bodySm" as="h3" alignment="center" fontWeight="bold">
-              vertical
-            </Text>
-          </div>
-        </Bleed>
-      </Box>
-    </div>
+    <Box background="surface" border="base" padding="4">
+      <Bleed vertical="4">
+        <Placeholder label="Vertical" />
+      </Bleed>
+    </Box>
   );
 }
 
+const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
+  return (
+    <div
+      style={{
+        background: '#7B47F1',
+        padding: '14px var(--p-space-2)',
+        height: height ?? undefined,
+        width: width ?? undefined,
+      }}
+    >
+      <Inline align="center">
+        <div
+          style={{
+            color: '#FFFFFF',
+          }}
+        >
+          <Text as="h2" variant="bodyMd" fontWeight="regular">
+            {label}
+          </Text>
+        </div>
+      </Inline>
+    </div>
+  );
+};
+
 export default withPolarisExample(BleedVerticalExample);

From 1c48a8c24205a736207b228dcf3415ff14815482 Mon Sep 17 00:00:00 2001
From: Chaz Dean <59836805+chazdean@users.noreply.github.com>
Date: Mon, 31 Oct 2022 08:26:34 -0400
Subject: [PATCH 2/3] Update bleed-horizontal.tsx

---
 polaris.shopify.com/pages/examples/bleed-horizontal.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/polaris.shopify.com/pages/examples/bleed-horizontal.tsx b/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
index fb925355c23..0343371e263 100644
--- a/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
@@ -6,7 +6,7 @@ import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 function BleedHorizontalExample() {
   return (
     <Box background="surface" border="base" padding="4">
-      <Bleed vertical="4">
+      <Bleed horizontal="4">
         <Placeholder label="Horizontal" />
       </Bleed>
     </Box>

From dd22019ed5dc725fc6b18f7e03b90dfcce9ff6cb Mon Sep 17 00:00:00 2001
From: Chaz Dean <59836805+chazdean@users.noreply.github.com>
Date: Thu, 3 Nov 2022 10:02:14 -0400
Subject: [PATCH 3/3] Remove `nullish` from `Placeholder` component

---
 .changeset/wild-seas-notice.md                                | 2 +-
 polaris.shopify.com/pages/examples/bleed-all-directions.tsx   | 4 ++--
 polaris.shopify.com/pages/examples/bleed-horizontal.tsx       | 4 ++--
 .../pages/examples/bleed-specific-direction.tsx               | 4 ++--
 polaris.shopify.com/pages/examples/bleed-vertical.tsx         | 4 ++--
 5 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.changeset/wild-seas-notice.md b/.changeset/wild-seas-notice.md
index 98681faa539..67d8ce79da0 100644
--- a/.changeset/wild-seas-notice.md
+++ b/.changeset/wild-seas-notice.md
@@ -2,4 +2,4 @@
 'polaris.shopify.com': patch
 ---
 
-Updated `Bleed` component docs
+Updated `Bleed` component guidance and examples
diff --git a/polaris.shopify.com/pages/examples/bleed-all-directions.tsx b/polaris.shopify.com/pages/examples/bleed-all-directions.tsx
index 613fefb0e65..3e39626d78a 100644
--- a/polaris.shopify.com/pages/examples/bleed-all-directions.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-all-directions.tsx
@@ -19,8 +19,8 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
       style={{
         background: '#7B47F1',
         padding: '14px var(--p-space-2)',
-        height: height ?? undefined,
-        width: width ?? undefined,
+        height: height,
+        width: width,
       }}
     >
       <Inline align="center">
diff --git a/polaris.shopify.com/pages/examples/bleed-horizontal.tsx b/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
index 0343371e263..c20de1c4877 100644
--- a/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
@@ -19,8 +19,8 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
       style={{
         background: '#7B47F1',
         padding: '14px var(--p-space-2)',
-        height: height ?? undefined,
-        width: width ?? undefined,
+        height: height,
+        width: width,
       }}
     >
       <Inline align="center">
diff --git a/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx b/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx
index feba7cb2c6e..82805f60fb6 100644
--- a/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx
@@ -36,8 +36,8 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
       style={{
         background: '#7B47F1',
         padding: '14px var(--p-space-2)',
-        height: height ?? undefined,
-        width: width ?? undefined,
+        height: height,
+        width: width,
       }}
     >
       <Inline align="center">
diff --git a/polaris.shopify.com/pages/examples/bleed-vertical.tsx b/polaris.shopify.com/pages/examples/bleed-vertical.tsx
index 4abf9538258..ee3829fc323 100644
--- a/polaris.shopify.com/pages/examples/bleed-vertical.tsx
+++ b/polaris.shopify.com/pages/examples/bleed-vertical.tsx
@@ -19,8 +19,8 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
       style={{
         background: '#7B47F1',
         padding: '14px var(--p-space-2)',
-        height: height ?? undefined,
-        width: width ?? undefined,
+        height: height,
+        width: width,
       }}
     >
       <Inline align="center">