Lutra/docs/themes.md
danny 086bc8a925 T1: four more themes, theme picker, theme file import, editor font settings
Plum Night, River, Paper and Reed (designed by Amy, approved by Daniel)
join the brand pair. theme.list/current/select/import, a picker with
live preview (view.selectTheme) and "Import Theme…" (view.importTheme);
imported themes are validated and stored in <data_dir>/themes. Editor
font family and line height settings apply live. Docs: docs/themes.md.

Gate: fmt, clippy and the rest pass up to cargo test, where only the
unrelated lutra-terminal PTY test a_full_buffer_stops_the_shell timed
out under load; to be re-run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 19:31:34 +01:00

9.6 KiB

Themes

Status: six built-in themes, theme files with import, editor font settings (C9 T1) · Last updated: 2026-11-02

Every colour and font in Lutra comes from theme tokens: CSS custom properties --lt-<name> that crates/engine/src/theme.rs defines and the UI reads with var(--lt-…). Nothing in the UI hard-codes a colour.

Built-in themes

Id Name Kind Character
lutra-dark Lutra Dark dark The brand theme (H5): near-neutral, faintly plum surfaces, raspberry accent.
lutra-light Lutra Light light The brand theme (H5): cream-tinted surfaces, raspberry accent.
lutra-plum-night Plum Night dark Deep, warm plum surfaces with a soft cream-gold accent.
lutra-river River dark Cool slate and river teal; raspberry keywords keep the family link.
lutra-paper Paper light Almost white paper with the banner plum as the accent; the quietest theme.
lutra-reed Reed light Soft sand and sage surfaces with a muted pine accent.

Amy designed the four C9 themes from the README banner and the brand tokens; Daniel approved them on 2026-11-02. All colours are Lutra's own (no copied editor or IDE scheme). Every text colour reaches WCAG AA (4.5:1) on the backgrounds it is drawn on, and every icon and cursor colour reaches 3:1. ui/tests/theme/contrast.test.ts checks this for every built-in theme on each run of the gate.

Choosing a theme

  • Settings ▸ Appearance ▸ Theme lists every built-in and imported theme and "Same as system".
  • View ▸ Select Theme… (view.selectTheme, also in the command palette) opens a picker. Up/Down previews a theme live, Enter keeps it, Escape goes back to the one you had.
  • Same as system follows the light or dark preference of the operating system, using Lutra Dark and Lutra Light.
  • Agents and scripts: theme.list, theme.current, theme.select { id } (an id from theme.list, or system), or settings.set with appearance.theme. Every switch is live: the engine sends themeChanged with all tokens.

Editor font

The Editor section of the settings has three font settings. They apply live and stay when you switch themes.

Setting Default Meaning
editor.fontFamily empty A CSS font list such as "JetBrains Mono", monospace. Empty uses Lutra's monospace stack (ui-monospace, "Cascadia Code", Menlo, Consolas, monospace), which also stays behind your choice as a fallback. The font must be installed. The characters ; { } < > \ are refused. Applies to the editor and other code text at once, and to terminals opened afterwards (it drives --lt-font-mono).
editor.fontSize 14 Size in pixels, 8 to 48.
editor.lineHeight 150 Line height in percent of the font size, 100 to 300.

Theme files

A theme file is a UTF-8 JSON file of at most 256 KiB:

{
  "lutraTheme": 1,
  "id": "my-river",
  "name": "My River",
  "dark": true,
  "description": "River with a warmer accent",
  "author": "you",
  "tokens": {
    "bg": "#1a2125",
    "editor-bg": "#151b1e",
    "fg": "#e2e8e6",
    "fg-muted": "#8e9ca3",
    "border": "#2c373d",
    "accent": "#e8a87c",
    "error": "#f08a7a",
    "statusbar-bg": "#1e272b",
    "statusbar-fg": "#adbbc0",
    "editor-selection-bg": "#28434a",
    "editor-active-line-bg": "#1b2327",
    "editor-cursor": "#6fc6b8",
    "editor-gutter-bg": "#151b1e",
    "editor-gutter-fg": "#8e9ca3",
    "editor-match-bg": "#24393b",
    "tab-active-bg": "#151b1e",
    "tab-modified": "#6fc6b8",
    "notice-bg": "#223a3c",
    "syntax-keyword": "#e392b6",
    "syntax-string": "#9fcb94",
    "syntax-number": "#e8ae86",
    "syntax-comment": "#87959c",
    "syntax-variable": "#d2dcd9",
    "syntax-function": "#e4cb7c",
    "syntax-type": "#74c3d1",
    "syntax-constant": "#b4aaea",
    "syntax-tag": "#e6957c",
    "syntax-attribute": "#c9bd86",
    "syntax-operator": "#adbbc0",
    "diag-error": "#f08a7a",
    "diag-warning": "#e2b65c",
    "diag-info": "#8fb6ec",
    "diag-hint": "#8e9ca3",
    "vcs-added": "#93c98a",
    "vcs-modified": "#8fb6ec",
    "vcs-deleted": "#d69a92",
    "vcs-untracked": "#e3aa6a",
    "vcs-ignored": "#86939a",
    "vcs-conflicted": "#f27a90",
    "terminal-bg": "#151b1e",
    "terminal-fg": "#e2e8e6",
    "terminal-cursor": "#6fc6b8",
    "terminal-selection-bg": "#28434a",
    "terminal-ansi-black": "#263035",
    "terminal-ansi-red": "#ee8172",
    "terminal-ansi-green": "#9fcb94",
    "terminal-ansi-yellow": "#e4cb7c",
    "terminal-ansi-blue": "#8cb0e8",
    "terminal-ansi-magenta": "#e392b6",
    "terminal-ansi-cyan": "#74c3d1",
    "terminal-ansi-white": "#c6d0cd",
    "terminal-ansi-bright-black": "#8e9ca3",
    "terminal-ansi-bright-red": "#f6a597",
    "terminal-ansi-bright-green": "#bfdeb2",
    "terminal-ansi-bright-yellow": "#f0dc9c",
    "terminal-ansi-bright-blue": "#afc6f2",
    "terminal-ansi-bright-magenta": "#f0b0cd",
    "terminal-ansi-bright-cyan": "#a6dbe3",
    "terminal-ansi-bright-white": "#f3f6f5"
  }
}
Key Required Meaning
lutraTheme yes The format version, 1.
id yes 1 to 64 lowercase letters, digits and dashes, starting with a letter. It must not be a built-in id or system. Importing a file with the same id again replaces that theme.
name yes Display name, 1 to 64 characters, no control characters.
dark yes true for a dark theme. It sets the window's color-scheme, so scroll bars and form controls match.
tokens yes Every colour token below, as "#rrggbb". Names may be written with or without the --lt- prefix.
description, author no Free text; Lutra ignores it.

