All Otter Shell apps share one theme via otter-theme. The Theme tab in otter-settings lets you choose a visual profile, density, and color source. It also previews all 12 built-in presets.
Settings stores those choices as ordered imports in ~/.config/otter-shell/theme.conf. Built-in preset colors go in preset-colors.conf. Running apps watch the root file and every imported layer. otter-term reloads without a restart, and otter-bar refreshes widget colors without reloading otter-bar.conf.
Stick with otter-settings unless you need keys the UI does not expose. It keeps comments and field order on save.
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.
Theme layers load in this order:
- Compiled Current fallback
- Selected profile,
profiles/current.conf or profiles/bank.conf
- Selected density profile
- Optional
preset-colors.conf or generated-colors.conf
- Explicit fields in root
theme.conf
- Per-app and per-widget overrides
Color layers only change semantic colors. Profiles own geometry, spacing, fonts, radii, and layout. Root overrides always win over imported layers.
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:
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):
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:
font_dpi_aware = true scales font and padding on high-DPI displays. Empty font_family = "" falls back to the bundled Nerd Font.
Icon theme
Set one XDG icon theme for semantic Otter Shell icons:
You can use a theme name or an absolute theme directory. Otter Shell checks it first, prefers SVG icons, then falls back to bundled icons when no match exists. Leave the value unset to use bundled defaults.
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:
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.
Background blur
Many Otter surfaces can ask the compositor to blur what sits behind translucent regions. Toggle it in otter-settings (Theme / Theme Gen blur controls) or in theme.conf:
Default is on. Needs a compositor that supports the Otter background-effect protocol path. If blur is unavailable, surfaces still draw with their usual alpha.
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)
Colors can follow your wallpaper. Run otter-theme-gen with otter-wallpaper, then use the Theme Gen tab in 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 writes ~/.config/otter-shell/generated-colors.conf. It leaves root theme.conf alone. 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.
Islands mode applies Otter Shell Islands styling. The Opacity slider sets panel transparency. 
