[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

Author: laurkim

.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

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">

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,

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>

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>

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>

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>

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>

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>
   );

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>