[Box] Add support for paddingInline and paddingBlock (#11170)

### WHY are these changes introduced? Resolves #10617. ### WHAT is this pull request doing? Adds: - support for `paddingInline` and `paddingBlock` to reduce the need to set the value redundantly with multiple props - updates to `Box` padding documentation on style guide and storybook - fixes the text color on layout component style guide examples for accessibility <details> <summary>Box padding documentation — before</summary> <img src="https://github.com/Shopify/polaris/assets/26749317/a1e91acb-c9fc-4783-8365-a2ebc48a2fd7" alt="Box padding documentation — before"> </details> <details> <summary>Box padding documentation — after</summary> <img src="https://github.com/Shopify/polaris/assets/26749317/950a7fd0-ced5-41a4-b3e9-a9aea7c89506" alt="Box padding documentation — after"> </details> ### How to 🎩 Example that tests different use cases for Box padding props in the Playground included below. 🖥 [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) <details> <summary>Copy-paste this code in <code>playground/Playground.tsx</code>:</summary> ```jsx import React from 'react'; import {Page, Box, BlockStack, Text} from '../src'; export function Playground() { return ( <Page title="Playground"> {/* Add the code you want to test in here */} <BlockStack gap="800"> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — default </Text> <Box background="bg-surface" borderWidth="025" borderColor="border"> <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — paddingBlock only </Text> <Box background="bg-fill-magic-secondary" paddingBlock="2400" borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — paddingBlock responsive (xs and lg breakpoint) </Text> <Box background="bg-fill-magic-secondary" paddingBlock={{xs: '0', lg: '2400'}} borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — paddingBlock and paddingBlockStart (different values) </Text> <Box background="bg-fill-magic-secondary" paddingBlock="2400" paddingBlockEnd="800" borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — paddingInline only </Text> <Box background="bg-fill-warning-secondary" paddingInline="3200" borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — paddingInline responsive (xs and lg breakpoint) </Text> <Box background="bg-fill-warning-secondary" paddingInline={{xs: '0', lg: '3200'}} borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — paddingInline and paddingInlineEnd (different values) </Text> <Box background="bg-fill-warning-secondary" paddingInline="3200" paddingInlineEnd="800" borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — padding only </Text> <Box background="bg-surface-success" padding="500" borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — padding responsive (xs and lg breakpoint) </Text> <Box background="bg-surface-success" padding={{xs: '0', lg: '500'}} borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — paddingInlineStart, paddingInlineEnd, paddingBlockStart, paddingBlockEnd (different values) </Text> <Box background="bg-fill-critical-secondary" paddingInlineStart="200" paddingInlineEnd="400" paddingBlockStart="600" paddingBlockEnd="800" borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> <BlockStack gap="200"> <Text as="h1" variant="headingLg"> Box padding — paddingInlineStart, paddingInlineEnd, paddingBlockStart, paddingBlockEnd responsive (xs and lg breakpoint) </Text> <Box background="bg-fill-critical-secondary" paddingInlineStart={{xs: '0', lg: '200'}} paddingInlineEnd={{xs: '0', lg: '400'}} paddingBlockStart={{xs: '0', lg: '600'}} paddingBlockEnd={{xs: '0', lg: '800'}} borderWidth="025" borderColor="border" > <Text as="p" variant="bodyMd" truncate> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent aliquet libero et metus tempus, sit amet malesuada justo posuere. Nulla egestas, diam et dapibus maximus, nisl neque tempus sapien, semper tincidunt nulla elit vitae dui. Nulla scelerisque porta ex at mattis. Phasellus tempor augue nec eros egestas laoreet. </Text> </Box> </BlockStack> </BlockStack> </Page> ); } ``` </details> ### 🎩 checklist - [x] 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
Shopify · Nov 15, 2023 · 79cadcf · 79cadcf
1 parent c58632a
commit 79cadcf
Show file tree

Hide file tree

Showing 15 changed files with 166 additions and 40 deletions.
diff --git a/.changeset/serious-days-grow.md b/.changeset/serious-days-grow.md
@@ -0,0 +1,6 @@
+---
+'@shopify/polaris': minor
+'polaris.shopify.com': minor
+---
+
+Added support for `paddingInline` and `paddingBlock` on `Box` component with updated documentation
diff --git a/polaris-react/src/components/Box/Box.stories.tsx b/polaris-react/src/components/Box/Box.stories.tsx
@@ -141,6 +141,69 @@ export function WithBorderRadius() {
   );
 }
 
