From bc28b64df0d40b050ac503c37613ad57fffd1f24 Mon Sep 17 00:00:00 2001
From: Andrew Cherniavskyi <andrew@mui.com>
Date: Tue, 15 Jul 2025 19:58:57 +0200
Subject: [PATCH 1/2] add callout for array spacing

---
 .../material/customization/spacing/spacing.md | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/data/material/customization/spacing/spacing.md b/docs/data/material/customization/spacing/spacing.md
index d44433bac36c7f..03e9bd95f792ac 100644
--- a/docs/data/material/customization/spacing/spacing.md
+++ b/docs/data/material/customization/spacing/spacing.md
@@ -44,6 +44,44 @@ const theme = createTheme({
 theme.spacing(2); // = '8px'
 ```
 
+:::warning
+Note that when spacing is defined as an array, it only works with positive integers that will be used as array indexes.<br />
+It doesn't support all possible signatures of the `theme.spacing()` helper, for example `theme.spacing(0.5)`, `theme.spacing(-1)`, or `theme.spacing(1, 'auto')`.
+
+If you must use spacing array, consider using a function signature that can handle all possible signatures of the `theme.spacing()` helper:
+
+<details>
+<summary>Spacing function example</summary>
+
+```tsx
+const spacings = [0, 4, 8, 16, 32, 64];
+
+const theme = createTheme({
+  spacing: (factor: number | 'auto' = 0) => {
+    if (factor === 'auto') {
+      return 'auto';
+    }
+    const sign = factor >= 0 ? 1 : -1;
+    const factorAbs = Math.min(Math.abs(factor), spacings.length - 1);
+    if (Number.isInteger(factor)) {
+      return spacings[factorAbs] * sign;
+    }
+    return interpolate(factorAbs, spacings) * sign;
+  },
+});
+
+const interpolate = (value: number, array: readonly number[]) => {
+  const floor = Math.floor(value);
+  const ceil = Math.ceil(value);
+  const diff = value - floor;
+  return array[floor] + (array[ceil] - array[floor]) * diff;
+};
+```
+
+</details>
+
+:::
+
 ## Multiple arity
 
 The `theme.spacing()` helper accepts up to 4 arguments.

From eea600ef5c56a6acc5e00d5585f6bbfed8c9c692 Mon Sep 17 00:00:00 2001
From: Andrew <andrew@mui.com>
Date: Fri, 1 Aug 2025 20:53:02 +0200
Subject: [PATCH 2/2] update default value

---
 docs/data/material/customization/spacing/spacing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data/material/customization/spacing/spacing.md b/docs/data/material/customization/spacing/spacing.md
index 03e9bd95f792ac..6ca330c68a241c 100644
--- a/docs/data/material/customization/spacing/spacing.md
+++ b/docs/data/material/customization/spacing/spacing.md
@@ -57,7 +57,7 @@ If you must use spacing array, consider using a function signature that can hand
 const spacings = [0, 4, 8, 16, 32, 64];
 
 const theme = createTheme({
-  spacing: (factor: number | 'auto' = 0) => {
+  spacing: (factor: number | 'auto' = 1) => {
     if (factor === 'auto') {
       return 'auto';
     }