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>
This commit is contained in:
danny 2026-11-02 19:47:58 +01:00
parent 872b5cb258
commit 086bc8a925
26 changed files with 2881 additions and 100 deletions

158
docs/themes.md Normal file
View file

@ -0,0 +1,158 @@
# 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:
```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/<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) |