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>
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 fromtheme.list, orsystem), orsettings.setwithappearance.theme. Every switch is live: the engine sendsthemeChangedwith 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
Themeconstant incrates/engine/src/theme.rs, listed inBUILTIN, with its name inui/src/i18n/en.json(theme.<camelId>andsettings.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 withLUTRA_UPDATE_SNAPSHOTS=1to rewriteui/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.tsif 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 inui/src/main.ts, and leadsfont-mono(COMMONintheme.rs) andMONO_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_EXCEPTIONSinxtask/src/licences.rs, comment indeny.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) |