# Reference: theme file format

> Neutral, exhaustive description of a Turbo Rust 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_RUST_THEME_DIR` | Used when the variable is set and non-empty. |
| `~/.config/turbo-rust/themes` | Linux (`os.UserConfigDir`). |
| `~/Library/Application Support/turbo-rust/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 `-theme` 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

| Key | What it colours |
| --- | --- |
| `syntax.identifier` | An ordinary name |
| `syntax.keyword` | `func`, `if`, `package`, … |
| `syntax.type` | `int`, `string`, and a name after `type` |
| `syntax.builtin` | `len`, `append`, `make`, … |
| `syntax.constant` | `true`, `false`, `nil`, `iota` |
| `syntax.function` | A name before `(`, or after `func` |
| `syntax.string` | A string literal |
| `syntax.char` | A rune literal |
| `syntax.number` | An integer, float or imaginary literal |
| `syntax.comment` | `//` and `/* */` |
| `syntax.operator` | `+`, `:=`, `<-`, … |
| `syntax.punctuation` | Brackets, commas, dots, semicolons |
| `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. |