Box: Offset padding by border width to ensure equal footprint regardless of configuration

packages/theme/docs/ds-tokens.md

@@ -17,8 +17,6 @@ Do not edit directly.
 | `--wpds-border-radius-surface-lg`       | Large radius for surfaces       |
 | `--wpds-border-width-surface-xs`        | Extra small width for surfaces  |
 | `--wpds-border-width-surface-sm`        | Small width for surfaces        |
-| `--wpds-border-width-surface-md`        | Medium width for surfaces       |
-| `--wpds-border-width-surface-lg`        | Large width for surfaces        |
 | `--wpds-border-width-interactive-focus` | Border width for focus ring     |
 
 ### Color

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

@@ -8,8 +8,6 @@
 	--wpds-border-radius-surface-sm: 2px; /* Small radius for surfaces */
 	--wpds-border-radius-surface-xs: 1px; /* Extra small radius for surfaces */
 	--wpds-border-width-interactive-focus: 2px; /* Border width for focus ring */
-	--wpds-border-width-surface-lg: 8px; /* Large width for surfaces */
-	--wpds-border-width-surface-md: 4px; /* Medium width for surfaces */
 	--wpds-border-width-surface-sm: 2px; /* Small width for surfaces */
 	--wpds-border-width-surface-xs: 1px; /* Extra small width for surfaces */
 	--wpds-color-bg-interactive-brand: #00000000; /* Background color for interactive elements with brand tone and normal emphasis. */

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

