UI: Add Stack component leveraging gap spacing design tokens

package.json

@@ -136,7 +136,7 @@
 		"glob": "7.1.2",
 		"husky": "7.0.0",
 		"jest": "29.6.2",
-		"jest-environment-jsdom": "^29.6.2",
+		"jest-environment-jsdom": "^30.2.0",
 		"jest-jasmine2": "29.6.2",
 		"jest-junit": "13.0.0",
 		"jest-message-util": "29.6.2",
@@ -191,7 +191,7 @@
 		"webpack-bundle-analyzer": "4.9.1"
 	},
 	"overrides": {
-		"jsdom": "25.0.1"
+		"jsdom": "26.1.0"
 	},
 	"scripts": {
 		"build": "node ./bin/build.mjs",

packages/scripts/package.json

@@ -64,7 +64,7 @@
 		"filenamify": "^4.2.0",
 		"jest": "^29.6.2",
 		"jest-dev-server": "^10.1.4",
-		"jest-environment-jsdom": "^29.6.2",
+		"jest-environment-jsdom": "^30.2.0",
 		"jest-environment-node": "^29.6.2",
 		"json2php": "^0.0.9",
 		"markdownlint-cli": "^0.31.1",

packages/theme/docs/ds-tokens.md

@@ -123,6 +123,12 @@ Do not edit directly.
 | `--wpds-dimension-padding-surface-sm`  | Small spacing for surfaces          |
 | `--wpds-dimension-padding-surface-md`  | Medium spacing for surfaces         |
 | `--wpds-dimension-padding-surface-lg`  | Large spacing for surfaces          |
+| `--wpds-dimension-gap-2xs`             | 2x extra small gap                  |
+| `--wpds-dimension-gap-xs`              | Extra small gap                     |
+| `--wpds-dimension-gap-sm`              | Small gap                           |
+| `--wpds-dimension-gap-md`              | Medium gap                          |
+| `--wpds-dimension-gap-lg`              | Large gap                           |
+| `--wpds-dimension-gap-xl`              | Extra large gap                     |
 
 ### Elevation
 

packages/theme/src/prebuilt/css/design-tokens.css

@@ -100,6 +100,12 @@
 	--wpds-color-stroke-surface-warning: #d0b381; /* Decorative stroke color used to define warning-toned surface boundaries with normal emphasis. */
 	--wpds-color-stroke-surface-warning-strong: #926300; /* Decorative stroke color used to define warning-toned surface boundaries with strong emphasis. */
 	--wpds-dimension-base: 4px; /* Base dimension unit */
+	--wpds-dimension-gap-2xs: 4px; /* 2x extra small gap */
+	--wpds-dimension-gap-lg: 24px; /* Large gap */
+	--wpds-dimension-gap-md: 16px; /* Medium gap */
+	--wpds-dimension-gap-sm: 12px; /* Small gap */
+	--wpds-dimension-gap-xl: 40px; /* Extra large gap */
+	--wpds-dimension-gap-xs: 8px; /* Extra small gap */
 	--wpds-dimension-padding-surface-2xs: 4px; /* 2x extra small spacing for surfaces */
 	--wpds-dimension-padding-surface-lg: 32px; /* Large spacing for surfaces */
 	--wpds-dimension-padding-surface-md: 24px; /* Medium spacing for surfaces */
@@ -134,6 +140,12 @@
 
 [data-wpds-theme-provider-id][data-wpds-density='default'] {
 	--wpds-dimension-base: 4px; /* Base dimension unit */
+	--wpds-dimension-gap-2xs: 4px; /* 2x extra small gap */
+	--wpds-dimension-gap-lg: 24px; /* Large gap */
+	--wpds-dimension-gap-md: 16px; /* Medium gap */
+	--wpds-dimension-gap-sm: 12px; /* Small gap */
+	--wpds-dimension-gap-xl: 40px; /* Extra large gap */
+	--wpds-dimension-gap-xs: 8px; /* Extra small gap */
 	--wpds-dimension-padding-surface-2xs: 4px; /* 2x extra small spacing for surfaces */
 	--wpds-dimension-padding-surface-lg: 32px; /* Large spacing for surfaces */
 	--wpds-dimension-padding-surface-md: 24px; /* Medium spacing for surfaces */
@@ -142,6 +154,12 @@
 }
 
 [data-wpds-theme-provider-id][data-wpds-density='compact'] {
+	--wpds-dimension-gap-2xs: 4px; /* 2x extra small gap */
+	--wpds-dimension-gap-lg: 20px; /* Large gap */
+	--wpds-dimension-gap-md: 12px; /* Medium gap */
+	--wpds-dimension-gap-sm: 8px; /* Small gap */
+	--wpds-dimension-gap-xl: 32px; /* Extra large gap */
+	--wpds-dimension-gap-xs: 4px; /* Extra small gap */
 	--wpds-dimension-padding-surface-2xs: 4px; /* 2x extra small spacing for surfaces */
 	--wpds-dimension-padding-surface-lg: 24px; /* Large spacing for surfaces */
 	--wpds-dimension-padding-surface-md: 20px; /* Medium spacing for surfaces */
@@ -150,6 +168,12 @@
 }
 
 [data-wpds-theme-provider-id][data-wpds-density='comfortable'] {
+	--wpds-dimension-gap-2xs: 8px; /* 2x extra small gap */
+	--wpds-dimension-gap-lg: 32px; /* Large gap */
+	--wpds-dimension-gap-md: 20px; /* Medium gap */
+	--wpds-dimension-gap-sm: 16px; /* Small gap */
+	--wpds-dimension-gap-xl: 48px; /* Extra large gap */
+	--wpds-dimension-gap-xs: 12px; /* Extra small gap */
 	--wpds-dimension-padding-surface-2xs: 8px; /* 2x extra small spacing for surfaces */
 	--wpds-dimension-padding-surface-lg: 40px; /* Large spacing for surfaces */
 	--wpds-dimension-padding-surface-md: 32px; /* Medium spacing for surfaces */

packages/theme/src/prebuilt/js/design-tokens.js

@@ -106,6 +106,12 @@ export default [
 	'--wpds-dimension-padding-surface-sm',
 	'--wpds-dimension-padding-surface-md',
 	'--wpds-dimension-padding-surface-lg',
+	'--wpds-dimension-gap-2xs',
+	'--wpds-dimension-gap-xs',
+	'--wpds-dimension-gap-sm',
+	'--wpds-dimension-gap-md',
+	'--wpds-dimension-gap-lg',
+	'--wpds-dimension-gap-xl',
 	'--wpds-elevation-x-small',
 	'--wpds-elevation-small',
 	'--wpds-elevation-medium',

packages/theme/src/prebuilt/json/figma.json

@@ -622,6 +622,54 @@
 		},
 		"description": "Large spacing for surfaces"
 	},
+	"Dimension/Semantic/gap-2xs": {
+		"value": {
+			".": "4px",
+			"compact": "4px",
+			"comfortable": "8px"
+		},
+		"description": "2x extra small gap"
+	},
+	"Dimension/Semantic/gap-xs": {
+		"value": {
+			".": "8px",
+			"compact": "4px",
+			"comfortable": "12px"
+		},
+		"description": "Extra small gap"
+	},
+	"Dimension/Semantic/gap-sm": {
+		"value": {
+			".": "12px",
+			"compact": "8px",
+			"comfortable": "16px"
+		},
+		"description": "Small gap"
+	},
+	"Dimension/Semantic/gap-md": {
+		"value": {
+			".": "16px",
+			"compact": "12px",
+			"comfortable": "20px"
+		},
+		"description": "Medium gap"
+	},
+	"Dimension/Semantic/gap-lg": {
+		"value": {
+			".": "24px",
+			"compact": "20px",
+			"comfortable": "32px"
+		},
+		"description": "Large gap"
+	},
+	"Dimension/Semantic/gap-xl": {
+		"value": {
+			".": "40px",
+			"compact": "32px",
+			"comfortable": "48px"
+		},
+		"description": "Extra large gap"
+	},
 	"Elevation/x-small": {
 		"value": {
 			".": "0 1px 1px 0 color(srgb 0 0 0 / 0.03), 0 1px 2px 0 color(srgb 0 0 0 / 0.02), 0 3px 3px 0 color(srgb 0 0 0 / 0.02), 0 4px 4px 0 color(srgb 0 0 0 / 0.01)"

packages/theme/tokens/dimension.json

@@ -103,6 +103,68 @@
 						}
 					}
 				}
