mirror of
https://github.com/getcompanion-ai/co-mono.git
synced 2026-04-15 09:01:14 +00:00
docs(coding-agent): merge theme.md into themes.md, add hot reload info
- Merged theme.md content into themes.md - Added hot reload documentation - Updated all references from theme.md to themes.md - Fixed outdated info (vars not defs, complete example with all 50 tokens) - Removed dev-focused Implementation section
This commit is contained in:
Mario Zechner
parent
94952bd6c0
commit
d79eb99cd2
5 changed files with 263 additions and 631 deletions
|
|
@ -2,7 +2,17 @@
|
|||
|
||||
# Themes
|
||||
|
||||
Themes are JSON files that define colors for the TUI. You can select themes in `/settings` or via `settings.json`.
|
||||
Themes are JSON files that define colors for the TUI.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Locations](#locations)
|
||||
- [Selecting a Theme](#selecting-a-theme)
|
||||
- [Creating a Custom Theme](#creating-a-custom-theme)
|
||||
- [Theme Format](#theme-format)
|
||||
- [Color Tokens](#color-tokens)
|
||||
- [Color Values](#color-values)
|
||||
- [Tips](#tips)
|
||||
|
||||
## Locations
|
||||
|
||||
|
|
@ -17,30 +27,269 @@ Pi loads themes from:
|
|||
|
||||
Disable discovery with `--no-themes`.
|
||||
|
||||
## Format
|
||||
## Selecting a Theme
|
||||
|
||||
Themes use this structure:
|
||||
Select a theme via `/settings` or in `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"theme": "my-theme"
|
||||
}
|
||||
```
|
||||
|
||||
On first run, pi detects your terminal background and defaults to `dark` or `light`.
|
||||
|
||||
## Creating a Custom Theme
|
||||
|
||||
1. Create a theme file:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.pi/agent/themes
|
||||
vim ~/.pi/agent/themes/my-theme.json
|
||||
```
|
||||
|
||||
2. Define the theme with all required colors (see [Color Tokens](#color-tokens)):
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/theme-schema.json",
|
||||
"name": "my-theme",
|
||||
"vars": {
|
||||
"accent": "#00aaff",
|
||||
"muted": 242
|
||||
"primary": "#00aaff",
|
||||
"secondary": 242
|
||||
},
|
||||
"colors": {
|
||||
"accent": "accent",
|
||||
"muted": "muted",
|
||||
"accent": "primary",
|
||||
"border": "primary",
|
||||
"borderAccent": "#00ffff",
|
||||
"borderMuted": "secondary",
|
||||
"success": "#00ff00",
|
||||
"error": "#ff0000",
|
||||
"warning": "#ffff00",
|
||||
"muted": "secondary",
|
||||
"dim": 240,
|
||||
"text": "",
|
||||
"thinkingText": "secondary",
|
||||
"selectedBg": "#2d2d30",
|
||||
"userMessageBg": "#2d2d30",
|
||||
"toolSuccessBg": "#1e2e1e"
|
||||
"userMessageText": "",
|
||||
"customMessageBg": "#2d2d30",
|
||||
"customMessageText": "",
|
||||
"customMessageLabel": "primary",
|
||||
"toolPendingBg": "#1e1e2e",
|
||||
"toolSuccessBg": "#1e2e1e",
|
||||
"toolErrorBg": "#2e1e1e",
|
||||
"toolTitle": "primary",
|
||||
"toolOutput": "",
|
||||
"mdHeading": "#ffaa00",
|
||||
"mdLink": "primary",
|
||||
"mdLinkUrl": "secondary",
|
||||
"mdCode": "#00ffff",
|
||||
"mdCodeBlock": "",
|
||||
"mdCodeBlockBorder": "secondary",
|
||||
"mdQuote": "secondary",
|
||||
"mdQuoteBorder": "secondary",
|
||||
"mdHr": "secondary",
|
||||
"mdListBullet": "#00ffff",
|
||||
"toolDiffAdded": "#00ff00",
|
||||
"toolDiffRemoved": "#ff0000",
|
||||
"toolDiffContext": "secondary",
|
||||
"syntaxComment": "secondary",
|
||||
"syntaxKeyword": "primary",
|
||||
"syntaxFunction": "#00aaff",
|
||||
"syntaxVariable": "#ffaa00",
|
||||
"syntaxString": "#00ff00",
|
||||
"syntaxNumber": "#ff00ff",
|
||||
"syntaxType": "#00aaff",
|
||||
"syntaxOperator": "primary",
|
||||
"syntaxPunctuation": "secondary",
|
||||
"thinkingOff": "secondary",
|
||||
"thinkingMinimal": "primary",
|
||||
"thinkingLow": "#00aaff",
|
||||
"thinkingMedium": "#00ffff",
|
||||
"thinkingHigh": "#ff00ff",
|
||||
"thinkingXhigh": "#ff0000",
|
||||
"bashMode": "#ffaa00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Select the theme via `/settings`.
|
||||
|
||||
**Hot reload:** When you edit the currently active custom theme file, pi reloads it automatically for immediate visual feedback.
|
||||
|
||||
## Theme Format
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/theme-schema.json",
|
||||
"name": "my-theme",
|
||||
"vars": {
|
||||
"blue": "#0066cc",
|
||||
"gray": 242
|
||||
},
|
||||
"colors": {
|
||||
"accent": "blue",
|
||||
"muted": "gray",
|
||||
"text": "",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `name` is required and must be unique.
|
||||
- `vars` is optional. It lets you reuse colors.
|
||||
- `colors` must define all required tokens.
|
||||
- `vars` is optional. Define reusable colors here, then reference them in `colors`.
|
||||
- `colors` must define all 50 required tokens.
|
||||
|
||||
See [theme.md](theme.md) for the full token list, color formats, and validation details.
|
||||
The `$schema` field enables editor auto-completion and validation.
|
||||
|
||||
## Color Tokens
|
||||
|
||||
Every theme must define all 50 color tokens. There are no optional colors.
|
||||
|
||||
### Core UI (11 colors)
|
||||
|
||||
| Token | Purpose |
|
||||
|-------|---------|
|
||||
| `accent` | Primary accent (logo, selected items, cursor) |
|
||||
| `border` | Normal borders |
|
||||
| `borderAccent` | Highlighted borders |
|
||||
| `borderMuted` | Subtle borders (editor) |
|
||||
| `success` | Success states |
|
||||
| `error` | Error states |
|
||||
| `warning` | Warning states |
|
||||
| `muted` | Secondary text |
|
||||
| `dim` | Tertiary text |
|
||||
| `text` | Default text (usually `""`) |
|
||||
| `thinkingText` | Thinking block text |
|
||||
|
||||
### Backgrounds & Content (11 colors)
|
||||
|
||||
| Token | Purpose |
|
||||
|-------|---------|
|
||||
| `selectedBg` | Selected line background |
|
||||
| `userMessageBg` | User message background |
|
||||
| `userMessageText` | User message text |
|
||||
| `customMessageBg` | Extension message background |
|
||||
| `customMessageText` | Extension message text |
|
||||
| `customMessageLabel` | Extension message label |
|
||||
| `toolPendingBg` | Tool box (pending) |
|
||||
| `toolSuccessBg` | Tool box (success) |
|
||||
| `toolErrorBg` | Tool box (error) |
|
||||
| `toolTitle` | Tool title |
|
||||
| `toolOutput` | Tool output text |
|
||||
|
||||
### Markdown (10 colors)
|
||||
|
||||
| Token | Purpose |
|
||||
|-------|---------|
|
||||
| `mdHeading` | Headings |
|
||||
| `mdLink` | Link text |
|
||||
| `mdLinkUrl` | Link URL |
|
||||
| `mdCode` | Inline code |
|
||||
| `mdCodeBlock` | Code block content |
|
||||
| `mdCodeBlockBorder` | Code block fences |
|
||||
| `mdQuote` | Blockquote text |
|
||||
| `mdQuoteBorder` | Blockquote border |
|
||||
| `mdHr` | Horizontal rule |
|
||||
| `mdListBullet` | List bullets |
|
||||
|
||||
### Tool Diffs (3 colors)
|
||||
|
||||
| Token | Purpose |
|
||||
|-------|---------|
|
||||
| `toolDiffAdded` | Added lines |
|
||||
| `toolDiffRemoved` | Removed lines |
|
||||
| `toolDiffContext` | Context lines |
|
||||
|
||||
### Syntax Highlighting (9 colors)
|
||||
|
||||
| Token | Purpose |
|
||||
|-------|---------|
|
||||
| `syntaxComment` | Comments |
|
||||
| `syntaxKeyword` | Keywords |
|
||||
| `syntaxFunction` | Function names |
|
||||
| `syntaxVariable` | Variables |
|
||||
| `syntaxString` | Strings |
|
||||
| `syntaxNumber` | Numbers |
|
||||
| `syntaxType` | Types |
|
||||
| `syntaxOperator` | Operators |
|
||||
| `syntaxPunctuation` | Punctuation |
|
||||
|
||||
### Thinking Level Borders (6 colors)
|
||||
|
||||
Editor border colors indicating thinking level (visual hierarchy from subtle to prominent):
|
||||
|
||||
| Token | Purpose |
|
||||
|-------|---------|
|
||||
| `thinkingOff` | Thinking off |
|
||||
| `thinkingMinimal` | Minimal thinking |
|
||||
| `thinkingLow` | Low thinking |
|
||||
| `thinkingMedium` | Medium thinking |
|
||||
| `thinkingHigh` | High thinking |
|
||||
| `thinkingXhigh` | Extra high thinking |
|
||||
|
||||
### Bash Mode (1 color)
|
||||
|
||||
| Token | Purpose |
|
||||
|-------|---------|
|
||||
| `bashMode` | Editor border in bash mode (`!` prefix) |
|
||||
|
||||
### HTML Export (optional)
|
||||
|
||||
The `export` section controls colors for `/export` HTML output. If omitted, colors are derived from `userMessageBg`.
|
||||
|
||||
```json
|
||||
{
|
||||
"export": {
|
||||
"pageBg": "#18181e",
|
||||
"cardBg": "#1e1e24",
|
||||
"infoBg": "#3c3728"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Color Values
|
||||
|
||||
Four formats are supported:
|
||||
|
||||
| Format | Example | Description |
|
||||
|--------|---------|-------------|
|
||||
| Hex | `"#ff0000"` | 6-digit hex RGB |
|
||||
| 256-color | `39` | xterm 256-color palette index (0-255) |
|
||||
| Variable | `"primary"` | Reference to a `vars` entry |
|
||||
| Default | `""` | Terminal's default color |
|
||||
|
||||
### 256-Color Palette
|
||||
|
||||
- `0-15`: Basic ANSI colors (terminal-dependent)
|
||||
- `16-231`: 6×6×6 RGB cube (`16 + 36×R + 6×G + B` where R,G,B are 0-5)
|
||||
- `232-255`: Grayscale ramp
|
||||
|
||||
### Terminal Compatibility
|
||||
|
||||
Pi uses 24-bit RGB colors. Most modern terminals support this (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). For older terminals with only 256-color support, pi falls back to the nearest approximation.
|
||||
|
||||
Check truecolor support:
|
||||
|
||||
```bash
|
||||
echo $COLORTERM # Should output "truecolor" or "24bit"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
**Dark terminals:** Use bright, saturated colors with higher contrast.
|
||||
|
||||
**Light terminals:** Use darker, muted colors with lower contrast.
|
||||
|
||||
**Color harmony:** Start with a base palette (Nord, Gruvbox, Tokyo Night), define it in `vars`, and reference consistently.
|
||||
|
||||
**Testing:** Check your theme with different message types, tool states, markdown content, and long wrapped text.
|
||||
|
||||
**VS Code:** Set `terminal.integrated.minimumContrastRatio` to `1` for accurate colors.
|
||||
|
||||
## Examples
|
||||
|
||||
See the built-in themes:
|
||||
- [dark.json](../src/modes/interactive/theme/dark.json)
|
||||
- [light.json](../src/modes/interactive/theme/light.json)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue