docs: custom themes in extensions (#19219)

docs/cli/themes.md

@@ -54,7 +54,7 @@ used in the CLI.
 
 Add a `customThemes` block to your user, project, or system `settings.json`
 file. Each custom theme is defined as an object with a unique name and a set of
-color keys. For example:
+nested configuration objects. For example:
 
 ```json
 {
@@ -63,50 +63,52 @@ color keys. For example:
       "MyCustomTheme": {
         "name": "MyCustomTheme",
         "type": "custom",
-        "Background": "#181818",
+        "background": {
-        ...
+          "primary": "#181818"
+        },
+        "text": {
+          "primary": "#f0f0f0",
+          "secondary": "#a0a0a0"
+        }
       }
     }
   }
 }
 ```
 
-**Color keys:**
+**Configuration objects:**
 
-- `Background`
+- **`text`**: Defines text colors.
-- `Foreground`
+  - `primary`: The default text color.
-- `LightBlue`
+  - `secondary`: Used for less prominent text.
-- `AccentBlue`
+  - `link`: Color for URLs and links.
-- `AccentPurple`
+  - `accent`: Used for highlights and emphasis.
-- `AccentCyan`
+  - `response`: Precedence over `primary` for rendering model responses.
-- `AccentGreen`
+- **`background`**: Defines background colors.
-- `AccentYellow`
+  - `primary`: The main background color of the UI.
-- `AccentRed`
+  - `diff.added`: Background for added lines in diffs.
-- `Comment`
+  - `diff.removed`: Background for removed lines in diffs.
-- `Gray`
+- **`border`**: Defines border colors.
-- `DiffAdded` (optional, for added lines in diffs)
+  - `default`: The standard border color.
-- `DiffRemoved` (optional, for removed lines in diffs)
+  - `focused`: Border color when an element is focused.
-
+- **`status`**: Colors for status indicators.
-You can also override individual UI text roles by adding a nested `text` object.
+  - `success`: Used for successful operations.
-This object supports the keys `primary`, `secondary`, `link`, `accent`, and
+  - `warning`: Used for warnings.
-`response`. When `text.response` is provided it takes precedence over
+  - `error`: Used for errors.
-`text.primary` for rendering model responses in chat.
+- **`ui`**: Other UI elements.
+  - `comment`: Color for code comments.
+  - `symbol`: Color for code symbols and operators.
+  - `gradient`: An array of colors used for gradient effects.
 
 **Required properties:**
 
 - `name` (must match the key in the `customThemes` object and be a string)
 - `type` (must be the string `"custom"`)
-- `Background`
+
-- `Foreground`
+While all sub-properties are technically optional, we recommend providing at
-- `LightBlue`
+least `background.primary`, `text.primary`, `text.secondary`, and the various
-- `AccentBlue`
+accent colors via `text.link`, `text.accent`, and `status` to ensure a cohesive
-- `AccentPurple`
+UI.
-- `AccentCyan`
-- `AccentGreen`
-- `AccentYellow`
-- `AccentRed`
-- `Comment`
-- `Gray`
 
 You can use either hex codes (e.g., `#FF0000`) **or** standard CSS color names
 (e.g., `coral`, `teal`, `blue`) for any color value. See
@@ -141,22 +143,35 @@ custom theme defined in `settings.json`.
 
 ```json
 {
-  "name": "My File Theme",
+  "name": "Gruvbox Dark",
   "type": "custom",
-  "Background": "#282A36",
+  "background": {
-  "Foreground": "#F8F8F2",
+    "primary": "#282828",
-  "LightBlue": "#82AAFF",
+    "diff": {
-  "AccentBlue": "#61AFEF",
+      "added": "#2b3312",
-  "AccentPurple": "#BD93F9",
+      "removed": "#341212"
-  "AccentCyan": "#8BE9FD",
+    }
-  "AccentGreen": "#50FA7B",
+  },
-  "AccentYellow": "#F1FA8C",
+  "text": {
-  "AccentRed": "#FF5555",
+    "primary": "#ebdbb2",
-  "Comment": "#6272A4",
+    "secondary": "#a89984",
-  "Gray": "#ABB2BF",
+    "link": "#83a598",
-  "DiffAdded": "#A6E3A1",
+    "accent": "#d3869b"
-  "DiffRemoved": "#F38BA8",
+  },
-  "GradientColors": ["#4796E4", "#847ACE", "#C3677F"]
+  "border": {
+    "default": "#3c3836",
+    "focused": "#458588"
+  },
+  "status": {
+    "success": "#b8bb26",
+    "warning": "#fabd2f",
+    "error": "#fb4934"
+  },
+  "ui": {
+    "comment": "#928374",
+    "symbol": "#8ec07c",
+    "gradient": ["#cc241d", "#d65d0e", "#d79921"]
+  }
 }
 ```
 
@@ -180,6 +195,15 @@ untrusted sources.
   same [configuration precedence](../get-started/configuration.md) as other
   settings.
 
+### Themes from extensions
+
+[Extensions](../extensions/reference.md#themes) can also provide custom themes.
+Once an extension is installed and enabled, its themes are automatically added
+to the selection list in the `/theme` command.
+
+Themes from extensions appear with the extension name in parentheses to help you
+identify their source, for example: `shades-of-green (green-extension)`.
+
 ---
 
 ## Dark themes

docs/extensions/index.md

@@ -1,8 +1,8 @@
 # Gemini CLI extensions
 
-Gemini CLI extensions package prompts, MCP servers, custom commands, hooks,
+Gemini CLI extensions package prompts, MCP servers, custom commands, themes,
-sub-agents, and agent skills into a familiar and user-friendly format. With
+hooks, sub-agents, and agent skills into a familiar and user-friendly format.
-extensions, you can expand the capabilities of Gemini CLI and share those
+With extensions, you can expand the capabilities of Gemini CLI and share those
 capabilities with others. They are designed to be easily installable and
 shareable.
 

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

docs/extensions/writing-extensions.md

@@ -21,6 +21,7 @@ Extensions offer a variety of ways to customize Gemini CLI.
 | **[Context file (`GEMINI.md`)](reference.md#contextfilename)** | A markdown file containing instructions that are loaded into the model's context at the start of every session.    | Use this to define the "personality" of your extension, set coding standards, or provide essential knowledge that the model should always have.                                                                                                                                                | CLI provides to model |
 | **[Agent skills](../cli/skills.md)**                           | A specialized set of instructions and workflows that the model activates only when needed.                         | Use this for complex, occasional tasks (like "create a PR" or "audit security") to avoid cluttering the main context window when the skill isn't being used.                                                                                                                                   | Model                 |
 | **[Hooks](../hooks/index.md)**                                 | A way to intercept and customize the CLI's behavior at specific lifecycle events (e.g., before/after a tool call). | Use this when you want to automate actions based on what the model is doing, like validating tool arguments, logging activity, or modifying the model's input/output.                                                                                                                          | CLI                   |
+| **[Custom themes](reference.md#themes)**                       | A set of color definitions to personalize the CLI UI.                                                              | Use this to provide a unique visual identity for your extension or to offer specialized high-contrast or thematic color schemes.                                                                                                                                                               | User (via /theme)     |
 
 ## Step 1: Create a new extension
 

packages/cli/src/commands/extensions/examples/themes-example/README.md

@@ -10,11 +10,14 @@ This is an example of a Gemini CLI extension that adds a custom theme.
     gemini extensions link packages/cli/src/commands/extensions/examples/themes-example
     ```
 
-2.  Set the theme in your settings file (`~/.gemini/config.yaml`):
+2.  Set the theme in your settings file (`~/.gemini/settings.json`):
 
-    ```yaml
+    ```json
-    ui:
+    {
-      theme: 'shades-of-green-theme (themes-example)'
+      "ui": {
+        "theme": "shades-of-green (themes-example)"
+      }
+    }
     ```
 
     Alternatively, you can set it through the UI by running `gemini` and then

packages/cli/src/commands/extensions/examples/themes-example/gemini-extension.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "themes": [
     {
-      "name": "shades-of-green-theme",
+      "name": "shades-of-green",
       "type": "custom",
       "background": {
         "primary": "#1a362a"