docs: new themes docs

1 files changed, 267 insertions, 20 deletions

diff --git a/packages/web/src/content/docs/docs/themes.mdx b/packages/web/src/content/docs/docs/themes.mdx
index ac8f489cb..269e30f8b 100644
--- a/packages/web/src/content/docs/docs/themes.mdx
+++ b/packages/web/src/content/docs/docs/themes.mdx
@@ -2,43 +2,290 @@
 title: Themes
 ---
 
-opencode will support most common terminal themes and you'll soon be able to create your own custom theme.
+opencode supports a flexible JSON-based theme system that allows users to create and customize themes easily.
 
----
+## Theme Loading Hierarchy
 
-## Built-in
+Themes are loaded from multiple directories in the following order (later directories override earlier ones):
 
-The following built-in themes are available:
+1. **Built-in themes** - Embedded in the binary
+2. **User config directory** - `~/.config/opencode/themes/*.json` (or `$XDG_CONFIG_HOME/opencode/themes/*.json`)
+3. **Project root directory** - `<project-root>/.opencode/themes/*.json`
+4. **Current working directory** - `./.opencode/themes/*.json`
 
-- `opencode`
+If multiple directories contain a theme with the same name, the theme from the directory with higher priority will be used.
 
-  ![opencode theme](../../../assets/themes/opencode.png)
+## Creating a Custom Theme
 
-- `ayu`
+To create a custom theme, create a JSON file in one of the theme directories:
 
-  ![ayu theme](../../../assets/themes/ayu.png)
+```bash no-frame
+# For user-wide themes
+mkdir -p ~/.config/opencode/themes
+vim ~/.config/opencode/themes/my-theme.json
 
-- `everforest`
+# For project-specific themes
+mkdir -p .opencode/themes
+vim .opencode/themes/my-theme.json
+```
 
-  ![everforest theme](../../../assets/themes/everforest.png)
+## Theme JSON Format
 
-- `tokyonight`
+Themes use a flexible JSON format with support for:
 
-  ![tokyonight theme](../../../assets/themes/tokyonight.png)
+- **Hex colors**: `"#ffffff"`
+- **ANSI colors**: `3` (0-255)
+- **Color references**: `"primary"` or custom definitions
+- **Dark/light variants**: `{"dark": "#000", "light": "#fff"}`
 
----
+### Example Theme
 
