# Themes (/docs/v0.1/configuration/themes)



A theme colours the parts koshi draws itself: pane borders, the tab bar, key
hints, and stack headers. Programs running inside a pane keep their own
colours.

**The file name is the theme name.** `themes/midnight.kdl` is the theme
`midnight`; the file carries no name of its own. It lives in a `themes/`
subdirectory of the [config directory](/docs/v0.1/configuration#where-the-files-go).

Select it in [`koshi.kdl`](/docs/v0.1/configuration/koshi-kdl):

```kdl title="koshi.kdl"
version 1
theme "midnight"        // reads themes/midnight.kdl
```

The built-in `default` colours apply when `theme` is omitted, when it is
`"default"`, or when the selected file is missing or invalid. koshi logs theme
load errors, and a single bad colour keeps its default while the rest of the
file still applies.

## colors [#colors]

The file is the theme — no wrapping block, just a required `version` and an
optional `colors` block. Every colour is a `#RRGGBB` hex string; the leading
`#` is optional.

The tab and key-hint bars fade from `ramp-start` to `ramp-end`. `bar-bg` fills
both rows. `on-ramp` and `on-accent` colour text drawn over filled blocks.

| Key                | What it colours                                           | Default   | Since   |
| ------------------ | --------------------------------------------------------- | --------- | ------- |
| `ramp-start`       | First end of the chrome gradient                          | `#d0a5ff` | ≥ 0.1.0 |
| `ramp-end`         | Second end of the gradient                                | `#7dbcff` | ≥ 0.1.0 |
| `on-ramp`          | Text over a ramp-coloured block                           | `#12091f` | ≥ 0.1.0 |
| `on-ramp-dim`      | Text over a dimmed ramp block                             | `#f0ecfa` | ≥ 0.1.0 |
| `accent`           | Marks the chords already pressed in a pending shortcut    | `#f5c2ff` | ≥ 0.1.0 |
| `on-accent`        | Text over an accent block                                 | `#1e1033` | ≥ 0.1.0 |
| `bar-bg`           | Background of the tab bar and the key-hint bar            | `#000000` | ≥ 0.1.0 |
| `border-focused`   | Border of the focused pane                                | `#00afd7` | ≥ 0.1.0 |
| `border-unfocused` | Border of the other panes                                 | `#585858` | ≥ 0.1.0 |
| `border-hover`     | Border of the pane the pointer is over — the wheel target | `#af5fff` | ≥ 0.1.0 |
| `stack-header-fg`  | Text of a collapsed stack member's header                 | `#f4f1fa` | ≥ 0.1.0 |
| `stack-header-bg`  | Background of that header                                 | `#300f4a` | ≥ 0.1.0 |
| `letterbox`        | The margin around a centred layout                        | `#585858` | ≥ 0.1.0 |

Keep the ramp readable against `bar-bg`, and `on-ramp` readable against the
ramp.

## Every colour at its default [#every-colour-at-its-default]

```kdl title="themes/midnight.kdl"
// themes/midnight.kdl — every colour, at its default value.
version 1

colors {
    ramp-start "#d0a5ff"
    ramp-end "#7dbcff"
    on-ramp "#12091f"
    on-ramp-dim "#f0ecfa"
    accent "#f5c2ff"
    on-accent "#1e1033"
    bar-bg "#000000"
    border-focused "#00afd7"
    border-unfocused "#585858"
    border-hover "#af5fff"
    stack-header-fg "#f4f1fa"
    stack-header-bg "#300f4a"
    letterbox "#585858"
}
```

## Built-in default and twenty-five ready-made themes [#built-in-default-and-twenty-five-ready-made-themes]

The first preview is koshi's built-in `default`. Copy any of the other
twenty-five out of `themes-example/` in the koshi repository into your
`themes/` directory. Each preview applies visible colours exactly where
koshi's renderer does: bar fill, ramp text and hint ribbons, pane borders, and
letterbox. The `~/Projects/koshi-docs` title sits in its top border; `3/388` is a scrolled
pane's `up/retained` marker in its bottom border. The compact grid stays
unstacked, so the copied file keeps its stack-header colours without inventing
a stack on screen. Terminal content keeps its own fixed colours.

<ThemeGallery />