/mulmoterminal-theme

name: mulmoterminal-theme
description: Build a colour scheme of your own for MulmoTerminal — one that joins Midnight, Nord, Daylight and Solarized in Settings' theme picker and can then be pinned per project. Writes `themes` in `~/.mulmoterminal/config.json`, the whole-app palette (panels, borders, accent, text). Settings → Theme can copy an existing theme and change its colours one by one; this skill is for a scheme described in words or drawn from an image, contrast checking, and the terminal's own `term` palette. Use when the user wants their own theme, a dark/light variant that isn't shipped, a scheme drawn from a painting, a photo or a brand's colours, or says the built-in themes are too dark, too blue, too low-contrast. For colouring ONE project's cell (its badge and header), or assigning an existing theme to a directory, use mulmoterminal-dirs instead.

Make a colour scheme of your own

`themes` in `~/.mulmoterminal/config.json` defines schemes that appear in Settings' picker next to the four built-ins, and that a project can then name in its `.mulmoterminal.json` `theme` key. Settings can choose a theme, and copy one and change its colours one at a time (Settings → Theme → Your own theme). What it cannot do is design one — from a mood, a photo or a brand, with contrast checked — or set the terminal's `term` palette. This skill is that path.

This is the **whole app's** palette — panel backgrounds, borders, accent, text. A single project's badge and header colours are a different thing (`mulmoterminal-dirs`).

How to run this

1. Find out what they're going after

Ask for the direction first, with concrete options rather than "what colours?":

• **From something that exists** — a painting, a photo, a brand, an editor theme they like.

This is the easiest to do well: take 5–8 colours off the source and assign them to roles.

• **A variant of a built-in** — "Nord but warmer", "Daylight with more contrast". Use `extends`

and write only the keys that differ.

• **Light or dark**, if it isn't already obvious. It decides every value below.

2. Decide `extends` — and know what it costs

{ "id": "arles", "label": "Van Gogh (Arles)", "extends": "daylight", "colors": { "--accent": "#c8971e" } }

• **With `extends`**, `colors` is a diff over that built-in (`midnight` / `nord` / `daylight` /

`solarized`). Anything you leave out is inherited. Start here — it is far easier to get right, and a three-key diff is a real theme.

• **Without `extends`**, the theme must set **every** one of the 20 keys below. This is enforced

when the config is saved, not when the theme is painted: an incomplete theme with no base is **rejected outright** rather than half-applied, because the missing half would inherit whatever the previous theme left on the element.

3. Write the colours

Assign the source's colours to roles, then say what each one is doing before you write it. Rules that matter more than taste:

• **`--text` on `--bg-base` and `--bg-panel` must stay readable.** Check the WCAG contrast ratio:

gamma-decode each channel (`c/255`, then `c<=0.03928 ? c/12.92 : ((c+0.055)/1.055)^2.4`), weight `0.2126 R + 0.7152 G + 0.0722 B`, ratio `(lighter+0.05)/(darker+0.05)`. Aim for **4.5:1 or better** for `--text`, and don't let `--text-muted` fall below **3:1** — a beautiful palette that can't be read is the usual way this goes wrong.

• **`--on-accent` goes on `--accent-bg`, not on the page.** Check it against that, and nothing else.
• **A painting's colours are rarely usable raw.** Backgrounds want the muted, desaturated end of

the source; the accent wants its most saturated note. Taking six vivid colours and putting them in six roles produces something unusable at 12px.

4. Write, then look

`themes` is a **partial `POST /api/config` merge** — write only `themes`, so the user's other settings survive. Send the **whole array**, existing entries included: it replaces, it does not append, and a lone new entry silently deletes the rest.

Then: **reload the tab**, open Settings, and pick the theme. It does not appear until the page re-reads the config. If the file was hand-edited while the server was running, the server needs a restart too.

Ask what to change and adjust. The picker is the real preview — apply and look, rather than describing.

5. Offer to pin it, if that's what they meant

A theme is global. If the user wanted "this project in my new scheme", the second half is `"theme": "<id>"` in that project's `.mulmoterminal.json` — hand off to `mulmoterminal-dirs`.

Schema

{
  "themes": [
    { "id": "arles", "label": "Van Gogh (Arles)", "extends": "daylight", "colors": { "--accent": "#c8971e" } }
  ]
}

| Field | Rule | |---|---| | `id` | **Required.** Lowercase letter first, then lowercase/digits/dashes, ≤ 32 chars (`^[a-z][a-z0-9-]{0,31}$`). It becomes a `data-theme` attribute value and is what a project's `theme` key names. | | `label` | **Required.** What the picker shows, ≤ 40 chars after trimming. | | `extends` | Optional: `"midnight"` / `"nord"` / `"daylight"` / `"solarized"`. Omit only if you set all 20 colours. | | `colors` | Hex only — `#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`. **A key outside the 20 drops the whole theme**, so check spelling before writing. | | `term` | Optional. The xterm palette, set outright — see [The terminal palette](#the-terminal-palette-term) below. Same hex rule, and its own key vocabulary. |

**`id` must not be a built-in id.** `midnight`, `nord`, `daylight` and `solarized` are refused rather than merged into — someone reading the guide's description of Midnight has to get Midnight.

The hex shape is doing security work in `colors`, not tidiness: those values land in CSS custom properties, so one that escaped the shape would be injected into a style declaration. `term` goes to a canvas instead, where the risk is different and still real — xterm throws on a colour it cannot parse, and it th