Reference: theme file format

Neutral, exhaustive description of a Turbo Golo theme file.

A theme is a TOML file. Themes are read from the user theme directory first, then from the ones embedded in the binary; a user file wins over an embedded theme of the same name.

Locations

Location	Notes
`$TURBO_GOLO_THEME_DIR`	Used when the variable is set and non-empty.
`~/.config/turbo-golo/themes`	Linux (`os.UserConfigDir`); `TURBO_GOLO_DIR` replaces the `~/.config/turbo-golo` part when set.
`~/Library/Application Support/turbo-golo/themes`	macOS.
embedded	`turbo-classic`, `turbo-dark`, `borland-light`, `cappuccino`, `catppuccin-frappe`, `catppuccin-latte`, `cobalt`, `darcula`, `intellij-light`, `monochrome-dark`, `monochrome-light`.

A theme's name for -theme and for Options ▸ Theme… is its file name without .toml. It may not contain /, \ or ...

The themes that ship

Name	Ground	For
`turbo-classic`	Borland navy	The default: the palette Turbo C had
`turbo-dark`	Neutral dark grey	Modern terminals with true colour
`borland-light`	Paper white	Bright rooms and projectors
`cappuccino`	Espresso brown	The Turbo layout with the temperature up: milk in the text, caramel where Turbo Dark puts blue
`catppuccin-frappe`	Warm slate	The Catppuccin Frappé palette, unchanged: pastel accents on a soft dark ground
`catppuccin-latte`	Warm paper	The Catppuccin Latte palette, unchanged: the same mapping with the saturation a light ground needs
`cobalt`	Deep navy	The Cobalt palette, accents kept as loud as they are known for
`darcula`	Charcoal	After JetBrains' Darcula: orange keywords, green strings, and the orange punctuation that makes it recognisable
`intellij-light`	White	After JetBrains' IntelliJ Light: blue bold keywords, green bold strings
`monochrome-dark`	Black and greys	No hue at all — code told apart by lightness, bold, italic and underline
`monochrome-light`	Paper and greys	The same, the other way up: on paper the darkest grey is the loudest

Every one of them states its whole palette rather than inheriting most of it. A theme you write yourself may inherit; see writing one.

A name a theme used to answer to

monochrome still loads. It is what this theme shipped as before monochrome-light joined it and the pair was renamed, and a settings file or a -theme flag saying monochrome gets monochrome-dark.

Retired name	Loads
`monochrome`	`monochrome-dark`

A retired name is not listed by -list-themes or by Options ▸ Theme…, so each theme appears once, under the name it has now. A theme of your own called monochrome.toml still wins over it, exactly as it would for any other name.

Top-level fields

Field	Type	Default	Description
`name`	string	the file's base name	Display name, shown in the theme picker and the About box.
`description`	string	`""`	One line, shown by `-list-themes`.
`inherits`	string	none	Name of a theme to start from. Its resolved styles are the base; this file overrides what it names. Chains are capped at 16 hops.
`colors`	table	`{}`	The styles. Keys are the style keys below.

Entry fields

Each value under [colors] is an inline table:

Field	Type	Default	Description
`fg`	string	inherited	Foreground colour.
`bg`	string	inherited	Background colour.
`bold`	bool	`false`	Switch bold on.
`underline`	bool	`false`	Switch underline on.
`italic`	bool	`false`	Switch italic on.
`reverse`	bool	`false`	Swap foreground and background.
`dim`	bool	`false`	Switch dim on.
`blink`	bool	`false`	Switch blink on.

Attributes are only ever switched on; there is no way to switch an inherited attribute off other than by not inheriting it.

Colour values

Form	Example	Notes
ANSI name	`navy`, `aqua`, `silver`, `fuchsia`	The sixteen names, plus the full W3C list.
Hex literal	`#5fafd7`	24-bit; tcell approximates it on terminals without true colour.
`default`	`default`	Whatever the terminal itself uses.
`-`	`-`	Same as `default`.
`""`	`""`	Same as `default`.

