Handoff — 2026-09-09 — three new themes, and the alias one of them needed

State

Eleven themes ship: monochrome-light, darcula and intellij-light are new. monochrome is now monochrome-dark, monochrome-light is new, and the old name still loads through retiredNames in theme/load.go. All fifteen packages pass; the quality gate passes (run #20).

Working tree uncommitted, here and in the four editors whose documentation was updated.

The one thing to know before releasing

The editors' documentation is ahead of their binaries. All four pin turbo-core v0.4.2 — v0.4.3 is published and none of them has been bumped to it yet — and both ship eight themes; their reference/themes.md, how-to/write-a-theme.md and tutorials now describe eleven. The order out of that is:

Tag and publish turbo-core — this is new public behaviour (a theme, and a name-resolution rule), so it wants a minor bump. v0.4.3 is already out, so that is v0.5.0.
Bump each editor's go.mod to it.
Re-run each editor's suite.

Until step 2, -list-themes in a released editor still shows eight and the docs say eleven.

Next steps

Commit here and in turbo-go, turbo-rust, turbo-python and turbo-moonbit.
Release as above.

Open questions / blockers

Nothing holds the documented theme list to the shipped one. The count and the names are written out in twelve Markdown files across five repositories, and the only thing that noticed they were stale this time was a person adding a theme. A test in each editor that reads theme.Available("") and checks every name appears in its own reference/themes.md would be about twenty lines, and would have caught the pre-existing staleness in theme/README.md too — that file had been missing both Catppuccin themes since they were added.
TestTheReleaseScriptTagsAndPushesForReal fails in this sandbox, on a clean tree as well as a dirty one: the git clone it makes into a temp directory produces NUL-padded files, and make check in the clone then fails with unexpected NUL in input. It is environmental, not a regression — confirmed by stashing every change and re-running. It will need re-checking somewhere else before the release.

Watch out for

The two JetBrains themes are "after", not faithful. Three values moved for readability rules — both comments and Darcula's caret row — and each is marked in its file with the measurement and the next value that would have failed. Do not "restore" them to JetBrains' originals without also removing the rules; two of the mutation tests do exactly that restoration and both fail.
syntax.comment is the binding constraint on any light theme, not the eye. On #eeeeee a comment must be #6c6c6c or darker to clear 4.5:1, and #6c6c6c only makes it by 0.03. #626262 was chosen for margin.
A theme with only fg takes its bg from default through the key hierarchy, which is why the syntax block sets no backgrounds and the contrast tests still see the page colour.
The retired-name tests read the aliases back through Load, not from the map, because the map is unexported — deliberately, so a caller cannot add one.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


# Handoff — 2026-09-09 — three new themes, and the alias one of them needed

## State

Eleven themes ship: `monochrome-light`, `darcula` and `intellij-light` are new. `monochrome` is now `monochrome-dark`, `monochrome-light` is new, and the old name still loads through `retiredNames` in `theme/load.go`. All fifteen packages pass; the quality gate passes (run #20).

Working tree uncommitted, here and in the four editors whose documentation was updated.

## The one thing to know before releasing

**The editors' documentation is ahead of their binaries.** All four pin turbo-core `v0.4.2` — `v0.4.3` is published and none of them has been bumped to it yet — and both ship eight themes; their `reference/themes.md`, `how-to/write-a-theme.md` and tutorials now describe eleven. The order out of that is:

1. Tag and publish turbo-core — this is new public behaviour (a theme, and a name-resolution rule), so it wants a **minor** bump. `v0.4.3` is already out, so that is **`v0.5.0`**.
2. Bump each editor's `go.mod` to it.
3. Re-run each editor's suite.

Until step 2, `-list-themes` in a released editor still shows eight and the docs say eleven.

## Next steps

1. Commit here and in turbo-go, turbo-rust, turbo-python and turbo-moonbit.
2. Release as above.

## Open questions / blockers

- **Nothing holds the documented theme list to the shipped one.** The count and the names are written out in twelve Markdown files across five repositories, and the only thing that noticed they were stale this time was a person adding a theme. A test in each editor that reads `theme.Available("")` and checks every name appears in its own `reference/themes.md` would be about twenty lines, and would have caught the pre-existing staleness in `theme/README.md` too — that file had been missing both Catppuccin themes since they were added.
- **`TestTheReleaseScriptTagsAndPushesForReal` fails in this sandbox**, on a clean tree as well as a dirty one: the `git clone` it makes into a temp directory produces NUL-padded files, and `make check` in the clone then fails with `unexpected NUL in input`. It is environmental, not a regression — confirmed by stashing every change and re-running. It will need re-checking somewhere else before the release.

## Watch out for

- **The two JetBrains themes are "after", not faithful.** Three values moved for readability rules — both comments and Darcula's caret row — and each is marked in its file with the measurement and the next value that would have failed. Do not "restore" them to JetBrains' originals without also removing the rules; two of the mutation tests do exactly that restoration and both fail.
- **`syntax.comment` is the binding constraint on any light theme**, not the eye. On `#eeeeee` a comment must be `#6c6c6c` or darker to clear 4.5:1, and `#6c6c6c` only makes it by 0.03. `#626262` was chosen for margin.
- **A theme with only `fg` takes its `bg` from `default`** through the key hierarchy, which is why the syntax block sets no backgrounds and the contrast tests still see the page colour.
- **The retired-name tests read the aliases back through `Load`, not from the map**, because the map is unexported — deliberately, so a caller cannot add one.