Components: Improve docs for the SpaceInput type

packages/components/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Internal
 
 -   `Divider`: Complete TypeScript migration ([#41991](https://github.com/WordPress/gutenberg/pull/41991)).
+-   `Divider`, `Flex`, `Spacer`: Improve documentation for the `SpaceInput` prop ([#42376](https://github.com/WordPress/gutenberg/pull/42376)).
 
 ## 19.15.0 (2022-07-13)
 

packages/components/src/divider/types.ts

@@ -15,14 +15,23 @@ export type DividerProps = Omit<
 > & {
 	/**
 	 * Adjusts all margins on the inline dimension.
+	 *
+	 * Can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+	 * or a literal CSS value string.
 	 */
 	margin?: SpaceInput;
 	/**
 	 * Adjusts the inline-end margin.
+	 *
+	 * Can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+	 * or a literal CSS value string.
 	 */
 	marginEnd?: SpaceInput;
 	/**
 	 * Adjusts the inline-start margin.
+	 *
+	 * Can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+	 * or a literal CSS value string.
 	 */
 	marginStart?: SpaceInput;
 	/**

packages/components/src/flex/types.ts

@@ -35,7 +35,10 @@ export type FlexProps = {
 	 */
 	expanded?: boolean;
 	/**
-	 * Spacing in between each child can be adjusted by using `gap`. The value of `gap` works as a multiplier to the library's grid system (base of `4px`).
+	 * Spacing in between each child can be adjusted by using `gap`.
+	 *
+	 * Can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+	 * or a literal CSS value string.
 	 *
 	 * @default 2
 	 */

packages/components/src/spacer/component.tsx

@@ -23,7 +23,9 @@ function UnconnectedSpacer(
 /**
  * `Spacer` is a primitive layout component that providers inner (`padding`) or outer (`margin`) space in-between components. It can also be used to adaptively provide space within an `HStack` or `VStack`.
  *
- * `Spacer` comes with a bunch of shorthand props to adjust `margin` and `padding`. The values of these props work as a multiplier to the library's grid system (base of `4px`).
+ * `Spacer` comes with a bunch of shorthand props to adjust `margin` and `padding`. The values of these props
+ * can either be a number (which will act as a multiplier to the library's grid system base of 4px),
+ * or a literal CSS value string.
  *
  * ```jsx
  * import { Spacer } from `@wordpress/components`

packages/components/src/ui/utils/space.ts

@@ -1,5 +1,11 @@
 /**
- * A real number or something parsable as a number
+ * The argument value for the `space()` utility function.
+ *
+ * When this is a number or a numeric string, it will be interpreted as a
+ * multiplier for the grid base value (4px). For example, `space( 2 )` will be 8px.
+ *
+ * Otherwise, it will be interpreted as a literal CSS length value. For example,
+ * `space( 'auto' )` will be 'auto', and `space( '2px' )` will be 2px.
  */
 export type SpaceInput = number | string;