@turri-dev/cli 0.1.4-next.318a98a → 0.1.4-next.5a8c6e5

package/docs/theming.md

@@ -1,7 +1,6 @@
 # Theming
 
-Two brand themes ship in `.pi/themes/`, built from the brand tokens. `turri` starts in
-`turri-dark`, the dark one; `--use-theme` picks another for that run:
+Two brand themes ship in `.pi/themes/`, built from the brand tokens. `turri` starts in `turri-dark`, the dark one; `--use-theme` picks another for that run:
 
 ```bash
 turri                                       # turri-dark
@@ -9,68 +8,68 @@ turri --use-theme turri-light/turri-dark    # follows terminal appearance
 turri --use-theme dark                      # pi's own
 ```
 
-The second form follows your terminal's light/dark appearance. The default is for
-`turri` only: pi's settings are left alone, so a plain `pi` keeps its theme. With the
-themes copied to `~/.pi/agent/themes/` (`cp .pi/themes/*.json ~/.pi/agent/themes/`), `{"theme": "turri-dark"}` in
-`~/.pi/agent/settings.json` gives a plain `pi` the same one.
+The second form follows your terminal's light/dark appearance. The default is for `turri` only: pi's settings are left alone, so a plain `pi` keeps its theme. With the themes copied to `~/.pi/agent/themes/` (`cp .pi/themes/*.json ~/.pi/agent/themes/`), `{"theme": "turri-dark"}` in `~/.pi/agent/settings.json` gives a plain `pi` the same one.
 
-Bad input fails quietly - an unknown `--use-theme` name and a malformed theme file both run without
-complaint - so if the colours do not change, suspect a typo rather than the mechanism.
+Bad input fails quietly - an unknown `--use-theme` name and a malformed theme file both run without complaint - so if the colours do not change, suspect a typo rather than the mechanism.
+
+## The palette
+
+Both themes, the command line's colours, the spec diff's, the banner's jellyfish and the docs' diagram are drawn from turri's design system and nothing else: dark, quiet surfaces, one pink thing to press, neon for anything you can follow. These are all the colours turri has - none is mixed, tinted or added.
+
+| name | value | in `turri-dark` |
+|---|---|---|
+| abyss | `#0a0f1a` | the page - the HTML export's background, and the surface the contrast below is measured on |
+| tile | `#0d1420` | the HTML export's cards |
+| hēi sè | `#142030` | boxes, the HTML export's callouts |
+| blue whale | `#1e3442` | a highlighted line: `selectedBg`; an added line's fill in a spec diff |
+| lines | `#22344a` | rules, dividers, frames: `borderMuted`, `mdHr` |
+| path | `#3e5a6b` | the editor's border, what is dim: `dim`, line numbers |
+| grauzone | `#85a3b2` | body text, and what can be skimmed: `text`, `muted` |
+| white | `#f4f7f9` | headings, tool titles, what you typed, the jellyfish's shine |
+| siesta tan | `#e9d8c8` | inline code, \*\*\*plain's text in quotes or backticks |
+| eggplant | `#732553` | a removed line's fill in a spec diff |
+| neon | `#5ce1e6` | links, focus, the selection, section labels, \*\*\*plain's concepts in a spec diff: `accent`, `mdLink`, regen's `◆` |
+| neon hover | `#8eebee` | types in code, an added line's fill in a light theme's spec diff |
+| pink | `#ff5c8d` | the wordmark, the jellyfish's bell, and what is done - its `✓`, the spec map's `◇` and `◆`: `success` |
+| pink hover | `#ff7fa6` | \*\*\*plain's section headers, a removed line's `-`, keywords in code |
+| orange | `#ff7a3d` | the jellyfish's gut, the `$` of bash mode, and everything that asks for you - what failed (`✗`), what works with limits, what needs you (the spec map's `!`): `error`, `warning` |
+
+The design system keeps pink for the one thing to press and orange for the `$` prompt alone. A terminal has no buttons, but it needs status colours, so pink carries what is done and orange everything that asks for you - what failed, what works with limits, what waits on you - the mark (`✗`, `!`, `■`) telling them apart. The palette has no red.
 
 ## Why there are two
 
-Half the palette is unusable on the other background. Contrast against brand black and brand
-white:
+Half the palette is unusable on the other background. Contrast against abyss and white:
 
-| token | on `#0f0f0f` | on `#ffffff` |
+| colour | on `#0a0f1a` | on `#ffffff` |
 |---|---|---|