The sixteen ANSI names: black maroon green olive navy purple teal silver gray red lime yellow blue fuchsia aqua white.

An unrecognised colour is a load error, not a silent fallback.

Style keys

Undefined keys fall back along the dots, and finally to default.

Base

Key	What it colours
`default`	The last resort of every lookup
`desktop`	The patterned backdrop behind the windows
`shadow`	The cells a window darkens behind itself

Key	What it colours
`menu.bar`	The row of titles
`menu.item`	A drop-down entry
`menu.selected`	The highlighted entry
`menu.shortcut`	The hot letter of a label
`menu.disabled`	An entry that cannot be chosen

Windows

Key	What it colours
`window.frame.active`	The frame of the focused window
`window.frame.inactive`	Every other frame
`window.title.active`	The focused window's title
`window.title.inactive`	Every other title
`window.body`	The interior, before its content draws

Bars

Key	What it colours
`statusbar`	The bar itself
`statusbar.key`	The `Fn` part of a hint
`statusbar.hint`	The right-aligned text
`scrollbar`	A scroll bar's track
`scrollbar.thumb`	Its thumb and arrows

Dialogs and controls

Key	What it colours
`dialog.frame`	A dialog's frame
`dialog.body`	Its interior
`dialog.title`	Its title
`dialog.label`	A line of static text
`button`	A button
`button.focused`	The focused button
`button.shortcut`	The hot letter of a button
`input`	An input field
`input.focused`	The focused input field
`input.selection`	Selected text in an input field
`list`	A list box
`list.selected`	Its highlighted line, when focused
`list.unfocused`	Its highlighted line, when not
`checkbox`	A check box
`checkbox.focused`	The focused check box

Editor

Key	What it colours
`editor.text`	Text no other rule claims
`editor.selection`	Selected text
`editor.linenumber`	The line-number gutter
`editor.currentline`	The line the cursor is on
`editor.cursor`	The cursor. Its background is also sent to the terminal as its cursor colour, and its foreground paints the character underneath.

Terminal

Key	What it colours
`terminal.text`	Every cell of a terminal window whose colour the program running in it did not choose
`terminal.cursor`	The cell under a terminal's cursor, when that window has the focus

A program that names its own colours keeps them: these two only fill in what it left unset. See Terminal windows.

Project tree

Key	What it colours
`tree.text`	A file's name in the project tree, and the tree's background
`tree.directory`	A directory's name
`tree.selected`	The highlighted row, when the tree has the focus
`tree.unfocused`	The highlighted row, when it does not

These are separate from the list.* keys on purpose: a dialog's list is coloured against a dialog, and reusing it would highlight a tree row in the very colour a window's body already is. See Project tree.

Syntax

The examples are Golo's; the other eight languages map their own constructs onto the same classes.

Key	What it colours
`syntax.identifier`	An ordinary name — `args`, `item`, `this`
`syntax.keyword`	`function`, `let`, `module`, `import`, `foreach`, `match`, `when`, …
`syntax.type`	A capitalised name — `Point`, `Shape`, `Circle` — and the dotted path after `module` or `import`
`syntax.builtin`	`println`, `str`, `len`, `list`, `map`, `range`, …
`syntax.constant`	`true`, `false`, `null`
`syntax.function`	A lower-case name before `(`, or the name after `function`
`syntax.string`	`"…"` and `"""…"""`
`syntax.char`	A `'c'` character literal
`syntax.number`	`42`, `3.14`, `1e3`, `42L`, `2.0F`
`syntax.comment`	`#` to the end of the line, and `----` … `----`
`syntax.operator`	`+`, `->`, `==`, `?:`, `..`, …
`syntax.punctuation`	Brackets, commas, dots, semicolons, and the `$` of `Shape$Circle`
`syntax.heading`	A Markdown heading, whole line
`syntax.tag`	An HTML element name and its brackets
`syntax.attribute`	An HTML attribute's name
`syntax.emphasis`	Markdown bold and italic
`syntax.link`	A Markdown link or image