+			},
+			"gap": {
+				"2xs": {
+					"$value": "{dimension.primitive.space.10}",
+					"$description": "2x extra small gap",
+					"$extensions": {
+						"mode": {
+							"compact": "{dimension.primitive.space.10}",
+							"comfortable": "{dimension.primitive.space.20}"
+						}
+					}
+				},
+				"xs": {
+					"$value": "{dimension.primitive.space.20}",
+					"$description": "Extra small gap",
+					"$extensions": {
+						"mode": {
+							"compact": "{dimension.primitive.space.10}",
+							"comfortable": "{dimension.primitive.space.30}"
+						}
+					}
+				},
+				"sm": {
+					"$value": "{dimension.primitive.space.30}",
+					"$description": "Small gap",
+					"$extensions": {
+						"mode": {
+							"compact": "{dimension.primitive.space.20}",
+							"comfortable": "{dimension.primitive.space.40}"
+						}
+					}
+				},
+				"md": {
+					"$value": "{dimension.primitive.space.40}",
+					"$description": "Medium gap",
+					"$extensions": {
+						"mode": {
+							"compact": "{dimension.primitive.space.30}",
+							"comfortable": "{dimension.primitive.space.50}"
+						}
+					}
+				},
+				"lg": {
+					"$value": "{dimension.primitive.space.60}",
+					"$description": "Large gap",
+					"$extensions": {
+						"mode": {
+							"compact": "{dimension.primitive.space.50}",
+							"comfortable": "{dimension.primitive.space.70}"
+						}
+					}
+				},
+				"xl": {
+					"$value": "{dimension.primitive.space.80}",
+					"$description": "Extra large gap",
+					"$extensions": {
+						"mode": {
+							"compact": "{dimension.primitive.space.70}",
+							"comfortable": "{dimension.primitive.space.90}"
+						}
+					}
+				}
 			}
 		}
 	}

