Improve comments for docs. Add better default spacing for Inline (#7593)

Part of user testing fixes:
#7592

Author: kyledurand

.changeset/red-jeans-clean.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': patch
+---
+
+Improved comments across layout components, changed default spacing of Inline component to match AlphaStack

polaris-react/src/components/AlphaCard/AlphaCard.tsx

@@ -17,8 +17,15 @@ type CardBackgroundColorTokenScale = Extract<
 export interface AlphaCardProps {
   /** Elements to display inside card */
   children?: React.ReactNode;
+  /** Background color
+   * @default 'surface'
+   */
   background?: CardBackgroundColorTokenScale;
+  /** The spacing around the card
+   * @default '5'
+   */
   padding?: SpacingSpaceScale;
+  /** Border radius value above a set breakpoint */
   roundedAbove?: BreakpointsAlias;
 }
 

polaris-react/src/components/AlphaStack/AlphaStack.tsx

@@ -17,15 +17,21 @@ type Element = 'div' | 'ul' | 'ol' | 'fieldset';
 type Spacing = ResponsiveProp<SpacingSpaceScale>;
 
 export interface AlphaStackProps {
-  /** HTML Element type */
+  /** HTML Element type
+   * @default 'div'
+   */
   as?: Element;
   /** Elements to display inside stack */
   children?: React.ReactNode;
-  /** Adjust vertical alignment of elements */
+  /** The vertical alignment of elements
+   * @default 'start'
+   */
   align?: Align;
   /** Toggle elements to be full width */
   fullWidth?: boolean;
-  /** Adjust spacing between elements */
+  /** The spacing between elements
+   * @default '4'
+   */
   spacing?: Spacing;
 }
 

polaris-react/src/components/Bleed/Bleed.tsx

@@ -5,22 +5,22 @@ import {sanitizeCustomProperties} from '../../utilities/css';
 
 import styles from './Bleed.scss';
 
-interface Spacing {
-  bottom: SpacingSpaceScale;
-  left: SpacingSpaceScale;
-  right: SpacingSpaceScale;
-  top: SpacingSpaceScale;
-}
-
 export interface BleedProps {
   /** Elements to display inside tile */
   children: React.ReactNode;
+  /** Negative space around the element */
   spacing?: SpacingSpaceScale;
+  /** Negative horizontal space around the element */
   horizontal?: SpacingSpaceScale;
+  /** Negative vertical space around the element */
   vertical?: SpacingSpaceScale;
+  /** Negative top space around the element */
   top?: SpacingSpaceScale;
+  /** Negative bottom space around the element */
   bottom?: SpacingSpaceScale;
+  /** Negative left space around the element */
   left?: SpacingSpaceScale;
+  /** Negative right space around the element */
   right?: SpacingSpaceScale;
 }
 
@@ -58,26 +58,24 @@ export const Bleed = ({
     }
   };
 
-  const negativeMargins = {
-    top: getNegativeMargins('top'),
-    left: getNegativeMargins('left'),
-    right: getNegativeMargins('right'),
-    bottom: getNegativeMargins('bottom'),
-  } as Spacing;
+  const negativeTop = getNegativeMargins('top');
+  const negativeLeft = getNegativeMargins('left');
+  const negativeRight = getNegativeMargins('right');
+  const negativeBottom = getNegativeMargins('bottom');
 
   const style = {
-    ...(negativeMargins.bottom
-      ? {'--pc-bleed-margin-bottom': `var(--p-space-${negativeMargins.bottom})`}
-      : undefined),
-    ...(negativeMargins.left
-      ? {'--pc-bleed-margin-left': `var(--p-space-${negativeMargins.left})`}
-      : undefined),
-    ...(negativeMargins.right
-      ? {'--pc-bleed-margin-right': `var(--p-space-${negativeMargins.right})`}
-      : undefined),
-    ...(negativeMargins.top
-      ? {'--pc-bleed-margin-top': `var(--p-space-${negativeMargins.top})`}
-      : undefined),
+    '--pc-bleed-margin-bottom': negativeBottom
+      ? `var(--p-space-${negativeBottom})`
+      : undefined,
+    '--pc-bleed-margin-left': negativeLeft
+      ? `var(--p-space-${negativeLeft})`
+      : undefined,
+    '--pc-bleed-margin-right': negativeRight
+      ? `var(--p-space-${negativeRight})`
+      : undefined,
+    '--pc-bleed-margin-top': negativeTop
+      ? `var(--p-space-${negativeTop})`
+      : undefined,
   } as React.CSSProperties;
 
   return (

polaris-react/src/components/Columns/Columns.tsx

@@ -17,7 +17,9 @@ type Spacing = {
 };
 
 export interface ColumnsProps {
-  /** The space between columns */
+  /** The spacing between columns
+   * @default '4'
+   */
   spacing?: Spacing;
   /** The number of columns to display
    * @default {xs: 6, sm: 6, md: 6, lg: 6, xl: 6}

polaris-react/src/components/Inline/Inline.tsx

@@ -19,7 +19,9 @@ export interface InlineProps {
   children?: React.ReactNode;
   /** Wrap stack elements to additional rows as needed on small screens (Defaults to true) */
   wrap?: boolean;
-  /** Adjust spacing between elements */
+  /** The spacing between elements
+   * @default '4'
+   */
   spacing?: SpacingSpaceScale;
   /** Adjust vertical alignment of elements */
   alignY?: keyof typeof AlignY;