Which language produces which class is in Languages coloured.

Completion and diagnostics

Key	What it colours
`completion.frame`	The popup's frame
`completion.item`	A suggestion
`completion.selected`	The highlighted suggestion
`completion.detail`	The kind tag beside a suggestion
`diagnostic.error`	An error from the language server
`diagnostic.warning`	A warning
`diagnostic.info`	A note

Example

name = "Mine"
description = "Turbo Classic, with readable comments."
inherits = "turbo-classic"

[colors]
"syntax.comment" = { fg = "#8a8a8a", italic = true }
"syntax.string"  = { fg = "#87d7af" }
"editor.currentline" = { bg = "#00005f" }

Errors

Message	Cause
`theme: not found: "x"`	No `x.toml` in the user directory or among the embedded themes.
`theme: not found: "…" is not a plain theme name`	The name contains `/`, `\` or `..`.
`invalid TOML: …`	The file is not valid TOML.
`colors."k": fg: unknown colour "…"`	The colour name is not recognised.
`inherits: chain deeper than 16, probably a loop`	Two themes inherit from each other, directly or through others.
`inherits "x": theme: not found`	The parent named does not exist.

  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
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238


# Reference: theme file format

> Neutral, exhaustive description of a Turbo Golo theme file.

A theme is a TOML file. Themes are read from the user theme directory first, then from the ones embedded in the binary; a user file wins over an embedded theme of the same name.

## Locations

| Location | Notes |
| --- | --- |
| `$TURBO_GOLO_THEME_DIR` | Used when the variable is set and non-empty. |
| `~/.config/turbo-golo/themes` | Linux (`os.UserConfigDir`); `TURBO_GOLO_DIR` replaces the `~/.config/turbo-golo` part when set. |
| `~/Library/Application Support/turbo-golo/themes` | macOS. |
| embedded | `turbo-classic`, `turbo-dark`, `borland-light`, `cappuccino`, `catppuccin-frappe`, `catppuccin-latte`, `cobalt`, `darcula`, `intellij-light`, `monochrome-dark`, `monochrome-light`. |

A theme's **name** for `-theme` and for `Options ▸ Theme…` is its file name without `.toml`. It may not contain `/`, `\` or `..`.

## The themes that ship

| Name | Ground | For |
| --- | --- | --- |
| `turbo-classic` | Borland navy | The default: the palette Turbo C had |
| `turbo-dark` | Neutral dark grey | Modern terminals with true colour |
| `borland-light` | Paper white | Bright rooms and projectors |
| `cappuccino` | Espresso brown | The Turbo layout with the temperature up: milk in the text, caramel where Turbo Dark puts blue |
| `catppuccin-frappe` | Warm slate | The Catppuccin Frappé palette, unchanged: pastel accents on a soft dark ground |
| `catppuccin-latte` | Warm paper | The Catppuccin Latte palette, unchanged: the same mapping with the saturation a light ground needs |
| `cobalt` | Deep navy | The Cobalt palette, accents kept as loud as they are known for |
| `darcula` | Charcoal | After JetBrains' Darcula: orange keywords, green strings, and the orange punctuation that makes it recognisable |
| `intellij-light` | White | After JetBrains' IntelliJ Light: blue bold keywords, green bold strings |
| `monochrome-dark` | Black and greys | No hue at all — code told apart by lightness, bold, italic and underline |
| `monochrome-light` | Paper and greys | The same, the other way up: on paper the darkest grey is the loudest |

Every one of them **states its whole palette** rather than inheriting most of it. A theme you write yourself may inherit; see [writing one](../how-to/write-a-theme.md).

## A name a theme used to answer to

`monochrome` still loads. It is what this theme shipped as before `monochrome-light` joined it and the pair was renamed, and a settings file or a `-theme` flag saying `monochrome` gets `monochrome-dark`.

| Retired name | Loads |
| --- | --- |
| `monochrome` | `monochrome-dark` |

A retired name is **not** listed by `-list-themes` or by **Options ▸ Theme…**, so each theme appears once, under the name it has now. A theme of your own called `monochrome.toml` still wins over it, exactly as it would for any other name.

## Top-level fields

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | string | the file's base name | Display name, shown in the theme picker and the About box. |
| `description` | string | `""` | One line, shown by `-list-themes`. |
| `inherits` | string | none | Name of a theme to start from. Its resolved styles are the base; this file overrides what it names. Chains are capped at 16 hops. |
| `colors` | table | `{}` | The styles. Keys are the style keys below. |

## Entry fields

Each value under `[colors]` is an inline table:

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `fg` | string | inherited | Foreground colour. |
| `bg` | string | inherited | Background colour. |
| `bold` | bool | `false` | Switch bold on. |
| `underline` | bool | `false` | Switch underline on. |
| `italic` | bool | `false` | Switch italic on. |
| `reverse` | bool | `false` | Swap foreground and background. |
| `dim` | bool | `false` | Switch dim on. |
| `blink` | bool | `false` | Switch blink on. |

Attributes are only ever switched **on**; there is no way to switch an inherited attribute off other than by not inheriting it.

## Colour values

| Form | Example | Notes |
| --- | --- | --- |
| ANSI name | `navy`, `aqua`, `silver`, `fuchsia` | The sixteen names, plus the full W3C list. |
| Hex literal | `#5fafd7` | 24-bit; tcell approximates it on terminals without true colour. |
| `default` | `default` | Whatever the terminal itself uses. |
| `-` | `-` | Same as `default`. |
| `""` | `""` | Same as `default`. |

