Themes

The yottacode TUI ships with thirteen built-in color palettes. Switch between them with /theme — an interactive picker with a live preview pane — or pin one in ~/.yottacode/config.toml so every new session boots into it.

The picker

/theme opens a two-pane overlay. Theme names live on the left; the right pane shows a live showcase rendered in the highlighted palette — inline tokens, a chroma-highlighted code block, a diff fragment, and status / state markers.

The cursor opens on the currently-active theme. The green ❯ arrow stays green across every palette so the “you are here” cue doesn’t shift color when you preview a theme.

Scriptable shortcuts

For muscle memory or non-interactive callers (e.g. one-shot mode), two forms bypass the picker:

/theme set <name>      # explicit
/theme <name>          # positional shortcut, same effect

Both apply, persist, and report [theme] switched to "<name>" (persisted).

Built-in palettes

Order matches what the picker displays: yottacode-dark leads as the polished house dark theme and default pick, terminal sits second as the universal-safe terminal-adaptive fallback, then the rest are alphabetical.

A theme marked real bg repaints your terminal emulator’s actual background color (not just in-app chrome) the moment you preview or apply it — see Real terminal background below.

Real terminal background

Themes marked real bg above repaint your terminal emulator’s actual background color via the OSC 11 control sequence — not just yottacode’s own chrome surfaces, the whole terminal canvas, exactly as if you’d changed your terminal profile’s background color yourself. This only became possible once the TUI moved to full-screen (alt-screen) rendering — see “Why there’s no true light theme” below for the constraint it lifted.

What to expect:

• Default first-run look. Fresh installs boot into yottacode-dark, including its real charcoal background. Pin terminal if you want yottacode to inherit your terminal palette/background instead.
• Live preview, live revert. Browsing the picker repaints your real terminal background on every cursor move, same as every other role; Esc puts it back exactly as it was.
• Restored on exit, always. yottacode captures your terminal’s original background at startup and writes it back before handing the terminal back to your shell — on a normal quit, on Ctrl+C, and on a crash (anywhere the process gets a chance to run its shutdown path; kill -9 is the one exception nothing can defer through, same as any other cleanup in the app).
• Silently skipped on unsupported terminals. yottacode queries your terminal for OSC 11 support once at startup. If nothing answers — some SSH hops without escape-sequence passthrough, tmux without set -g allow-passthrough on, a handful of older or headless terminals — the whole feature is a no-op for that session: themes still switch every other color, they just don’t touch the real background. Nothing is retried or reported as an error.
• Themes without “real bg” (terminal, high-contrast, low-contrast, no-color) intentionally leave your terminal’s background exactly as you have it configured — that’s the contract those themes are built around, not an oversight.

Why there’s no true “light” theme

Foreground colors alone can’t fake a light theme on a dark terminal — AdaptiveColor picks between a light-mode and dark-mode variant, but every role still has to render something, and text tuned for a dark backdrop reads poorly no matter which variant you pick if the canvas underneath stays dark. Real terminal-background theming (above) closes part of this gap for the themes that opt in, but none of the thirteen palettes here currently ship a light-mode background — the closest is low-contrast, which stays close to body text without replacing your terminal’s own background.

If you want the full light experience, run yottacode in a terminal whose background is light, or pin a themed background to a light hex color if you maintain your own theme (see “Adding a theme” below).

Persistence

The picker’s Enter (or /theme set <name>) writes:

[theme]
name = "dimmed"

to ~/.yottacode/config.toml. The default theme (yottacode-dark) is not persisted — omitting the section keeps the file minimal for users who never touched the command.

A typo in the persisted name is rejected at load time:

config: ~/.yottacode/config.toml: theme.name = "termnal" is not a registered theme (try one of terminal, yottacode-dark, catppuccin, dimmed, gruvbox, high-contrast, low-contrast, no-color, nord, one-dark, solarized-dark, studio-dark, tokyo-night)

Adding a theme (for contributors)

Drop an internal/tui/themes/<name>.go file with a single init() that calls register(Palette{ Name: …, Description: …, Highlight: …, Accent: …, …}). The TUI’s styles.go builds every UI style from those role colors; nothing else needs editing for the new theme to surface in the picker. Tests in themes_test.go assert the registered set — append the new name to expectedThemes in the right slot (the curated head pins yottacode-dark first and terminal second; the tail is alphabetical) so the registry-coverage test stays accurate.

Lock the theme contract:

• Every role must be filled. styles.go reads all ten role fields; an unset lipgloss.AdaptiveColor{} renders as default-foreground (effectively invisible against the terminal background) and looks like a bug.
• HasBackground = true is opt-in, and does two things. In-app chrome surfaces (palette overlay, approval modal, watermark box) get painted with your Background color — code blocks are intentionally exempted to preserve chroma syntax highlighting. And, when the terminal supports it (see Real terminal background), the theme repaints the user’s actual terminal background to the same color via OSC 11 — automatic, no separate flag. Only opt in for themes with a real, canonical background swatch (a named color scheme like Nord or Solarized); themes meant to adapt to whatever the user’s terminal already looks like should leave HasBackground zero.
• Highlight is the chroma style name. Pair it deliberately — a light UI palette with monokai reads as broken; a dark UI with github washes out fenced code.
• Pin vs. adapt. Use pin(...) when the theme’s identity is “this exact look on every terminal” (Catppuccin, Gruvbox, Solarized). Use lipgloss.AdaptiveColor{Light: …, Dark: …} when the theme should respond to terminal background detection (low-contrast).