packages/ui/CONTRIBUTING.md

@@ -25,3 +25,28 @@ src/
 
 -   The folder name should match the primary component name
 -   The `index.ts` file should contain only the public API exports for the component(s)
+
+## CSS Architecture
+
+### CSS Layers
+
+We use [CSS cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers) to ensure an expected order of precedence in style resolution. All component stylesheets must follow this layering approach to maintain consistency and prevent specificity conflicts.
+
+Every component stylesheet must include the layer definition at the top and wrap all styles within the appropriate layer:
+
+```css
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.stack {
+		display: flex;
+	}
+}
+```
+
+#### CSS Layer Hierarchy
+
+-   **`wp-ui-utilities`** - Shared utility styles (box-sizing, focus rings, resets) that apply before component styles
+-   **`wp-ui-components`** - Default styles for design system components (`.stack`, etc.)
+-   **`wp-ui-compositions`** - Internal compositions that extend base components
+-   **`wp-ui-overrides`** - Last-resort styles to override default rules

packages/ui/README.md

@@ -25,7 +25,7 @@ import { Box } from '@wordpress/ui';
 
 function MyComponent() {
 	return (
-		<Box background="neutral" padding="small">
+		<Box background="neutral" padding="sm">
 			Hello World
 		</Box>
 	);

packages/ui/package.json

@@ -34,7 +34,8 @@
 	"sideEffects": false,
 	"dependencies": {
 		"@wordpress/element": "file:../element",
-		"@wordpress/private-apis": "file:../private-apis"
+		"@wordpress/private-apis": "file:../private-apis",
+		"clsx": "^2.1.1"
 	},
 	"devDependencies": {
 		"@wordpress/theme": "file:../theme"

packages/ui/src/box/box.tsx

@@ -92,7 +92,7 @@ export const Box = forwardRef< HTMLDivElement, BoxProps >( function Box(
 	},
 	ref
 ) {
-	const style: React.CSSProperties = {};
+	const style: React.CSSProperties = { ...props.style };
 
 	if ( backgroundColor ) {
 		style.backgroundColor = `var(--wpds-color-bg-${ target }-${ backgroundColor }, var(--wpds-color-bg-surface-${ backgroundColor }))`;
@@ -122,5 +122,9 @@ export const Box = forwardRef< HTMLDivElement, BoxProps >( function Box(
 		style.borderColor = `var(--wpds-color-stroke-${ target }-${ borderColor }, var(--wpds-color-stroke-surface-${ borderColor }))`;
 	}
 
-	return renderElement< 'div' >( render, { style, ...props }, ref );
+	return renderElement< 'div' >( {
+		render,
+		ref,
+		props: { ...props, style },
+	} );
 } );

packages/ui/src/box/test/box.test.tsx

@@ -0,0 +1,40 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { createRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { Box } from '../box';
+
+describe( 'Box', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLDivElement >();
+
+		render( <Box ref={ ref }>Content</Box> );
+
+		expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+	} );
+
+	it( 'merges props', () => {
+		render(
+			<Box backgroundColor="brand" style={ { width: '10px' } }>
+				Content
+			</Box>
+		);
+
+		const box = screen.getByText( 'Content' );
+
+		expect( box ).toHaveStyle( {
+			'background-color':
+				'var(--wpds-color-bg-surface-brand, var(--wpds-color-bg-surface-brand))',
+			width: '10px',
+		} );
+	} );
+} );

packages/ui/src/stack/index.ts

@@ -0,0 +1,4 @@
+/**
+ * Internal dependencies
+ */
+export { Stack } from './stack';