# 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-` 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: ```json { "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/.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.` and `settings.appearance.theme.value.`). - 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) |