The sixteen ANSI names: `black` `maroon` `green` `olive` `navy` `purple` `teal` `silver` `gray` `red` `lime` `yellow` `blue` `fuchsia` `aqua` `white`.

An unrecognised colour is a **load error**, not a silent fallback.

## Style keys

Undefined keys fall back along the dots, and finally to `default`.

### Base

| Key | What it colours |
| --- | --- |
| `default` | The last resort of every lookup |
| `desktop` | The patterned backdrop behind the windows |
| `shadow` | The cells a window darkens behind itself |

### Menu bar

| Key | What it colours |
| --- | --- |
| `menu.bar` | The row of titles |
| `menu.item` | A drop-down entry |
| `menu.selected` | The highlighted entry |
| `menu.shortcut` | The hot letter of a label |
| `menu.disabled` | An entry that cannot be chosen |

### Windows

| Key | What it colours |
| --- | --- |
| `window.frame.active` | The frame of the focused window |
| `window.frame.inactive` | Every other frame |
| `window.title.active` | The focused window's title |
| `window.title.inactive` | Every other title |
| `window.body` | The interior, before its content draws |

### Bars

| Key | What it colours |
| --- | --- |
| `statusbar` | The bar itself |
| `statusbar.key` | The `Fn` part of a hint |
| `statusbar.hint` | The right-aligned text |
| `scrollbar` | A scroll bar's track |
| `scrollbar.thumb` | Its thumb and arrows |

### Dialogs and controls

| Key | What it colours |
| --- | --- |
| `dialog.frame` | A dialog's frame |
| `dialog.body` | Its interior |
| `dialog.title` | Its title |
| `dialog.label` | A line of static text |
| `button` | A button |
| `button.focused` | The focused button |
| `button.shortcut` | The hot letter of a button |
| `input` | An input field |
| `input.focused` | The focused input field |
| `input.selection` | Selected text in an input field |
| `list` | A list box |
| `list.selected` | Its highlighted line, when focused |
| `list.unfocused` | Its highlighted line, when not |
| `checkbox` | A check box |
| `checkbox.focused` | The focused check box |

### Editor

