---
name: hermes-dashboard-theming
description: "Customize the Hermes web dashboard appearance: YAML themes, typography, terminal background, component chrome, and custom CSS."
version: 1.0.0
author: Agent
---

# Hermes Dashboard Theming

Customize the `hermes dashboard` web UI via drop-in YAML theme files. This system is **separate** from the CLI TUI `/skin` command — dashboard themes repaint the browser UI (backgrounds, cards, fonts, terminal pane), while TUI skins control text colors inside the terminal.

## Quick Reference

| Concept | Path / Command |
|---------|---------------|
| Theme directory | `~/.hermes/dashboard-themes/` |
| File format | `<name>.yaml`, all fields optional |
| Activate | Palette icon (🎨) in dashboard header, or `dashboard.theme` in config.yaml |
| Font override (no YAML) | Font section below theme list in the picker — persists in config.yaml |
| Built-in themes | 7 (Hermes Teal, Hermes Teal Large, Midnight, Ember, Mono, Cyberpunk, Rosé) |
| TUI skin (chat content) | `/skin` command in the chat terminal — separate system |

## Theme YAML Structure

Every field is optional — missing keys fall back to the built-in `default` theme.

```yaml
name: my-theme
label: My Theme
description: What this theme does

# 3-layer palette — all shadcn tokens derived via CSS color-mix()
palette:
  background: { hex: "#0a1628", alpha: 1.0 }  # Deepest canvas (near-black)
  midground: "#40c8ff"          # Primary text + accent (bare hex, alpha=1)
  foreground: { hex: "#ffffff", alpha: 0 }  # Top highlight (default invisible)
  warmGlow: "rgba(255, 199, 55, 0.24)"  # Vignette color
  noiseOpacity: 0.7             # Grain overlay (0 = off)

typography:
  fontSans: '"Inter", system-ui, sans-serif'          # Body font stack
  fontMono: '"JetBrains Mono", ui-monospace, monospace' # Code font stack
  fontDisplay: '"Inter", sans-serif'                   # Heading stack (falls back to fontSans)
  fontUrl: "https://fonts.googleapis.com/css2?family=Inter:..."  # External stylesheet URL
  baseSize: "16px"               # Root font size — KEY for readability tweaks
  lineHeight: "1.5"              # Default line height
  letterSpacing: "0"             # Default letter spacing

layout:
  radius: "0.5rem"               # Corner rounding (cascades to sm/md/lg/xl)
  density: comfortable           # compact (0.85x) | comfortable (1x) | spacious (1.2x)

layoutVariant: standard          # standard (1600px max) | cockpit (sidebar rail) | tiled (full width)

# Background image / logo — URLs become CSS vars
assets:
  bg: "url(https://...)"
  logoSvg: "url(https://...)"
  faviconSvg: "url(https://...)"

# Per-component chrome — accepted keys: card, header, footer, sidebar, tab, progress, badge, backdrop, page
componentStyles:
  card:
    background: "linear-gradient(...)"
    boxShadow: "0 1px 2px rgba(0,0,0,0.06)"

# Override specific shadcn color tokens (when palette derivation isn't enough)
colorOverrides:
  primary: "#ffce3a"
  border: "rgba(64, 200, 255, 0.28)"

# Terminal background for the chat xterm.js pane
terminalBackground: "#000000"

# Raw CSS injected as <style data-hermes-theme-css> — capped at 32 KiB
customCSS: |
  .hermes-chat-xterm-host { ... }
```

## Readability Best Practices

For users who find the default text too small:

1. **Bump `baseSize`** — the single most impactful field. Try `"18px"` or `"20px"`.
2. **Set `density: spacious`** — adds 20% padding/margin multiplier.
3. **Use Atkinson Hyperlegible font** — designed by the Braille Institute for maximum legibility:
   ```yaml
   typography:
     fontSans: '"Atkinson Hyperlegible", system-ui, sans-serif'
     fontUrl: "https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&display=swap"
     baseSize: "18px"
     lineHeight: "1.65"
   layout:
     density: spacious
   ```
4. **For the chat terminal itself** — use `/skin daylight` or `/skin slate` for a light/blue terminal background inside the TUI (that's a separate system; see references/tui-skins-separation.md).

## Theme Discovery & Activation

1. Place `.yaml` file in `~/.hermes/dashboard-themes/`
2. Hard-refresh the dashboard (`Shift+Cmd+R` / `Ctrl+Shift+R`)
3. Click 🎨 palette icon in the dashboard header
4. Select the theme

To set as permanent default via config:
```bash
hermes config set dashboard.theme my-theme
```

## Chat Tab — What's Customizable vs Fixed

The dashboard Chat tab is an **embedded xterm.js terminal** running the Hermes TUI, NOT a custom message-bubble UI.

| Aspect | Control | Method |
|--------|---------|--------|
| Terminal background | ✅ Theme | `terminalBackground` in YAML |
| Terminal font | ❌ Fixed | `JetBrains Mono, Fira Code, ...` monospace stack |
| Terminal font size | ❌ Auto | Calculated from viewport width (max 14px) |
| Text colors inside terminal | ✅ TUI skin | `/skin` command or `~/.hermes/skins/*.yaml` |
| Wrapper chrome | ✅ `customCSS` | `.hermes-chat-xterm-host` class |
| Sidebar panel | ✅ Theme | Via `componentStyles.sidebar` |

## Community Theme Sources

- **Yak's Hermes Dashboard Themes** (28★) — 8 themes, readability-focused, uses Atkinson Hyperlegible: `github.com/yakuzadevopps/Hermes-Dashboard-Themes`
- **minutechreview** (4★) — 20 themes, aesthetic/country-themed: `github.com/minutechreview/hermes-dashboard-themes`
- **Clean WebUI** (13★) — White background, dark text, Normal-case: `github.com/fplanque/hermes-agent-dashboard-theme-clean`