-## Configure
+```json no-frame
+{
+  "$schema": "https://opencode.ai/theme.json",
+  "defs": {
+    "nord0": "#2E3440",
+    "nord1": "#3B4252",
+    "nord2": "#434C5E",
+    "nord3": "#4C566A",
+    "nord4": "#D8DEE9",
+    "nord5": "#E5E9F0",
+    "nord6": "#ECEFF4",
+    "nord7": "#8FBCBB",
+    "nord8": "#88C0D0",
+    "nord9": "#81A1C1",
+    "nord10": "#5E81AC",
+    "nord11": "#BF616A",
+    "nord12": "#D08770",
+    "nord13": "#EBCB8B",
+    "nord14": "#A3BE8C",
+    "nord15": "#B48EAD"
+  },
+  "theme": {
+    "primary": {
+      "dark": "nord8",
+      "light": "nord10"
+    },
+    "secondary": {
+      "dark": "nord9",
+      "light": "nord9"
+    },
+    "accent": {
+      "dark": "nord7",
+      "light": "nord7"
+    },
+    "error": {
+      "dark": "nord11",
+      "light": "nord11"
+    },
+    "warning": {
+      "dark": "nord12",
+      "light": "nord12"
+    },
+    "success": {
+      "dark": "nord14",
+      "light": "nord14"
+    },
+    "info": {
+      "dark": "nord8",
+      "light": "nord10"
+    },
+    "text": {
+      "dark": "nord4",
+      "light": "nord0"
+    },
+    "textMuted": {
+      "dark": "nord3",
+      "light": "nord1"
+    },
+    "background": {
+      "dark": "nord0",
+      "light": "nord6"
+    },
+    "backgroundPanel": {
+      "dark": "nord1",
+      "light": "nord5"
+    },
+    "backgroundElement": {
+      "dark": "nord1",
+      "light": "nord4"
+    },
+    "border": {
+      "dark": "nord2",
+      "light": "nord3"
+    },
+    "borderActive": {
+      "dark": "nord3",
+      "light": "nord2"
+    },
+    "borderSubtle": {
+      "dark": "nord2",
+      "light": "nord3"
+    },
+    "diffAdded": {
+      "dark": "nord14",
+      "light": "nord14"
+    },
+    "diffRemoved": {
+      "dark": "nord11",
+      "light": "nord11"
+    },
+    "diffContext": {
+      "dark": "nord3",
+      "light": "nord3"
+    },
+    "diffHunkHeader": {
+      "dark": "nord3",
+      "light": "nord3"
+    },
+    "diffHighlightAdded": {
+      "dark": "nord14",
+      "light": "nord14"
+    },
+    "diffHighlightRemoved": {
+      "dark": "nord11",
+      "light": "nord11"
+    },
+    "diffAddedBg": {
+      "dark": "#3B4252",
+      "light": "#E5E9F0"
+    },
+    "diffRemovedBg": {
+      "dark": "#3B4252",
+      "light": "#E5E9F0"
+    },
+    "diffContextBg": {
+      "dark": "nord1",
+      "light": "nord5"
+    },
+    "diffLineNumber": {
+      "dark": "nord2",
+      "light": "nord4"
+    },
+    "diffAddedLineNumberBg": {
+      "dark": "#3B4252",
+      "light": "#E5E9F0"
+    },
+    "diffRemovedLineNumberBg": {
+      "dark": "#3B4252",
+      "light": "#E5E9F0"
+    },
+    "markdownText": {
+      "dark": "nord4",
+      "light": "nord0"
+    },
+    "markdownHeading": {
+      "dark": "nord8",
+      "light": "nord10"
+    },
+    "markdownLink": {
+      "dark": "nord9",
+      "light": "nord9"
+    },
+    "markdownLinkText": {
+      "dark": "nord7",
+      "light": "nord7"
+    },
+    "markdownCode": {
+      "dark": "nord14",
+      "light": "nord14"
+    },
+    "markdownBlockQuote": {
+      "dark": "nord3",
+      "light": "nord3"
+    },
+    "markdownEmph": {
+      "dark": "nord12",
+      "light": "nord12"
+    },
+    "markdownStrong": {
+      "dark": "nord13",
+      "light": "nord13"
+    },
+    "markdownHorizontalRule": {
+      "dark": "nord3",
+      "light": "nord3"
+    },
+    "markdownListItem": {
+      "dark": "nord8",
+      "light": "nord10"
+    },
+    "markdownListEnumeration": {
+      "dark": "nord7",
+      "light": "nord7"
+    },
+    "markdownImage": {
+      "dark": "nord9",
+      "light": "nord9"
+    },
+    "markdownImageText": {
+      "dark": "nord7",
+      "light": "nord7"
+    },
+    "markdownCodeBlock": {
+      "dark": "nord4",
+      "light": "nord0"
+    },
+    "syntaxComment": {
+      "dark": "nord3",
+      "light": "nord3"
+    },
+    "syntaxKeyword": {
+      "dark": "nord9",
+      "light": "nord9"
+    },
+    "syntaxFunction": {
+      "dark": "nord8",
+      "light": "nord8"
+    },
+    "syntaxVariable": {
+      "dark": "nord7",
+      "light": "nord7"
+    },
+    "syntaxString": {
+      "dark": "nord14",
+      "light": "nord14"
+    },
+    "syntaxNumber": {
+      "dark": "nord15",
+      "light": "nord15"
+    },
+    "syntaxType": {
+      "dark": "nord7",
+      "light": "nord7"
+    },
+    "syntaxOperator": {
+      "dark": "nord9",
+      "light": "nord9"
+    },
+    "syntaxPunctuation": {
+      "dark": "nord4",
+      "light": "nord0"
+    }
+  }
+}
+```
 
-To select a theme, type in:
+### Color Definitions
 
-```bash frame="none"
-/themes
-```
+The `defs` section (optional) allows you to define reusable colors that can be referenced in the theme.
+
+## Built-in Themes
+
+OpenCode comes with several built-in themes:
+- `opencode` - Default OpenCode theme
+- `tokyonight` - Tokyo Night theme
+- `everforest` - Everforest theme
+- `ayu` - Ayu dark theme
+- `catppuccin` - Catppuccin theme
+- `gruvbox` - Gruvbox theme
+- `kanagawa` - Kanagawa theme
+- `nord` - Nord theme
+- and more (see ./packages/tui/internal/theme/themes)
 
-Your selected theme will be used the next time you start opencode.
+## Using a Theme
 
-You can also configure it in your opencode config.
+To use a theme, set it in your OpenCode configuration or select it from the theme dialog in the TUI.
 
 ```json title="opencode.json" {3}
 {