+export function WithPadding() {
+  return (
+    <BlockStack gap="400">
+      <Box
+        background="bg-surface"
+        padding="100"
+        borderWidth="050"
+        borderColor="border-info"
+      >
+        <Icon source={PaintBrushMajor} tone="base" />
+      </Box>
+      <Box
+        background="bg-surface"
+        paddingBlock="400"
+        borderWidth="050"
+        borderColor="border-info"
+      >
+        <Icon source={PaintBrushMajor} tone="base" />
+      </Box>
+      <Box
+        background="bg-surface"
+        paddingBlockStart="400"
+        borderWidth="050"
+        borderColor="border-info"
+      >
+        <Icon source={PaintBrushMajor} tone="base" />
+      </Box>
+      <Box
+        background="bg-surface"
+        paddingBlockEnd="400"
+        borderWidth="050"
+        borderColor="border-info"
+      >
+        <Icon source={PaintBrushMajor} tone="base" />
+      </Box>
+      <Box
+        background="bg-surface"
+        paddingInline="400"
+        borderWidth="050"
+        borderColor="border-info"
+      >
+        <Icon source={PaintBrushMajor} tone="base" />
+      </Box>
+      <Box
+        background="bg-surface"
+        paddingInlineStart="400"
+        borderWidth="050"
+        borderColor="border-info"
+      >
+        <Icon source={PaintBrushMajor} tone="base" />
+      </Box>
+      <Box
+        background="bg-surface"
+        paddingInlineEnd="400"
+        borderWidth="050"
+        borderColor="border-info"
+      >
+        <Icon source={PaintBrushMajor} tone="base" />
+      </Box>
+    </BlockStack>
+  );
+}
+
 export function WithResponsivePadding() {
   return (
     <BlockStack gap="400">

diff --git a/polaris-react/src/components/Box/Box.tsx b/polaris-react/src/components/Box/Box.tsx
@@ -78,6 +78,12 @@ export interface BoxProps extends React.AriaAttributes {
    * padding={{xs: '200', sm: '300', md: '400', lg: '500', xl: '600'}}
    */
   padding?: Spacing;
+  /** Vertical start and end spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
+   * @example
+   * paddingBlock='400'
+   * paddingBlock={{xs: '200', sm: '300', md: '400', lg: '500', xl: '600'}}
+   */
+  paddingBlock?: Spacing;
   /** Vertical start spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
    * @example
    * paddingBlockStart='400'
@@ -90,6 +96,12 @@ export interface BoxProps extends React.AriaAttributes {
    * paddingBlockEnd={{xs: '200', sm: '300', md: '400', lg: '500', xl: '600'}}
    */
   paddingBlockEnd?: Spacing;
+  /** Horizontal start and end spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
+   * @example
+   * paddingInline='400'
+   * paddingInline={{xs: '200', sm: '300', md: '400', lg: '500', xl: '600'}}
+   */
+  paddingInline?: Spacing;
   /** Horizontal start spacing around children. Accepts a spacing token or an object of spacing tokens for different screen sizes.
    * @example
    * paddingInlineStart='400'
@@ -169,8 +181,10 @@ export const Box = forwardRef<HTMLElement, BoxProps>(
       outlineStyle,
       outlineWidth,
       padding,
+      paddingBlock,
       paddingBlockStart,
       paddingBlockEnd,
+      paddingInline,
       paddingInlineStart,
       paddingInlineEnd,
       role,
@@ -265,27 +279,27 @@ export const Box = forwardRef<HTMLElement, BoxProps>(
       '--pc-box-overflow-y': overflowY,
       ...getResponsiveProps(
         'box',
-        'padding-block-end',
+        'padding-block-start',
         'space',
-        paddingBlockEnd || padding,
+        paddingBlockStart || paddingBlock || padding,
       ),
       ...getResponsiveProps(
         'box',
-        'padding-block-start',
+        'padding-block-end',
         'space',
-        paddingBlockStart || padding,
+        paddingBlockEnd || paddingBlock || padding,
       ),
       ...getResponsiveProps(
         'box',
         'padding-inline-start',
         'space',
-        paddingInlineStart || padding,
+        paddingInlineStart || paddingInline || padding,
       ),
       ...getResponsiveProps(
         'box',
         'padding-inline-end',
         'space',
-        paddingInlineEnd || padding,
+        paddingInlineEnd || paddingInline || padding,
       ),
       '--pc-box-shadow': shadow ? `var(--p-shadow-${shadow})` : undefined,
       '--pc-box-width': width,

diff --git a/polaris.shopify.com/pages/examples/bleed-horizontal.tsx b/polaris.shopify.com/pages/examples/bleed-horizontal.tsx
@@ -32,7 +32,12 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
             color: 'var(--p-color-text-info-on-bg-fill)',
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="regular">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="regular"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>

diff --git a/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx b/polaris.shopify.com/pages/examples/bleed-specific-direction.tsx
@@ -47,7 +47,12 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
             color: 'var(--p-color-text-info-on-bg-fill)',
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="regular">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="regular"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>

diff --git a/polaris.shopify.com/pages/examples/bleed-vertical.tsx b/polaris.shopify.com/pages/examples/bleed-vertical.tsx
@@ -29,7 +29,12 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
             color: 'var(--p-color-text-info-on-bg-fill)',
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="regular">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="regular"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>

diff --git a/polaris.shopify.com/pages/examples/block-stack-with-align.tsx b/polaris.shopify.com/pages/examples/block-stack-with-align.tsx
@@ -59,7 +59,12 @@ const Placeholder = ({
             color: 'var(--p-color-text-info-on-bg-fill)',
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="regular">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="regular"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>

diff --git a/polaris.shopify.com/pages/examples/block-stack-with-inline-align.tsx b/polaris.shopify.com/pages/examples/block-stack-with-inline-align.tsx
@@ -53,7 +53,12 @@ const Placeholder = ({
             color: 'var(--p-color-text-info-on-bg-fill)',
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="regular">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="regular"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>

diff --git a/polaris.shopify.com/pages/examples/box-with-color.tsx b/polaris.shopify.com/pages/examples/box-with-color.tsx
@@ -5,7 +5,7 @@ import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
 
 function BoxWithColorExample() {
   return (
-    <Box background="bg-surface-selected">
+    <Box background="bg-fill-info">
       <Placeholder label="Content inside a box" />
     </Box>
   );

diff --git a/polaris.shopify.com/pages/examples/box-with-padding.tsx b/polaris.shopify.com/pages/examples/box-with-padding.tsx
@@ -8,37 +8,34 @@ function BoxWithPaddingExample() {
     <BlockStack gap="400">
       <div
         style={{
-          backgroundColor: 'var(--p-color-bg-fill-info)',
           width: '586px',
         }}
       >
-        <Box padding="400" width="586px">
+        <Box padding="400" width="586px" background="bg-fill-info">
           <Placeholder label="padding" childAlign="center" />
         </Box>
       </div>
       <InlineStack gap="400">
-        <div style={{backgroundColor: 'var(--p-color-bg-fill-info)'}}>
-          <Box paddingInlineStart="400" width="284px">
-            <Placeholder label="paddingInlineStart" childAlign="start" />
-          </Box>
-        </div>
-        <div style={{backgroundColor: 'var(--p-color-bg-fill-info)'}}>
-          <Box paddingInlineEnd="400" width="284px">
-            <Placeholder label="paddingInlineEnd" childAlign="end" />
-          </Box>
-        </div>
+        <Box paddingInline="400" width="586px" background="bg-fill-info">
+          <Placeholder label="paddingInline" childAlign="center" />
+        </Box>
+        <Box paddingInlineStart="400" width="284px" background="bg-fill-info">
+          <Placeholder label="paddingInlineStart" childAlign="start" />
+        </Box>
+        <Box paddingInlineEnd="400" width="284px" background="bg-fill-info">
+          <Placeholder label="paddingInlineEnd" childAlign="end" />
+        </Box>
       </InlineStack>
       <InlineStack gap="400">
-        <div style={{backgroundColor: 'var(--p-color-bg-fill-info)'}}>
-          <Box paddingBlockStart="400" width="284px">
-            <Placeholder label="paddingBlockStart" childAlign="center" />
-          </Box>
-        </div>
-        <div style={{backgroundColor: 'var(--p-color-bg-fill-info)'}}>
-          <Box paddingBlockEnd="400" width="284px">
-            <Placeholder label="paddingBlockEnd" childAlign="center" />
-          </Box>
-        </div>
+        <Box paddingBlock="400" width="586px" background="bg-fill-info">
+          <Placeholder label="paddingBlock" childAlign="center" />
+        </Box>
+        <Box paddingBlockStart="400" width="284px" background="bg-fill-info">
+          <Placeholder label="paddingBlockStart" childAlign="center" />
+        </Box>
+        <Box paddingBlockEnd="400" width="284px" background="bg-fill-info">
+          <Placeholder label="paddingBlockEnd" childAlign="center" />
+        </Box>
       </InlineStack>
     </BlockStack>
   );
@@ -69,7 +66,12 @@ const Placeholder = ({
             color: 'var(--p-color-text-info-on-bg-fill)',
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="medium">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="medium"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>

diff --git a/polaris.shopify.com/pages/examples/box-with-shadow.tsx b/polaris.shopify.com/pages/examples/box-with-shadow.tsx
@@ -25,7 +25,7 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
           color: 'var(--p-color-text-info-on-bg-fill)',
         }}
       >
-        <Text as="p" variant="bodyMd">
+        <Text as="p" variant="bodyMd" tone="text-inverse">
           {label}
         </Text>
       </div>

diff --git a/polaris.shopify.com/pages/examples/card-with-varying-padding.tsx b/polaris.shopify.com/pages/examples/card-with-varying-padding.tsx
@@ -35,7 +35,7 @@ const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
           color: 'var(--p-color-text-info-on-bg-fill)',
         }}
       >
-        <Text as="h2" variant="bodyMd">
+        <Text as="h2" variant="bodyMd" tone="text-inverse">
           {label}
         </Text>
       </div>

diff --git a/polaris.shopify.com/pages/examples/inline-grid-with-fixed-widths.tsx b/polaris.shopify.com/pages/examples/inline-grid-with-fixed-widths.tsx
@@ -37,7 +37,13 @@ const Placeholder = ({
             width: width ?? undefined,
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="medium" alignment="center">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="medium"
+            alignment="center"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>

diff --git a/polaris.shopify.com/pages/examples/inline-stack-with-align.tsx b/polaris.shopify.com/pages/examples/inline-stack-with-align.tsx
@@ -69,7 +69,12 @@ const Placeholder = ({
             color: 'var(--p-color-text-info-on-bg-fill)',
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="medium">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="medium"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>

diff --git a/polaris.shopify.com/pages/examples/inline-stack-with-block-align.tsx b/polaris.shopify.com/pages/examples/inline-stack-with-block-align.tsx
@@ -81,7 +81,12 @@ const Placeholder = ({
             color: 'var(--p-color-text-info-on-bg-fill)',
           }}
         >
-          <Text as="h2" variant="bodyMd" fontWeight="medium">
+          <Text
+            as="h2"
+            variant="bodyMd"
+            fontWeight="medium"
+            tone="text-inverse"
+          >
             {label}
           </Text>
         </div>
-Original file line number
+Diff line change
@@ Expand Up @@
               color: 'var(--p-color-text-info-on-bg-fill)',
             }}
           >
-            <Text as="p" variant="bodyMd">
+            <Text as="p" variant="bodyMd" tone="text-inverse">
               {label}
             </Text>
           </div>
@@ Expand Down @@