> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes and colors

> Change Otter Shell colors and spacing in otter-settings or theme.conf. Per-app overrides inherit from the shared theme when left blank.

All Otter Shell apps share one theme via `otter-theme`. The **Theme** tab in [otter-settings](/desktop/otter-settings) previews all 12 built-in presets and writes changes on **Apply**.

```bash theme={null}
otter-settings
```

Changes land in `~/.config/otter-shell/theme.conf`. Running apps that watch the file pick them up. [otter-term](/apps/otter-term) hot-reloads `theme.conf` without a restart. [otter-bar](/desktop/otter-bar) refreshes widget colors on `theme.conf` changes without reloading `otter-bar.conf`.

<Tip>
  Stick with otter-settings unless you need keys the UI does not expose. It keeps comments and field order on save.
</Tip>

## Theme config file

Edit `~/.config/otter-shell/theme.conf` directly if you prefer. otter-bar, otter-transcribe, and otter-term read it at startup and on change.

## Terminal colors

Set otter-term's 16-color palette and UI chrome in otter-settings under **Terminal**, or in `~/.config/otter-shell/otter-term.conf`:

```conf theme={null}
colors_background = "#1e1e2e"
colors_foreground = "#cdd6f4"
colors_cursor     = "#f5e0dc"
colors_selection  = "#313244"

# 16-color palette
colors_black   = "#45475a"
colors_red     = "#f38ba8"
colors_green   = "#a6e3a1"
colors_yellow  = "#f9e2af"
colors_blue    = "#89b4fa"
colors_magenta = "#f5c2e7"
colors_cyan    = "#94e2d5"
colors_white   = "#bac2de"
```

Terminal colors hot-reload on save.

## App-level color overrides

Apps can override the shared theme with their own color keys. In otter-transcribe's **Transcribe** tab (or `otter-transcribe.conf`):

```conf theme={null}
background_color  = ""
border_color      = ""
graph_color       = ""
graph_peak_color  = ""
text_color        = ""
```

Empty string `""` inherits from the theme. Set a hex color to override for that app only.

## Font

Default terminal font: `IoskeleyMono Nerd Font`, bundled in `otter-shell-fonts` at `/usr/share/fonts/otter-shell/`.

Change it in otter-settings under **Terminal**, or in `otter-term.conf`:

```conf theme={null}
font_family    = "JetBrains Mono"
font_size      = 14
font_dpi_aware = true
```

`font_dpi_aware = true` scales font and padding on high-DPI displays. Empty `font_family = ""` falls back to the bundled Nerd Font.

## Window decorations

You can choose how Otter XDG toplevels ask for decorations, and how client-side titlebars look when CSD is on.

In otter-settings, open the **Theme** tab and use the **Decorations** and **CSD** sections. Or set keys in `theme.conf`:

```conf theme={null}
# Prefer server, client, client_floating, or none
decorations_prefered_decoration_type = "server"

# Client-side decoration chrome (used when CSD is active)
csd_button_layout = ":sbc"
csd_titlebar_height = 28
csd_border_size = 1
```

| Value             | Meaning                                                            |
| ----------------- | ------------------------------------------------------------------ |
| `server`          | Prefer compositor (SSD) decorations when supported                 |
| `client`          | Prefer application (CSD) decorations                               |
| `client_floating` | Prefer CSD while floating; maximized windows follow the compositor |
| `none`            | No decoration preference                                           |

`csd_button_layout` uses GTK-style layout. `:` is the center. Letters before it go left; letters after go right. `c` = close, `b` = maximize, `s` = minimize. Default `:sbc` puts minimize, maximize, and close on the right.

CSD also has titlebar and button color tokens (`csd_titlebar_bg_active`, `csd_button_close_bg`, and related keys). Built-in presets fill those in.

## Built-in presets

In the otter-settings theme browser:

Otter Shell, Otter Shell Islands, Catppuccin (Mocha/Latte/Frappe/Macchiato), Nord, Gruvbox, Dracula, Tokyo Night, One Dark.

## Wallpaper-reactive themes (Theme Gen)

Want colors that follow your wallpaper? Run [otter-theme-gen](/desktop/otter-theme-gen) with [otter-wallpaper](/desktop/otter-wallpaper), then use the **Theme Gen** tab in [otter-settings](/desktop/otter-settings). It edits `otter-theme-gen.conf`. The daemon ships in `otter-shell`.

When enabled, `otter-theme-gen` watches `$XDG_RUNTIME_DIR/otter-shell/wallpaper-state` and updates `theme.conf`. You can sync colors to other apps through template outputs: terminals, GTK, Hyprland (`~/.config/hypr/otter-theme.lua`), KDE color schemes, Papirus folder colors, `bottom`, btop, and more. Toggle each template in the Theme Gen tab, then click **Apply**.

Key options include **Islands mode** for Otter Shell Islands styling and an **Opacity** slider for panel transparency.