From 70afbac80cdc51cdbd9bbce9ddf01a232b84f48f Mon Sep 17 00:00:00 2001
From: James Long <longster@gmail.com>
Date: Thu, 10 Sep 2026 23:13:53 -0400
Subject: [PATCH] docs(www): add core CLI theme concepts (#48426)

---
 services/www/src/docs/content/cli/theme.mdx | 54 +++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/services/www/src/docs/content/cli/theme.mdx b/services/www/src/docs/content/cli/theme.mdx
index 5fe6af17a9b..f43fccefeef 100644
--- a/services/www/src/docs/content/cli/theme.mdx
+++ b/services/www/src/docs/content/cli/theme.mdx
@@ -1,3 +1,57 @@
 ---
 title: "Theme"
 ---
+
+OpenCode includes built-in light and dark themes. Choose a color scheme in settings, or use colors derived from your terminal.
+
+## Choose a theme
+
+Press `Ctrl+P`, then select **Open settings** to change the theme and color mode.
+
+You can also set them in your global [CLI config](/cli/config):
+
+```json title="~/.config/opencode/cli.json"
+{
+  "$schema": "https://opencode.ai/v2/cli.json",
+  "theme": {
+    "name": "tokyonight",
+    "mode": "system"
+  }
+}
+```
+
+## Color mode
+
+Choose whether OpenCode follows your terminal's appearance or always uses light or dark colors:
+
+| Mode | Behavior |
+| --- | --- |
+| `system` | Follow the terminal's detected light or dark appearance. |
+| `dark` | Always use the theme's dark colors. |
+| `light` | Always use the theme's light colors. |
+
+For example, always use dark colors:
+
+```json title="cli.json"
+{
+  "theme": {
+    "name": "tokyonight",
+    "mode": "dark"
+  }
+}
+```
+
+## Terminal colors
+
+When OpenCode can read your terminal palette, the theme picker also includes `system`. This theme derives its colors from your terminal's foreground, background, and ANSI palette.
+
+```json title="cli.json"
+{
+  "theme": {
+    "name": "system",
+    "mode": "system"
+  }
+}
+```
+
+The theme name `system` selects terminal-derived colors. The color mode `system` follows the terminal's light or dark appearance.