turbo-editors/turbo-golo · write-a-theme.md

⑂ main

write-a-theme.md · 160 lines · 8.3 KBmarkdown    Blame HistoryRaw
📦 Turbo Golo   1# How to write your own theme
3This guide shows how to add a colour theme of your own. It assumes you know where your configuration directory is and can edit a TOML file.
5## 1. Find where themes go
8turbo-golo -list-themes
11The last line tells you the directory — `~/.config/turbo-golo/themes` on Linux, `~/Library/Application Support/turbo-golo/themes` on macOS. Create it:
14mkdir -p ~/.config/turbo-golo/themes
17## 2. Start from an existing theme
19The quickest start is to inherit from one that already works and override only what you want:
22# ~/.config/turbo-golo/themes/mine.toml
23name = "Mine"
24description = "Turbo Classic, but the comments are readable."
25inherits = "turbo-classic"
28"syntax.comment" = { fg = "#8a8a8a", italic = true }
29"syntax.string"  = { fg = "#87d7af" }
32Everything you do not set is taken from `turbo-classic`.
34**Inherit from a theme whose ground is the same as yours.** The colours you leave out were chosen against the background of the theme you inherit from, so a dark theme built on `turbo-classic` will show, here and there, a colour picked for Borland navy. If you are writing a dark theme, inherit from `turbo-dark`, `cappuccino`, `catppuccin-frappe`, `cobalt`, `darcula` or `monochrome-dark`; if a light one, from `borland-light`, `catppuccin-latte`, `intellij-light` or `monochrome-light`. That is also why the eleven themes that ship in the binary each state their palette in full rather than inheriting most of it — a test holds them to it, because a shipped theme is one the project is answerable for.
36## 3. Use it
39turbo-golo -theme mine main.golo
42Or from inside the editor: `Options ▸ Theme…`, which lists every theme it can find.
44## 4. Iterate
46Edit the file, then restart the editor. There is no live reload.
48If the theme fails to load, Turbo Golo falls back to the default rather than refusing to start. To see *why* it failed:
51turbo-golo -list-themes
54A broken theme is listed with the parse error beside it — an unknown colour name is an error, not a silent fallback, so a typo is pointed at rather than quietly repainting half the screen.
56## 5. Check it stays readable
58turbo-core, the library the themes ship in, holds every one of them to five measured rules, and they are worth applying to your own. Its test suite runs them.
60| Rule | Why |
61| --- | --- |
62| The cursor is at least 64 apart from the line it sits on, in its strongest channel | A terminal draws its cursor over the cell; one that blends in cannot be found |
63| The cursor is never a plain reversal of that line | A terminal that draws its cursor by inverting the cell would invert it back into invisibility |
64| The current line is at least 16 from the page | `turbo-dark` once used ten, which is no highlight at all |
65| Text you have to read is at least 64 from its background | Furniture — the desktop, a shadow, a scrollbar trough, a disabled entry — is exempt: it exists to recede |
66| Comments read at 4.5:1 or better against their background, by WCAG relative luminance | A comment is prose, read word by word. `turbo-classic` drew them in `#808080` on its navy: 128 channel values apart, so the rule above waved it through, and 4.05:1 to read, which is below the W3C's floor for body text. |
68The contrast rule is applied to every shipped theme but the two Catppuccin ones, and the exemption is written where it is made: their colours are somebody else's published palette, faithfully copied, and Catppuccin puts comments at 2.87:1 in Frappé and 2.83:1 in Latte. A theme called Catppuccin that is not those exact values is a different theme wearing a borrowed name, so the fix — if anyone wants one — is upstream.
70It is applied to comments and to nothing else. `syntax.punctuation` is quieter still in several themes and stays that way: punctuation is recognised by shape, not read.
72A sixth rule catches the mistake no measurement finds: **two syntax classes a reader meets side by side must not be drawn identically**. `turbo-classic` once painted `syntax.link` the same lime as `syntax.string`, so a Markdown link and an inline code span were the same thing on screen — every colour readable, every key set, and the two simply equal. Both monochromes pass this rule with no hue at all, by using bold, italic and underline instead.
74## Variants
76**Override a shipped theme rather than adding one.** Name your file after it — `turbo-classic.toml` — and yours wins. The embedded one is not replaced, so deleting your file brings it back.
78**Start from scratch.** Leave `inherits` out. Set at least `default`; every key you do not set falls back along the dots to it, so a theme with one line is still a usable theme.
80**Colour only the syntax.** One key does it:
84syntax = { fg = "silver" }
87`syntax.keyword`, `syntax.string` and the rest all fall back to it.
89**Keep the terminal's own colours.** Use `default` as a colour value:
93"editor.text" = { fg = "default", bg = "default" }
96**Test it in a checkout without installing it.** Point the editor at any directory:
99TURBO_GOLO_THEME_DIR=./my-themes turbo-golo -theme mine main.golo
102**The cursor is hard to see.** `editor.cursor` does two things: its **background** is sent to the terminal as the cursor's own colour, and it also paints the cell underneath as a fallback for terminals that ignore that. Set it to something loud:
105
106"editor.cursor" = { fg = "#000000", bg = "#ff8700" }
109Two things make a cursor colour a bad one, and the test suite rejects both: a plain reversal of the line — which terminals that draw their cursor by inverting the cell turn back into invisibility — and anything less than 64 channel values away from the line it sits on.
111**The cursor's line is hard to find.** That is `editor.currentline`, and it is a different key. It has to differ from `editor.text` by at least 16 channel values to count as a highlight at all.
113**Golo types and builtins look alike.** In `turbo-classic` a capitalised name such as `Point` is `syntax.type`, and `println` is `syntax.builtin`; both are aqua on navy, and only the builtin is bold. If that is too close for you, give one of them a colour of its own:
116
117"syntax.type"    = { fg = "yellow" }
118"syntax.builtin" = { fg = "aqua", bold = true }
121**Markdown and HTML look plain.** Five keys belong to the markup languages and have no equivalent in Golo, so a theme written before they existed does not set them:
124
125"syntax.heading"   = { fg = "white", bold = true }
126"syntax.tag"       = { fg = "aqua" }
127"syntax.attribute" = { fg = "yellow" }
128"syntax.emphasis"  = { fg = "fuchsia", bold = true }
129"syntax.link"      = { fg = "aqua", underline = true }
132Give `syntax.link` a different colour from `syntax.string`: a link and an inline `code` span sit side by side in most prose, and sharing a colour makes them one blur. The shipped `turbo-classic` had exactly that fault until it was looked at on a real terminal.
134**The project tree looks flat.** It has four keys of its own, and none of them falls back to `list`:
137
138"tree.text"      = { fg = "silver", bg = "navy" }
139"tree.directory" = { fg = "white", bg = "navy", bold = true }
140"tree.selected"  = { fg = "black", bg = "aqua" }
141"tree.unfocused" = { fg = "black", bg = "gray" }
144Give `tree.text` the same background as `window.body`, so the tree looks like part of its window, and make `tree.selected` clearly different from it — the test suite holds every shipped theme to at least 64 channel values between the two, because a highlight the same colour as the page is no highlight.
146**Terminal windows look wrong.** They have two keys of their own, and neither falls back to `editor`:
149
150"terminal.text"   = { fg = "silver", bg = "black" }
151"terminal.cursor" = { fg = "black", bg = "aqua" }
154`terminal.text` is what a shell's output gets when it names no colour of its own — set it to something close to a real terminal rather than to your editor background, or `less` and `htop` will look out of place. A program that does name its colours keeps them either way.
156## See also
158- Every key you may set, and every colour name: [theme file reference](../reference/themes.md)
159- Which class each piece of Golo gets: [Languages coloured](../reference/languages.md)
160- Why the format is TOML with two kinds of inheritance: [Design decisions](../explanation/design-decisions.md)

