Themes and identity

Veyyon’s interface is built around near-black, near-white, silver structure (#C6CBD4), and a single ember accent (#F0862E) — the same tokens the website ships.

Bundled themes

File	Name	Notes
`defaults/titanium.json`	Titanium	Default dark theme. Pitch black `#000000`, silver `#C6CBD4`, ember accent `#F0862E`; mirrors the website tokens (`website/site.css`)
`dark.json`	Veyyon Dark	Bundled alternative. Pitch black `#000000` / `#FAFAFA` / silver `#B8BDC7`; predates the ember accent
`light.json`	Light	Default light theme. White `#FFFFFF` ground with dark-silver structure `#5C6470`, ember accent

A larger bundled catalog ships under modes/theme/defaults/ and is selectable from the theme picker.

Changing theme

Settings UI: /settings → Appearance → theme (or the theme picker on first run).
Config: theme in ~/.veyyon/profiles/default/agent/config.yml (profile-specific when using --profile).
Custom themes: drop JSON under ~/.veyyon/profiles/default/agent/themes/; schema in docs/handbook/src/reference/theme.md.

Terminal capability detection maps the same hierarchy for truecolor, ANSI-256, ANSI-16, unknown background, and no-color modes. Reduced-motion settings remove decorative animation without hiding state changes.

Backgrounds

Veyyon paints no backgrounds by default. The transcript (user messages, tool output, extension messages), the composer, and the status line all inherit your terminal’s own background, so the UI looks native on any terminal color. Two opt-ins bring painted surfaces back:

Turn off statusLine.transparent (/settings → Appearance → Status Line) to paint the theme’s statusLineBg bar, including powerline end caps.
A custom theme can declare a composerBg color to paint the composer card; when omitted, the composer stays unpainted.

Painted ground

tui.paintGround (/settings → Appearance → Display) controls whether Veyyon sets the terminal’s own background color (OSC 11) to the theme’s ground while it runs, so the UI fills the window edge-to-edge instead of floating on the terminal’s configured background. The original background is restored on exit, including crash exits.

The ground is the theme’s page background, the same export.pageBg color the HTML export uses (see docs/handbook/src/reference/theme.md). Every built-in theme declares one.

Value	Behavior
`auto` (default)	Paint only when the terminal’s reported background is already close to the theme ground, so no visible seam appears while painting. If the terminal doesn’t report its background, inherit it.
`always`	Always paint the theme ground.
`never`	Never touch the terminal background.

On auto, the decision is taken before the launch card paints, from the background this terminal reported on the previous launch (cache/launch-facts.json). The first launch in a terminal has no record and inherits; the report that follows paints the ground if it is close enough. A report that contradicts the record takes effect on the next frame.

A custom theme that declares no page background has no ground to paint, so Veyyon inherits the terminal’s own background regardless of this setting. With always, it also logs once that the active theme declares no ground, since that is the one case you asked to paint and it could not. Add an export.pageBg to the theme to give it a ground.

Terminals that don’t support OSC 11 ignore the sequence; nothing breaks.

What the theme covers

The contract applies to onboarding, composer, menus, dialogs, status line, markdown, tables, diffs, tool output, approvals, progress, and errors, not only the chat pane.

Identity elsewhere

CLI binary: veyyon
Config root: ~/.veyyon (VEYYON_CONFIG_DIR; XDG paths after veyyon config init-xdg)
npm packages: @veyyon/*

Keyboard shortcuts