-| brand-yellow | 17.07 | 1.12 |
-| brand-green | 14.77 | 1.30 |
-| brand-green-light | 13.34 | 1.44 |
-| brand-blue | **1.97** | 9.72 |
-| brand-green-dark | 1.56 | 12.31 |
-| brand-red | 3.38 | 5.67 |
-
-So `turri-dark` carries yellow, green and green-light, and `turri-light` carries blue and
-green-dark. **Brand blue never appears as text in the dark theme** - at 1.97:1 on brand black it is
-illegible - so the dark theme's accent is brand yellow, and blue appears only in the light theme
-and in both themes' HTML-export backgrounds. The one place blue stands for something in both is the spec
-map's `◆` - a functional spec its conformance tests pass for: brand blue in a light theme, and in a dark
-one its tint 55% of the way to white, `#919aec`, 7.34:1 on brand black (`brandBlue` in
-`src/regenerate/plain-palette.ts`).
-
-`--color-brand-status-warning` on white is 3.49:1, under the 4.5:1 bar for body text, so it is used
-only for accents in the light theme, never for prose.
+| white | 17.81 | 1.08 |
+| neon | 12.20 | 1.57 |
+| grauzone | 7.19 | 2.67 |
+| pink | 6.54 | 2.93 |
+| orange | 7.39 | 2.59 |
+| path | **2.63** | 7.29 |
+| blue whale | 1.48 | 12.92 |
+| eggplant | 1.93 | 9.91 |
+
+So `turri-light` is drawn from the design system's deep colours: abyss for text, eggplant for the accent, headings, what is done and the wordmark, blue whale for links and regen's `◆`, path for what is muted. Its pale colours become backgrounds - siesta tan for a selection, neon for a search hit, white for your messages. Orange stays the error and the warning at 2.59:1 - the palette has nothing warm that reads on white. The wordmark and regen's `◆` are painted outside the theme's slots (`brandPink` and `brandNeon` in `src/regenerate/plain-palette.ts`). **Path is never text that matters in the dark theme** - at 2.63:1 it is for rules and what is meant to recede.
 
 ## Backgrounds
 
-The dark theme paints no panels: the backgrounds of your messages, turri's messages and the
-tool rows are `""`, the terminal's own background, so the transcript reads as one surface whatever
-the terminal's colour is - brand black or not, no block shows up as a box. Two are deliberately
-painted, because they have to be visible to work:
+The dark theme paints no panels: the backgrounds of your messages, turri's messages and the tool rows are `""`, the terminal's own background, so the transcript reads as one surface whatever the terminal's colour is - abyss or not, no block shows up as a box. Two are deliberately painted, because they have to be visible to work:
 
 | token | value | why |
 |---|---|---|
-| `selectedBg` | `#223936` | a selection you cannot see is not a selection |
-| `searchMatchBg` | `#e0ff6e` | search hits, with black text on top |
+| `selectedBg` | `#1e3442` | a selection you cannot see is not a selection |
+| `searchMatchBg` | `#5ce1e6` | search hits, with abyss text on top |
 
 With tool rows carrying no background, their state is signalled by the title and the diff colours.
 
-**The window's background is your terminal's setting**, and the transcript is drawn on it. For the
-brand look, set it to brand black, `#0f0f0f`, in your terminal profile.
+**The window's background is your terminal's setting**, and the transcript is drawn on it. For the brand look, set it to abyss, `#0a0f1a`, in your terminal profile.
 
 ## Spec diffs
 
-A spec diff in the panels is not painted with the theme's colours for code: those are made for code,
-and the turri themes' backgrounds are all the surface colour, so a diff drawn with them would have no
-fills and hardly any highlighting. It has a palette of its own (`src/regenerate/plain-palette.ts`), one for
-a dark theme and one for a light, picked by the theme's appearance: a hue for each piece of \*\*\*plain -
-a section's header, a concept, a link, text in quotes or backticks, a front matter key, a module,
-a comment - at least 7:1 on the surface, and a fill behind each added and removed line, green and red,
-that every colour still reads on.
+A spec diff in the panels is not painted with the theme's colours for code: those are made for code, and the turri themes' backgrounds are all the surface colour, so a diff drawn with them would have no fills and hardly any highlighting. It has a palette of its own (`src/regenerate/plain-palette.ts`), one for a dark theme and one for a light, picked by the theme's appearance: a hue for each piece of \*\*\*plain - a section's header, a concept, a link, text in quotes or backticks, a front matter key, a module, a comment - at least 7:1 on the surface, and a fill behind each added and removed line: on a dark theme blue whale and eggplant, on a light one neon hover and siesta tan. Every colour reads at least 4.8:1 on blue whale and 5:1 on the light fills; eggplant, the design system's only warm dark fill, takes the pinks and grauzone down to 3.7:1.
 
 ## The font
 
-`--font-brand` cannot be applied. pi draws into a terminal, so the typeface is your terminal
-emulator's setting, and NeueMontreal is proportional - a terminal needs a monospaced face. Set it
-in iTerm2 / Ghostty / Alacritty, not here.
+The design system's fonts cannot be applied. pi draws into a terminal, so the typeface is your terminal emulator's setting. Its monospaced face is Geist Mono - set it in iTerm2 / Ghostty / Alacritty for the brand look; Neue Montreal, for headings, is proportional, and a terminal needs a monospaced face.