From b1da4a28e6d90d38368afddd89a156dabfe2db66 Mon Sep 17 00:00:00 2001 From: Ed Zynda Date: Fri, 20 Mar 2026 13:15:20 +0300 Subject: [PATCH] docs: add comprehensive theming documentation Add dedicated themes page (www/pages/themes.md) covering built-in themes, custom theme files, config integration, extension API, and precedence rules. Update README with theming section and feature listing. Add /theme to CLI commands reference, theme config to configuration docs, and RegisterTheme/SetTheme/ListThemes to extension capabilities. Add neon-theme to examples index. --- README.md | 31 ++- examples/extensions/README.md | 6 + www/pages/cli/commands.md | 24 +++ www/pages/configuration.md | 24 ++- www/pages/extensions/capabilities.md | 26 +++ www/pages/themes.md | 279 +++++++++++++++++++++++++++ www/tome.config.js | 2 +- 7 files changed, 388 insertions(+), 4 deletions(-) create mode 100644 www/pages/themes.md diff --git a/README.md b/README.md index 03a2b9fe..71ab0e9f 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ A powerful, extensible AI coding agent CLI with multi-provider support, built-in - **Built-in Core Tools**: bash, read, write, edit, grep, find, ls, spawn_subagent - no MCP overhead - **MCP Integration**: Connect external MCP servers for expanded capabilities - **Extension System**: Write custom tools, commands, widgets, and UI modifications in Go +- **Theming**: 22 built-in color themes (KITT, Catppuccin, Dracula, Nord, etc.) with runtime switching and custom theme files - **Interactive TUI**: Rich terminal interface powered by Bubble Tea with streaming, syntax highlighting, and custom rendering - **Session Management**: Tree-based conversation history with branching support - **Non-Interactive Mode**: Script-friendly positional args with JSON output @@ -221,9 +222,35 @@ kit acp # Start as ACP agent (stdio JSON-RPC) kit acp --debug # With debug logging to stderr ``` +## Themes + +Kit ships with 22 built-in color themes that control all UI elements. Switch at runtime: + +``` +/theme dracula +/theme catppuccin +/theme tokyonight +``` + +### Custom themes + +Drop a `.yml` file in `~/.config/kit/themes/` (user) or `.kit/themes/` (project): + +```yaml +# ~/.config/kit/themes/my-theme.yml +primary: + light: "#8839ef" + dark: "#cba6f7" +success: + light: "#40a02b" + dark: "#a6e3a1" +``` + +Built-in themes: `kitt`, `catppuccin`, `dracula`, `tokyonight`, `nord`, `gruvbox`, `monokai`, `solarized`, `github`, `one-dark`, `rose-pine`, `ayu`, `material`, `everforest`, `kanagawa`, `amoled`, `synthwave`, `vesper`, `flexoki`, `matrix`, `vercel`, `zenburn` + ## Extension System -Extensions are Go source files that run via Yaegi interpreter. They can add custom tools, slash commands, widgets, keyboard shortcuts, and intercept lifecycle events. +Extensions are Go source files that run via Yaegi interpreter. They can add custom tools, slash commands, widgets, keyboard shortcuts, themes, and intercept lifecycle events. ### Minimal Extension @@ -268,6 +295,7 @@ kit -e examples/extensions/minimal.go - **Interactive Prompts**: Select, confirm, input, and multi-select dialogs - **Subagents**: Spawn in-process child Kit instances - **LLM Completion**: Direct model calls via `Complete()` +- **Themes**: Register and switch color themes via `RegisterTheme`, `SetTheme`, `ListThemes` - **Custom Events**: Inter-extension communication via `EmitCustomEvent` ### Extension Examples @@ -300,6 +328,7 @@ See the `examples/extensions/` directory: - `subagent-test.go` - Subagent testing utilities - `summarize.go` - Conversation summarization - `tool-logger.go` - Log all tool calls +- `neon-theme.go` - Custom theme registration and switching - `tool-renderer-demo.go` - Custom tool call rendering - `widget-status.go` - Persistent status widgets diff --git a/examples/extensions/README.md b/examples/extensions/README.md index e63ac468..c1e60f05 100644 --- a/examples/extensions/README.md +++ b/examples/extensions/README.md @@ -83,6 +83,12 @@ kit install github.com/mark3labs/kit/examples/extensions --local |-----------|-------------|---------| | `kit-telegram/` | Telegram relay for remote monitoring & control | `RegisterCommand`, `OnAgentStart/End`, `SetStatus`, `SendMessage` | +### Themes + +| Extension | Description | Key API | +|-----------|-------------|---------| +| `neon-theme.go` | Register and switch custom themes | `RegisterTheme`, `SetTheme` | + ### Rendering | Extension | Description | Key API | diff --git a/www/pages/cli/commands.md b/www/pages/cli/commands.md index 624b9023..9be87e14 100644 --- a/www/pages/cli/commands.md +++ b/www/pages/cli/commands.md @@ -55,6 +55,30 @@ kit install --all # Install all extensions without prompting kit skill # Install the Kit extensions skill via skills.sh ``` +## Interactive slash commands + +These commands are available inside the Kit TUI during an interactive session: + +| Command | Description | +|---------|-------------| +| `/help` | Show available commands | +| `/tools` | List available MCP tools | +| `/servers` | Show connected MCP servers | +| `/model [name]` | Switch model or open model selector | +| `/theme [name]` | Switch color theme or list available themes | +| `/thinking [level]` | Set thinking level (off, minimal, low, medium, high) | +| `/compact [focus]` | Summarize older messages to free context | +| `/clear` | Clear conversation | +| `/clear-queue` | Clear queued messages | +| `/usage` | Show token usage | +| `/reset-usage` | Reset usage statistics | +| `/tree` | Navigate session tree | +| `/fork` | Branch from an earlier message | +| `/new` | Start a new session | +| `/name` | Set session display name | +| `/session` | Show session info | +| `/quit` | Exit Kit | + ## ACP server Run Kit as an [ACP (Agent Client Protocol)](https://agentclientprotocol.com) agent server. ACP-compatible clients communicate with Kit over JSON-RPC 2.0 on stdin/stdout. diff --git a/www/pages/configuration.md b/www/pages/configuration.md index 1b5bd5b9..a02e37fe 100644 --- a/www/pages/configuration.md +++ b/www/pages/configuration.md @@ -42,8 +42,7 @@ stream: true | `provider-url` | string | — | Base URL for provider API | | `tls-skip-verify` | bool | `false` | Skip TLS certificate verification | | `stop-sequences` | list | — | Custom stop sequences | -| `theme` | string | — | UI theme | -| `markdown-theme` | string | — | Markdown rendering theme | +| `theme` | object or string | — | UI theme ([inline overrides or file path](/themes)) | ## Environment variables @@ -94,3 +93,24 @@ mcpServers: | `excludedTools` | list | Blacklist of tool names to hide | A legacy format with `transport`, `args`, `env`, and `headers` fields is also supported. + +## Theme configuration + +Set theme colors inline or reference an external file: + +```yaml +# Inline partial overrides (unspecified fields inherit from default) +theme: + primary: + light: "#8839ef" + dark: "#cba6f7" + error: + dark: "#FF0000" +``` + +```yaml +# Reference external theme file +theme: "./themes/my-custom-theme.yml" +``` + +See [Themes](/themes) for the full theme file format, built-in themes, and the extension theme API. diff --git a/www/pages/extensions/capabilities.md b/www/pages/extensions/capabilities.md index bd5b28c4..23d5b1fd 100644 --- a/www/pages/extensions/capabilities.md +++ b/www/pages/extensions/capabilities.md @@ -242,6 +242,32 @@ response := ctx.Complete(ext.CompleteRequest{ }) ``` +## Themes + +Register and switch color themes at runtime: + +```go +// Register a custom theme +ctx.RegisterTheme("neon", ext.ThemeColorConfig{ + Primary: ext.ThemeColor{Light: "#CC00FF", Dark: "#FF00FF"}, + Secondary: ext.ThemeColor{Light: "#0088CC", Dark: "#00FFFF"}, + Success: ext.ThemeColor{Light: "#00CC44", Dark: "#00FF66"}, + Warning: ext.ThemeColor{Light: "#CCAA00", Dark: "#FFFF00"}, + Error: ext.ThemeColor{Light: "#CC0033", Dark: "#FF0055"}, + Info: ext.ThemeColor{Light: "#0088CC", Dark: "#00CCFF"}, + Text: ext.ThemeColor{Light: "#111111", Dark: "#F0F0F0"}, + Background: ext.ThemeColor{Light: "#F0F0F0", Dark: "#0A0A14"}, +}) + +// Switch to it +ctx.SetTheme("neon") + +// List all available themes +names := ctx.ListThemes() +``` + +See [Themes](/themes) for the full theme file format, built-in themes, and color reference. + ## Custom events Inter-extension communication: diff --git a/www/pages/themes.md b/www/pages/themes.md new file mode 100644 index 00000000..4f6b8658 --- /dev/null +++ b/www/pages/themes.md @@ -0,0 +1,279 @@ +--- +title: Themes +description: Customize Kit's appearance with built-in themes, custom theme files, and the extension theme API. +--- + +# Themes + +Kit ships with 22 built-in color themes and supports custom themes via YAML/JSON files or the extension API. Themes control all UI colors: input borders, popups, system messages, markdown rendering, syntax highlighting, and diff displays. + +## Quick start + +Switch themes at runtime with the `/theme` command: + +``` +/theme dracula +/theme catppuccin +/theme kitt +``` + +Run `/theme` with no arguments to list all available themes. + +## Built-in themes + +| Theme | Style | +|-------|-------| +| `kitt` | KITT-inspired reds and ambers (default) | +| `catppuccin` | Soothing pastels (Mocha/Latte) | +| `dracula` | Purple and cyan dark theme | +| `tokyonight` | Cool blues with warm accents | +| `nord` | Arctic, north-bluish palette | +| `gruvbox` | Retro groove colors | +| `monokai` | Classic syntax theme | +| `solarized` | Precision colors for machines and people | +| `github` | GitHub's light and dark palettes | +| `one-dark` | Atom One Dark | +| `rose-pine` | Soho vibes with muted tones | +| `ayu` | Simple with bright colors | +| `material` | Material Design palette | +| `everforest` | Green-focused comfortable theme | +| `kanagawa` | Dark theme inspired by Katsushika Hokusai | +| `amoled` | Pure black background, vivid accents | +| `synthwave` | Retro neon glows | +| `vesper` | Warm minimalist dark theme | +| `flexoki` | Inky reading palette | +| `matrix` | Green-on-black terminal aesthetic | +| `vercel` | Clean monochrome with blue accents | +| `zenburn` | Low-contrast, warm dark theme | + +All themes support both light and dark terminal modes via adaptive colors. + +## Custom theme files + +Create a `.yml`, `.yaml`, or `.json` file with color definitions. Kit discovers themes from two directories: + +| Location | Scope | Precedence | +|----------|-------|------------| +| `~/.config/kit/themes/` | User (global) | Overrides built-ins | +| `.kit/themes/` | Project-local | Overrides user and built-ins | + +### Theme file format + +A theme file defines adaptive color pairs with `light` and `dark` hex values. Any field left empty inherits from the default KITT theme. + +```yaml +# ~/.config/kit/themes/my-theme.yml + +# Core semantic colors +primary: + light: "#8839ef" + dark: "#cba6f7" +secondary: + light: "#04a5e5" + dark: "#89dceb" +success: + light: "#40a02b" + dark: "#a6e3a1" +warning: + light: "#df8e1d" + dark: "#f9e2af" +error: + light: "#d20f39" + dark: "#f38ba8" +info: + light: "#1e66f5" + dark: "#89b4fa" + +# Text and chrome +text: + light: "#4c4f69" + dark: "#cdd6f4" +muted: + light: "#6c6f85" + dark: "#a6adc8" +very-muted: + light: "#9ca0b0" + dark: "#6c7086" +background: + light: "#eff1f5" + dark: "#1e1e2e" +border: + light: "#acb0be" + dark: "#585b70" +muted-border: + light: "#ccd0da" + dark: "#313244" + +# Semantic roles +system: + light: "#179299" + dark: "#94e2d5" +tool: + light: "#fe640b" + dark: "#fab387" +accent: + light: "#ea76cb" + dark: "#f5c2e7" +highlight: + light: "#e6e9ef" + dark: "#181825" + +# Diff backgrounds +diff-insert-bg: + light: "#d5f0d5" + dark: "#1a3a2a" +diff-delete-bg: + light: "#f5d5d5" + dark: "#3a1a2a" +diff-equal-bg: + light: "#eceef3" + dark: "#232336" +diff-missing-bg: + light: "#e4e6eb" + dark: "#1a1a2e" + +# Code block backgrounds +code-bg: + light: "#eceef3" + dark: "#232336" +gutter-bg: + light: "#e4e6eb" + dark: "#1a1a2e" +write-bg: + light: "#d5f0d5" + dark: "#1a3a2a" + +# Markdown and syntax highlighting +markdown: + heading: + light: "#1e66f5" + dark: "#89b4fa" + link: + light: "#1e66f5" + dark: "#89b4fa" + keyword: + light: "#8839ef" + dark: "#cba6f7" + string: + light: "#40a02b" + dark: "#a6e3a1" + number: + light: "#fe640b" + dark: "#fab387" + comment: + light: "#9ca0b0" + dark: "#6c7086" +``` + +### Partial themes + +You only need to define the colors you want to change. Unspecified fields fall back to the default theme: + +```yaml +# Just override the primary and accent colors +primary: + dark: "#FF00FF" +accent: + dark: "#00FFFF" +``` + +### Distributing themes + +- **Personal**: Drop a file in `~/.config/kit/themes/` +- **Team/project**: Drop a file in `.kit/themes/` and commit it to version control +- **Override built-in**: Name your file the same as a built-in (e.g., `dracula.yml`) and it takes precedence + +## Config file theme + +You can also set theme colors directly in `.kit.yml`: + +```yaml +theme: + primary: + light: "#8839ef" + dark: "#cba6f7" + error: + dark: "#FF0000" +``` + +Or reference an external theme file: + +```yaml +theme: "./themes/my-custom-theme.yml" +``` + +## Extension theme API + +Extensions can register and switch themes programmatically at runtime. + +### Registering a theme + +```go +api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) { + ctx.RegisterTheme("neon", ext.ThemeColorConfig{ + Primary: ext.ThemeColor{Light: "#CC00FF", Dark: "#FF00FF"}, + Secondary: ext.ThemeColor{Light: "#0088CC", Dark: "#00FFFF"}, + Success: ext.ThemeColor{Light: "#00CC44", Dark: "#00FF66"}, + Warning: ext.ThemeColor{Light: "#CCAA00", Dark: "#FFFF00"}, + Error: ext.ThemeColor{Light: "#CC0033", Dark: "#FF0055"}, + Info: ext.ThemeColor{Light: "#0088CC", Dark: "#00CCFF"}, + Text: ext.ThemeColor{Light: "#111111", Dark: "#F0F0F0"}, + Background: ext.ThemeColor{Light: "#F0F0F0", Dark: "#0A0A14"}, + MdKeyword: ext.ThemeColor{Light: "#CC00FF", Dark: "#FF00FF"}, + MdString: ext.ThemeColor{Light: "#00CC44", Dark: "#00FF66"}, + MdComment: ext.ThemeColor{Light: "#888888", Dark: "#555555"}, + }) +}) +``` + +### Switching themes + +```go +err := ctx.SetTheme("dracula") +``` + +### Listing available themes + +```go +names := ctx.ListThemes() +``` + +### ThemeColorConfig fields + +| Field | Description | +|-------|-------------| +| `Primary` | Main brand/accent color | +| `Secondary` | Secondary accent | +| `Success` | Success states | +| `Warning` | Warning states | +| `Error` | Error/critical states | +| `Info` | Informational states | +| `Text` | Primary text | +| `Muted` | Dimmed text | +| `VeryMuted` | Very dimmed text | +| `Background` | Base background | +| `Border` | Panel borders | +| `MutedBorder` | Subtle dividers | +| `System` | System messages | +| `Tool` | Tool-related elements | +| `Accent` | Secondary highlight | +| `Highlight` | Highlighted regions | +| `MdHeading` | Markdown headings | +| `MdLink` | Markdown links | +| `MdKeyword` | Syntax: keywords | +| `MdString` | Syntax: strings | +| `MdNumber` | Syntax: numbers | +| `MdComment` | Syntax: comments | + +Each field is an `ext.ThemeColor` with `Light` and `Dark` hex strings. Empty fields inherit from the default theme. + +## Precedence order + +When multiple sources define the same theme name, later sources win: + +1. Built-in presets (lowest) +2. User themes (`~/.config/kit/themes/`) +3. Project-local themes (`.kit/themes/`) +4. Extension-registered themes (highest) + +Theme changes via `/theme` or `ctx.SetTheme()` take effect immediately on all UI elements, including previously rendered messages. diff --git a/www/tome.config.js b/www/tome.config.js index 7604eb29..06327fd9 100644 --- a/www/tome.config.js +++ b/www/tome.config.js @@ -21,7 +21,7 @@ export default { }, { group: "Configuration", - pages: ["configuration", "providers"], + pages: ["configuration", "providers", "themes"], }, { group: "CLI Reference",