Lutra/docs/themes.md
danny f2a1ef12cd T1: bundle IBM Plex Mono as the code font, italic comments (D28)
Daniel chose IBM Plex Mono from Amy's comparison of four free fonts. It
ships from @fontsource (Latin and Latin Extended, 400/700 with italics)
and leads font-mono for the editor and the terminal; the UI keeps the
system font. OFL-1.1 is allowed for this one package only
(PACKAGE_EXCEPTIONS in xtask/src/licences.rs, comment in deny.toml).
NOTICE, ASSETS.md and docs/themes.md updated.

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

9.9 KiB

Themes

Status: six built-in themes, theme files with import, editor font settings, bundled code font IBM Plex Mono (C9 T1) · Last updated: 2026-11-06

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 "Fira Code", monospace. Empty uses Lutra's own code font, IBM Plex Mono, which ships with Lutra (regular, bold and italic; comments are set in its italic). The default stack ("IBM Plex Mono", ui-monospace, "Cascadia Code", Menlo, Consolas, monospace) also stays behind your choice as a fallback. Any other 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.
  • The code font IBM Plex Mono comes from @fontsource/ibm-plex-mono (Latin and Latin Extended, 400 and 700 with italics, about 118 KB), imported in ui/src/main.ts, and leads font-mono (COMMON in theme.rs) and MONO_FALLBACK (ui/src/stores/settings.ts). Daniel chose it from four candidates Amy compared (D28); OFL-1.1 is allowed for this package only (PACKAGE_EXCEPTIONS in xtask/src/licences.rs, comment in deny.toml). The UI font stays the system font.

Revision history

Date Change Summary
2026-11-06 minor IBM Plex Mono bundled as the code font, italic comments (D28)
2026-11-02 major First version: four new built-in themes, theme file format and import, editor font settings (C9 T1)