📦 Turbo Golo d710c1b k33g 12h ago	1	# How to write your own theme
	2
	3	This guide shows how to add a colour theme of your own. It assumes you know where your configuration directory is and can edit a TOML file.
	4
	5	## 1. Find where themes go
	6
	7	```bash
	8	turbo-golo -list-themes
	9	```
	10
	11	The last line tells you the directory — `~/.config/turbo-golo/themes` on Linux, `~/Library/Application Support/turbo-golo/themes` on macOS. Create it:
	12
	13	```bash
	14	mkdir -p ~/.config/turbo-golo/themes
	15	```
	16
	17	## 2. Start from an existing theme
	18
	19	The quickest start is to inherit from one that already works and override only what you want:
	20
	21	```toml
	22	# ~/.config/turbo-golo/themes/mine.toml
	23	name = "Mine"
	24	description = "Turbo Classic, but the comments are readable."
	25	inherits = "turbo-classic"
	26
	27	[colors]
	28	"syntax.comment" = { fg = "#8a8a8a", italic = true }
	29	"syntax.string" = { fg = "#87d7af" }
	30	```
	31
	32	Everything you do not set is taken from `turbo-classic`.
	33
	34	Inherit from a theme whose ground is the same as yours. The colours you leave out were chosen against the background of the theme you inherit from, so a dark theme built on `turbo-classic` will show, here and there, a colour picked for Borland navy. If you are writing a dark theme, inherit from `turbo-dark`, `cappuccino`, `catppuccin-frappe`, `cobalt`, `darcula` or `monochrome-dark`; if a light one, from `borland-light`, `catppuccin-latte`, `intellij-light` or `monochrome-light`. That is also why the eleven themes that ship in the binary each state their palette in full rather than inheriting most of it — a test holds them to it, because a shipped theme is one the project is answerable for.
	35
	36	## 3. Use it
	37
	38	```bash
	39	turbo-golo -theme mine main.golo
	40	```
	41
	42	Or from inside the editor: `Options ▸ Theme…`, which lists every theme it can find.
	43
	44	## 4. Iterate
	45
	46	Edit the file, then restart the editor. There is no live reload.
	47
	48	If the theme fails to load, Turbo Golo falls back to the default rather than refusing to start. To see why it failed:
	49
	50	```bash
	51	turbo-golo -list-themes
	52	```
	53
	54	A broken theme is listed with the parse error beside it — an unknown colour name is an error, not a silent fallback, so a typo is pointed at rather than quietly repainting half the screen.
	55
	56	## 5. Check it stays readable
	57
	58	turbo-core, the library the themes ship in, holds every one of them to five measured rules, and they are worth applying to your own. Its test suite runs them.
	59
	60	\| Rule \| Why \|
	61	\| --- \| --- \|
	62	\| The cursor is at least 64 apart from the line it sits on, in its strongest channel \| A terminal draws its cursor over the cell; one that blends in cannot be found \|
	63	\| The cursor is never a plain reversal of that line \| A terminal that draws its cursor by inverting the cell would invert it back into invisibility \|
	64	\| The current line is at least 16 from the page \| `turbo-dark` once used ten, which is no highlight at all \|