Lutra refuses any other key, an unknown or repeated token, a missing token and a colour that is not #rrggbb. The error names the problem (for example "59 tokens are missing: bg, editor-bg, … and 51 more"). Fonts and sizes are not part of a theme; they are the settings above.

Importing

View ▸ Import Theme… (view.importTheme) asks for a file, checks it and switches to the theme. A broken file shows an error with the reason and changes nothing. Lutra stores a checked, normalised copy in its data directory under themes/<id>.json and loads it at every start. If a stored file is broken later, Lutra skips it with a warning and starts normally. To remove an imported theme, delete its file there and restart Lutra.

Agents and scripts: theme.import { path, select?: true }. It returns { id, name, dark, replaced } and fails with the reason.

Lutra does not check the contrast of an imported theme. To check it the way the built-in themes are checked, keep text at 4.5:1 or more against the backgrounds listed below.

Colour tokens

Tokens Used for
bg, fg, fg-muted, border Window surface, text, secondary text and lines (tool windows, dialogs, popups).
accent, error Focus rings, active tab and tool-window markers, buttons; error text.
statusbar-bg, statusbar-fg Status bar.
editor-bg, editor-selection-bg, editor-active-line-bg, editor-cursor, editor-gutter-bg, editor-gutter-fg, editor-match-bg The editor. Selection and active line sit under text, so text must stay readable on them.
tab-active-bg, tab-modified, notice-bg The active tab, the unsaved-changes dot, and highlighted rows (current problem, notices).
syntax-keyword, syntax-string, syntax-number, syntax-comment, syntax-variable, syntax-function, syntax-type, syntax-constant, syntax-tag, syntax-attribute, syntax-operator Syntax highlighting; also the colours of completion kind icons and the Structure window. Text on editor-bg and editor-active-line-bg.
diag-error, diag-warning, diag-info, diag-hint Underlines, gutter markers and Problems icons; text on editor-bg, editor-active-line-bg and bg.
vcs-added, vcs-modified, vcs-deleted, vcs-untracked, vcs-ignored, vcs-conflicted Git status colours of file names in the tree and tabs and of the change markers; text on bg, editor-bg, editor-active-line-bg and tab-active-bg.
terminal-bg, terminal-fg, terminal-cursor, terminal-selection-bg The terminal.
terminal-ansi-black … terminal-ansi-white, terminal-ansi-bright-black … terminal-ansi-bright-white (16) ANSI colours in the order black, red, green, yellow, blue, magenta, cyan, white. They are text on terminal-bg, except the one meant to vanish into it (black in a dark theme, white and bright white in a light one).

For contributors

  • A built-in theme is a Theme constant in crates/engine/src/theme.rs, listed in BUILTIN, with its name in ui/src/i18n/en.json (theme.<camelId> and settings.appearance.theme.value.<camelId>).
  • Every built-in theme defines exactly the tokens of DARK (a Rust test checks it). After changing a token, run the engine tests with LUTRA_UPDATE_SNAPSHOTS=1 to rewrite ui/tests/theme/themes.json. The Vitest contrast test reads that file.
  • A new token needs a value in every theme, a row above, and a contrast pair in contrast.test.ts if text or marks are drawn with it.
  • Bundling JetBrains Mono as the default (waiting for the owner to approve OFL-1.1 in xtask/src/licences.rs and deny.toml) takes three steps: add @fontsource/jetbrains-mono to ui/package.json and import it in ui/src/main.ts; put "JetBrains Mono" first in font-mono (COMMON in theme.rs) and in MONO_FALLBACK (ui/src/stores/settings.ts); then update the default described above.

Revision history

Date Change Summary
2026-11-02 major First version: four new built-in themes, theme file format and import, editor font settings (C9 T1)