diff --git a/docs/user/customization.md b/docs/user/customization.md
index c9039286d7..b8309e9813 100644
--- a/docs/user/customization.md
+++ b/docs/user/customization.md
@@ -70,6 +70,40 @@ push down, editor.action.moveLinesDownAction
 
 Now when you say eg "push down air and bat", cursorless will first select the two tokens with a gray hat over the `a` and `b`, then issue the VSCode command `editor.action.moveLinesDownAction`, and then restore your original selection.
 
+## \[Experimental\] Cursorless custom regex scopes
+
+You can define custom scopes using regexes in `user/cursorless-settings/experimental/regex_scope_types.csv`
+
+:::tip
+
+Use `"visualize <scope>"` to see a live preview of the regex scope in [the scope visualizer](./scope-visualizer.md). It updates in real time every time you save `regex_scope_types.csv`.
+
+:::
+
+For example, here's what `"visualize dotted"` would show with the scope type `dotted,"[\w.]+"`:
+
+<div class="light-mode-invert">
+  ![visualization of a custom regex scope](./images/custom-regex-scopes.png)
+</div>
+
+You can then use commands such as
+
+- `"take dotted sun"` to select `user.text` (line 10)
+- `"copy dotted urge"` to copy `user.chrome_mod` (line 11)
+- `"take every dotted urge"` to select `user.chrome_mod`, `shift`, and `a`
+
+:::tip
+
+> Check out [our wiki page](https://github.com/cursorless-dev/cursorless/wiki/Custom-regex-scopes) for a recipe book of user-created regex scopes!
+
+:::
+
+:::warning
+
+Regex matches cannot cross line boundaries (so multiline matches are not supported). The regexes also have the unicode flag set.
+
+:::
+
 ## Toggling "hat" display
 
 It is possible to show / hide the hats with a command. Keep in mind that many users, often after less than a week using Cursorless, find that their brain starts to tune out the hat display. Some start to miss them when they're gone 🥲
diff --git a/docs/user/images/custom-regex-scopes.png b/docs/user/images/custom-regex-scopes.png
new file mode 100644
index 0000000000..b595c6a156
Binary files /dev/null and b/docs/user/images/custom-regex-scopes.png differ
diff --git a/packages/cursorless-org-docs/src/css/custom.css b/packages/cursorless-org-docs/src/css/custom.css
index 911fe1a5d7..9dca5a9900 100644
--- a/packages/cursorless-org-docs/src/css/custom.css
+++ b/packages/cursorless-org-docs/src/css/custom.css
@@ -20,3 +20,7 @@
 [data-theme="dark"] .dark-mode-invert {
   filter: invert(90%) hue-rotate(180deg);
 }
+
+[data-theme="light"] .light-mode-invert {
+  filter: invert(90%) hue-rotate(180deg);
+}