@@ -10,8 +10,6 @@ export default [
 	'--wpds-border-radius-surface-lg',
 	'--wpds-border-width-surface-xs',
 	'--wpds-border-width-surface-sm',
-	'--wpds-border-width-surface-md',
-	'--wpds-border-width-surface-lg',
 	'--wpds-border-width-interactive-focus',
 	'--wpds-color-bg-surface-neutral',
 	'--wpds-color-bg-surface-neutral-strong',

packages/theme/tokens/border.json

@@ -30,14 +30,6 @@
 				"sm": {
 					"$value": { "value": 2, "unit": "px" },
 					"$description": "Small width for surfaces"
-				},
-				"md": {
-					"$value": { "value": 4, "unit": "px" },
-					"$description": "Medium width for surfaces"
-				},
-				"lg": {
-					"$value": { "value": 8, "unit": "px" },
-					"$description": "Large width for surfaces"
 				}
 			},
 			"interactive": {

packages/ui/src/box/box.tsx

@@ -31,44 +31,72 @@ const capitalize = ( str: string ): string =>
  * Converts a size value to a CSS design token property reference (with
  * fallback) or a calculated value based on the base unit.
  *
- * @param property The CSS property name.
- * @param target   The design system token target.
- * @param value    The size value, either a number (multiplier of base unit) or a string (token name).
- * @return A CSS value string with variable references.
+ * @param property    The CSS property name.
+ * @param target      The design system token target.
+ * @param value       The size value, either a number (multiplier of base unit) or a string (token name).
+ * @param offsetValue Optional CSS value to subtract (e.g., border width).
+ * @return            A CSS value string with variable references.
  */
 const getSpacingValue = (
 	property: string,
 	target: string,
-	value: number | string
+	value: number | string,
+	offsetValue?: string
+): string => {
+	const baseExpression =
+		typeof value === 'number'
+			? `var(--wpds-dimension-base) * ${ value }`
+			: `var(--wpds-dimension-${ property }-${ target }-${ value }, var(--wpds-dimension-${ property }-surface-${ value }))`;
+
+	if ( offsetValue ) {
+		return `calc(${ baseExpression } - ${ offsetValue })`;
+	}
+
+	return typeof value === 'number'
+		? `calc(${ baseExpression })`
+		: baseExpression;
+};
+
+const getBorderWidthValue = (
+	target: string,
+	borderWidth: Exclude< NonNullable< BoxProps[ 'borderWidth' ] >, number >
 ): string =>
-	typeof value === 'number'
-		? `calc(var(--wpds-dimension-base) * ${ value })`
-		: `var(--wpds-dimension-${ property }-${ target }-${ value }, var(--wpds-dimension-${ property }-surface-${ value }))`;
+	`var(--wpds-border-width-${ target }-${ borderWidth }, var(--wpds-border-width-surface-${ borderWidth }))`;
 
 /**
  * Generates CSS styles for properties with optionally directional values,
  * normalizing single values and objects with directional keys for logical
  * properties.
  *
- * @param property The CSS property name from BoxProps.
- * @param target   The design system token target.
- * @param value    The property value (single or object with directional keys).
- * @return A CSSProperties object with the computed styles.
+ * @param property    The CSS property name from BoxProps.
+ * @param target      The design system token target.
+ * @param value       The property value (single or object with directional keys).
+ * @param offsetValue Optional CSS value to subtract (e.g., border width).
+ * @return            A CSSProperties object with the computed styles.
  */
 const getDimensionVariantStyles = < T extends keyof BoxProps >(
 	property: T,
 	target: string,
-	value: NonNullable< BoxProps[ T ] >
+	value: NonNullable< BoxProps[ T ] >,
+	offsetValue?: string
 ): React.CSSProperties =>
 	typeof value !== 'object'
-		? { [ property ]: getSpacingValue( property, target, value ) }
+		? {
+				[ property ]: getSpacingValue(
+					property,
+					target,
+					value,
+					offsetValue
+				),
+		  }
 		: Object.keys( value ).reduce(
 				( result, key ) => ( {
 					...result,
 					[ property + capitalize( key ) ]: getSpacingValue(
 						property,
 						target,
-						value[ key ]
+						value[ key ],
+						offsetValue
 					),
 				} ),
 				{} as Record< string, string >
@@ -102,19 +130,27 @@ export const Box = forwardRef< HTMLDivElement, BoxProps >( function Box(
 		style.color = `var(--wpds-color-fg-${ target }-${ color }, var(--wpds-color-fg-content-${ color }))`;
 	}
 
+	const borderWidthValue =
+		borderWidth && getBorderWidthValue( target, borderWidth );
+
 	if ( padding ) {
 		Object.assign(
 			style,
-			getDimensionVariantStyles( 'padding', target, padding )
+			getDimensionVariantStyles(
+				'padding',
+				target,
+				padding,
+				borderWidthValue
+			)
 		);
 	}
 
 	if ( borderRadius ) {
 		style.borderRadius = `var(--wpds-border-radius-${ target }-${ borderRadius }, var(--wpds-border-radius-surface-${ borderRadius }))`;
 	}
 
-	if ( borderWidth ) {
-		style.borderWidth = `var(--wpds-border-width-${ target }-${ borderWidth }, var(--wpds-border-width-surface-${ borderWidth }))`;
+	if ( borderWidthValue ) {
+		style.borderWidth = borderWidthValue;
 		style.borderStyle = 'solid';
 	}
 

packages/ui/src/box/stories/index.story.tsx

@@ -30,13 +30,17 @@ export const Default: Story = {
 		padding: 'sm',
 		borderColor: 'brand',
 		borderRadius: 'md',
-		borderWidth: 'sm',
+		borderWidth: 'xs',
 	},
 	argTypes: {
 		padding: {
 			control: 'select',
 			options: [ '2xs', 'xs', 'sm', 'md', 'lg', 1, 2, 3, 4 ],
 		},
+		borderWidth: {
+			control: 'radio',
+			options: [ 'xs', 'sm' ],
+		},
 	},
 };
 

packages/ui/src/box/types.ts

@@ -90,7 +90,7 @@ export interface BoxProps extends ComponentProps< 'div' > {
 	/**
 	 * The surface border width design token.
 	 */
-	borderWidth?: Exclude< SizeToken, '2xs' >;
+	borderWidth?: Exclude< SizeToken, '2xs' | 'md' | 'lg' >;
 
 	/**
 	 * The surface border stroke color design token.