# Dashboard Theme vs TUI Skin — Two-Layer Customization

The dashboard has **two independent** visual customization systems. Confusing them is the #1 pitfall.

## Layer 1: Dashboard Theme

| Property | Detail |
|----------|--------|
| Storage | `~/.hermes/dashboard-themes/<name>.yaml` |
| Controls | Browser chrome: background, cards, header, sidebar, fonts, terminal background |
| Activation | 🎨 palette icon in dashboard header |
| Configuration | `dashboard.theme` in config.yaml |

The theme system uses a 3-layer palette (`background`, `midground`, `foreground`) from which all shadcn CSS tokens are auto-derived via `color-mix()`. Custom YAML fields include `palette`, `typography`, `layout`, `layoutVariant`, `assets`, `componentStyles`, `colorOverrides`, `customCSS`, and `terminalBackground`.

## Layer 2: TUI Skin

| Property | Detail |
|----------|--------|
| Storage | `~/.hermes/skins/<name>.yaml` |
| Controls | Text/content INSIDE the chat terminal: banner colors, spinner faces, response box labels, tool prefix |
| Activation | `/skin <name>` in chat, or `display.skin` in config.yaml |
| Interaction | Skins can be created visually via `npx hermes-mod` |

The TUI skin is rendered by Ink (React for terminals) inside the xterm.js terminal in the Chat tab. `/skin daylight` gives a light terminal with dark text — often the fastest readability fix.

## Chat Tab Architecture

The dashboard Chat tab (`/chat`) is **xterm.js** running a WebGL renderer that connects via WebSocket to a FastAPI PTY endpoint (`/api/pty`). The PTY spawns `node ui-tui/dist/entry.js` which runs the Hermes TUI.

Key source: `web/src/pages/ChatPage.tsx` in the Hermes source.

### Fixed Properties (not theme-configurable)

- **Font family**: `'JetBrains Mono', 'Cascadia Mono', 'Fira Code', 'MesloLGS NF', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace`
- **Font size**: Auto-calculated from `host.clientWidth`: 7px (<300px), 8px (300-359), 9px (360-419), 10px (420-519), 11px (520-719), 12px (720-1023), 14px (≥1024)
- **Line height**: 1.02 (<1024px), 1.15 (≥1024px)

### Theme-Controlled Properties

- **Terminal background**: `theme.terminalBackground ?? "#000000"` — set via `terminalBackground` key in dashboard theme YAML
- **Wrapper chrome**: The parent `<div>` with classes `relative flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden rounded-lg p-2 sm:p-3`
- **xterm host div**: Class `hermes-chat-xterm-host` — styleable via `customCSS`

## Recommended Theme Installation

```bash
# Create theme directory
mkdir -p ~/.hermes/dashboard-themes

# Yak's readability themes (8 themes, 28 stars)
cd /tmp && git clone https://github.com/yakuzadevopps/Hermes-Dashboard-Themes.git
cp Hermes-Dashboard-Themes/themes/*.yaml ~/.hermes/dashboard-themes/
rm -rf Hermes-Dashboard-Themes

# Community hackathon pack (20 themes)
cd /tmp && git clone https://github.com/minutechreview/hermes-dashboard-themes.git
cp hermes-dashboard-themes/*.yaml ~/.hermes/dashboard-themes/
rm -rf hermes-dashboard-themes

# Clean WebUI light theme (13 stars)
curl -sL https://raw.githubusercontent.com/fplanque/hermes-agent-dashboard-theme-clean/main/clean-webui.yaml \
  -o ~/.hermes/dashboard-themes/clean-webui.yaml
```

Refresh dashboard, click 🎨, pick your theme.

## Bumping Font Size on Any Theme

```bash
sed -i 's/baseSize: "16px"/baseSize: "20px"/' ~/.hermes/dashboard-themes/terminal-focus.yaml
```

Then hard-refresh (`Shift+Cmd+R` / `Ctrl+Shift+R`).