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

159 lines
9.9 KiB
Markdown

# 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:
```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.
- 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) |