| Key | What it colours |
| --- | --- |
| `editor.text` | Text no other rule claims |
| `editor.selection` | Selected text |
| `editor.linenumber` | The line-number gutter |
| `editor.currentline` | The line the cursor is on |
| `editor.cursor` | The cursor. Its **background** is also sent to the terminal as its cursor colour, and its foreground paints the character underneath. |

### Terminal

| Key | What it colours |
| --- | --- |
| `terminal.text` | Every cell of a terminal window whose colour the program running in it did not choose |
| `terminal.cursor` | The cell under a terminal's cursor, when that window has the focus |

A program that names its own colours keeps them: these two only fill in what it left unset. See [Terminal windows](terminal.md).

### Project tree

| Key | What it colours |
| --- | --- |
| `tree.text` | A file's name in the project tree, and the tree's background |
| `tree.directory` | A directory's name |
| `tree.selected` | The highlighted row, when the tree has the focus |
| `tree.unfocused` | The highlighted row, when it does not |

These are separate from the `list.*` keys on purpose: a dialog's list is coloured against a dialog, and reusing it would highlight a tree row in the very colour a window's body already is. See [Project tree](project-tree.md).

### Syntax

The examples are Golo's; the other eight languages map their own constructs onto the same classes.

| Key | What it colours |
| --- | --- |
| `syntax.identifier` | An ordinary name — `args`, `item`, `this` |
| `syntax.keyword` | `function`, `let`, `module`, `import`, `foreach`, `match`, `when`, … |
| `syntax.type` | A capitalised name — `Point`, `Shape`, `Circle` — and the dotted path after `module` or `import` |
| `syntax.builtin` | `println`, `str`, `len`, `list`, `map`, `range`, … |
| `syntax.constant` | `true`, `false`, `null` |
| `syntax.function` | A lower-case name before `(`, or the name after `function` |
| `syntax.string` | `"…"` and `"""…"""` |
| `syntax.char` | A `'c'` character literal |
| `syntax.number` | `42`, `3.14`, `1e3`, `42L`, `2.0F` |
| `syntax.comment` | `#` to the end of the line, and `----` … `----` |
| `syntax.operator` | `+`, `->`, `==`, `?:`, `..`, … |
| `syntax.punctuation` | Brackets, commas, dots, semicolons, and the `$` of `Shape$Circle` |
| `syntax.heading` | A Markdown heading, whole line |
| `syntax.tag` | An HTML element name and its brackets |
| `syntax.attribute` | An HTML attribute's name |
| `syntax.emphasis` | Markdown bold and italic |
| `syntax.link` | A Markdown link or image |

Which language produces which class is in [Languages coloured](languages.md).

### Completion and diagnostics

| Key | What it colours |
| --- | --- |
| `completion.frame` | The popup's frame |
| `completion.item` | A suggestion |
| `completion.selected` | The highlighted suggestion |
| `completion.detail` | The kind tag beside a suggestion |
| `diagnostic.error` | An error from the language server |
| `diagnostic.warning` | A warning |
| `diagnostic.info` | A note |

## Example

```toml
name = "Mine"
description = "Turbo Classic, with readable comments."
inherits = "turbo-classic"

[colors]
"syntax.comment" = { fg = "#8a8a8a", italic = true }
"syntax.string"  = { fg = "#87d7af" }
"editor.currentline" = { bg = "#00005f" }
```

## Errors

| Message | Cause |
| --- | --- |
| `theme: not found: "x"` | No `x.toml` in the user directory or among the embedded themes. |
| `theme: not found: "…" is not a plain theme name` | The name contains `/`, `\` or `..`. |
| `invalid TOML: …` | The file is not valid TOML. |
| `colors."k": fg: unknown colour "…"` | The colour name is not recognised. |
| `inherits: chain deeper than 16, probably a loop` | Two themes inherit from each other, directly or through others. |
| `inherits "x": theme: not found` | The parent named does not exist. |