diff --git a/src/docs/adding-custom-styles.mdx b/src/docs/adding-custom-styles.mdx
index bf3792fc3..103e0bea4 100644
--- a/src/docs/adding-custom-styles.mdx
+++ b/src/docs/adding-custom-styles.mdx
@@ -580,6 +580,45 @@ The `--value()` function can also take multiple arguments and resolve them left
 }
 ```
 
+#### Default values
+
+Use `--default()` inside `--value()` to support a default value when the utility is used without an explicit value:
+
+```css
+/* [!code filename:CSS] */
+/* [!code word:--default(4)] */
+@utility tab-* {
+  tab-size: --value(integer, --default(4));
+}
+```
+
+This matches both `tab-2` and `tab-4`, as well as just `tab` which uses the default value of `4`:
+
+```css
+/* [!code filename:Compiled CSS] */
+/* [!code highlight:4] */
+.tab {
+  tab-size: 4;
+}
+
+.tab-2 {
+  tab-size: 2;
+}
+```
+
+The `--default()` function can also be used inside `--modifier()` to provide a default value when no modifier is present:
+
+```css
+/* [!code filename:CSS] */
+/* [!code word:--default(1)] */
+@utility tab-* {
+  tab-size: --value(integer);
+  line-height: --modifier(integer, --default(1));
+}
+```
+
+This matches `tab-2/3` with a line-height of `3`, and `tab-2` with a line-height of `1`.
+
 #### Negative values
 
 To support negative values, register separate positive and negative utilities into separate declarations: