diff --git a/assets/settings/default.json b/assets/settings/default.json
index 89c134522c..dd25493d42 100644
--- a/assets/settings/default.json
+++ b/assets/settings/default.json
@@ -1,5 +1,18 @@
 {
-  // The name of the Zed theme to use for the UI
+  // The name of the Zed theme to use for the UI.
+  //
+  // The theme can also be set to follow system preferences:
+  //
+  // "theme": {
+  //   "mode": "system",
+  //   "light": "One Light",
+  //   "dark": "One Dark"
+  // }
+  //
+  // Where `mode` is one of:
+  // - "system": Use the theme that corresponds to the system's appearance
+  // - "light": Use the theme indicated by the "light" field
+  // - "dark": Use the theme indicated by the "dark" field
   "theme": "One Dark",
   // The name of a base set of key bindings to use.
   // This setting can take four values, each named after another