docs: custom themes in extensions (#19219)

docs/extensions/reference.md

@@ -172,6 +172,9 @@ The file has the following structure:
   `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf`
   command. Note that this differs from the MCP server `excludeTools`
   functionality, which can be listed in the MCP server config.
+- `themes`: An array of custom themes provided by the extension. Each theme is
+  an object that defines the color scheme for the CLI UI. See the
+  [Themes guide](../cli/themes.md) for more details on the theme format.
 
 When Gemini CLI starts, it loads all the extensions and merges their
 configurations. If there are any conflicts, the workspace configuration takes
@@ -302,6 +305,50 @@ extension's root folder and add your agent definition files (`.md`) there.
 Gemini CLI will automatically discover and load these agents when the extension
 is installed and enabled.
 
+### Themes
+
+Extensions can provide custom themes to personalize the CLI UI. Themes are
+defined in the `themes` array in `gemini-extension.json`.
+
+**Example**
+
+```json
+{
+  "name": "my-green-extension",
+  "version": "1.0.0",
+  "themes": [
+    {
+      "name": "shades-of-green",
+      "type": "custom",
+      "background": {
+        "primary": "#1a362a"
+      },
+      "text": {
+        "primary": "#a6e3a1",
+        "secondary": "#6e8e7a",
+        "link": "#89e689"
+      },
+      "status": {
+        "success": "#76c076",
+        "warning": "#d9e689",
+        "error": "#b34e4e"
+      },
+      "border": {
+        "default": "#4a6c5a"
+      },
+      "ui": {
+        "comment": "#6e8e7a"
+      }
+    }
+  ]
+}
+```
+
+Custom themes provided by extensions can be selected using the `/theme` command
+or by setting the `ui.theme` property in your `settings.json` file. Note that
+when referring to a theme from an extension, the extension name is appended to
+the theme name in parentheses, e.g., `shades-of-green (my-green-extension)`.
+
 ### Conflict resolution
 
 Extension commands have the lowest precedence. When a conflict occurs with user