65	\| Text you have to read is at least 64 from its background \| Furniture — the desktop, a shadow, a scrollbar trough, a disabled entry — is exempt: it exists to recede \|
66	\| Comments read at 4.5:1 or better against their background, by WCAG relative luminance \| A comment is prose, read word by word. `turbo-classic` drew them in `#808080` on its navy: 128 channel values apart, so the rule above waved it through, and 4.05:1 to read, which is below the W3C's floor for body text. \|
67
68	The contrast rule is applied to every shipped theme but the two Catppuccin ones, and the exemption is written where it is made: their colours are somebody else's published palette, faithfully copied, and Catppuccin puts comments at 2.87:1 in Frappé and 2.83:1 in Latte. A theme called Catppuccin that is not those exact values is a different theme wearing a borrowed name, so the fix — if anyone wants one — is upstream.
69
70	It is applied to comments and to nothing else. `syntax.punctuation` is quieter still in several themes and stays that way: punctuation is recognised by shape, not read.
71
72	A sixth rule catches the mistake no measurement finds: two syntax classes a reader meets side by side must not be drawn identically. `turbo-classic` once painted `syntax.link` the same lime as `syntax.string`, so a Markdown link and an inline code span were the same thing on screen — every colour readable, every key set, and the two simply equal. Both monochromes pass this rule with no hue at all, by using bold, italic and underline instead.
73
74	## Variants
75
76	Override a shipped theme rather than adding one. Name your file after it — `turbo-classic.toml` — and yours wins. The embedded one is not replaced, so deleting your file brings it back.
77
78	Start from scratch. Leave `inherits` out. Set at least `default`; every key you do not set falls back along the dots to it, so a theme with one line is still a usable theme.
79
80	Colour only the syntax. One key does it:
81
82	```toml
83	[colors]
84	syntax = { fg = "silver" }
85	```
86
87	`syntax.keyword`, `syntax.string` and the rest all fall back to it.
88
89	Keep the terminal's own colours. Use `default` as a colour value:
90
91	```toml
92	[colors]
93	"editor.text" = { fg = "default", bg = "default" }
94	```
95
96	Test it in a checkout without installing it. Point the editor at any directory:
97
98	```bash
99	TURBO_GOLO_THEME_DIR=./my-themes turbo-golo -theme mine main.golo
100	```
101
102	The cursor is hard to see. `editor.cursor` does two things: its background is sent to the terminal as the cursor's own colour, and it also paints the cell underneath as a fallback for terminals that ignore that. Set it to something loud:
103
104	```toml
105	[colors]
106	"editor.cursor" = { fg = "#000000", bg = "#ff8700" }
107	```
108
109	Two things make a cursor colour a bad one, and the test suite rejects both: a plain reversal of the line — which terminals that draw their cursor by inverting the cell turn back into invisibility — and anything less than 64 channel values away from the line it sits on.
110
111	The cursor's line is hard to find. That is `editor.currentline`, and it is a different key. It has to differ from `editor.text` by at least 16 channel values to count as a highlight at all.
112
113	Golo types and builtins look alike. In `turbo-classic` a capitalised name such as `Point` is `syntax.type`, and `println` is `syntax.builtin`; both are aqua on navy, and only the builtin is bold. If that is too close for you, give one of them a colour of its own:
114
115	```toml
116	[colors]
117	"syntax.type" = { fg = "yellow" }
118	"syntax.builtin" = { fg = "aqua", bold = true }
119	```
120
121	Markdown and HTML look plain. Five keys belong to the markup languages and have no equivalent in Golo, so a theme written before they existed does not set them:
122
123	```toml
124	[colors]
125	"syntax.heading" = { fg = "white", bold = true }
126	"syntax.tag" = { fg = "aqua" }
127	"syntax.attribute" = { fg = "yellow" }
128	"syntax.emphasis" = { fg = "fuchsia", bold = true }
129	"syntax.link" = { fg = "aqua", underline = true }
130	```
131
132	Give `syntax.link` a different colour from `syntax.string`: a link and an inline `code` span sit side by side in most prose, and sharing a colour makes them one blur. The shipped `turbo-classic` had exactly that fault until it was looked at on a real terminal.
133
134	The project tree looks flat. It has four keys of its own, and none of them falls back to `list`:
135
136	```toml
137	[colors]
138	"tree.text" = { fg = "silver", bg = "navy" }
139	"tree.directory" = { fg = "white", bg = "navy", bold = true }
140	"tree.selected" = { fg = "black", bg = "aqua" }
141	"tree.unfocused" = { fg = "black", bg = "gray" }
142	```
143
144	Give `tree.text` the same background as `window.body`, so the tree looks like part of its window, and make `tree.selected` clearly different from it — the test suite holds every shipped theme to at least 64 channel values between the two, because a highlight the same colour as the page is no highlight.
145
146	Terminal windows look wrong. They have two keys of their own, and neither falls back to `editor`:
147
148	```toml
149	[colors]
150	"terminal.text" = { fg = "silver", bg = "black" }
151	"terminal.cursor" = { fg = "black", bg = "aqua" }
152	```
153
154	`terminal.text` is what a shell's output gets when it names no colour of its own — set it to something close to a real terminal rather than to your editor background, or `less` and `htop` will look out of place. A program that does name its colours keeps them either way.
155
156	## See also
157
158	- Every key you may set, and every colour name: [theme file reference](../reference/themes.md)
159	- Which class each piece of Golo gets: [Languages coloured](../reference/languages.md)
160	- Why the format is TOML with two kinds of inheritance: [Design decisions](../explanation/design-decisions.md)