otter-theme graph.
Theme files
The root file is$XDG_CONFIG_HOME/otter-shell/theme.conf, defaulting to ~/.config/otter-shell/theme.conf. It selects three layer files and global appearance settings:
~/ paths, and paths relative to the root theme file are supported. Settings preserves custom layer paths when you edit an unrelated field.
User
theme.conf takes precedence over /etc/otter-shell/theme.conf; compiled defaults provide the final fallback. The loader also supports migrating older flat theme files. For new configuration, use the selected layer files instead of obsolete colors_*, icons_theme, csd_*, or transparency_background_blur root keys.
Colors
A color file contains these roles:preset-colors.conf and selects it through colors_path without replacing layout or spacing.
Islands is the bar_islands global, not a twelfth color preset.
Layout and density
Choose Current or Bank as layout. Current uses 4 px standalone control and panel radii. Bank uses status markers, 2 px control radii, 6 px panel radii, a wider navigation column, and a dock panel. Layout selection does not replace your colors. Generic list selection uses tonal fill rather than adding a second focus indicator. Choose Compact, Standard, or Spacious for density. Changing colors does not change these dimensions. For custom layout files, supported fields include:decoration accepts server, client, client_floating, or none. window_buttons uses : to separate left and right groups, with s for minimize, b for maximize, and c for close. Actual server decorations depend on compositor support.
Fonts and icons
font_family and font_size in theme.conf control shared UI typography. Terminal fonts and ANSI palette remain application settings in otter-term.conf; use Terminal in Settings for those.
Set icon_theme to an XDG icon theme name or absolute theme directory. For example:
icon_theme overrides that detection. otter-shell-fonts installs fallback fonts under /usr/share/fonts/otter-shell/ and depends on Inter and Noto Color Emoji font packages.
Opacity and blur
opacity is a percentage from 0 to 100. blur requests compositor background effects where supported:
App overrides
Apps can override selected theme values in their own config. Missing optional color keys inherit the shared theme. Settings marks present overrides with App override and offers Reset to remove only that key. Do not assume that an empty string has the same meaning for every field. Use Settings or the application’s documented config schema.Wallpaper-reactive colors
otter-theme-gen watches the wallpaper state from otter-wallpaper and writesgenerated-colors.conf. Select that file as the color source through Settings. Generated colors do not replace layout, density, typography, or decoration choices.
The Theme Gen tab controls the generator and optional templates for other apps. Hyprland template output uses ~/.config/hypr/otter-theme.lua; enabling the template does not configure your compositor’s imports for you.
Hot reload
Long-running applications watchtheme.conf and the selected color, layout, and spacing files. Saving a valid edit refreshes the theme. A failed reload retains the previous valid theme rather than publishing partial state.
Normal reads of layered themes do not rewrite files. Loading an older flat theme can perform a one-time migration: the loader keeps a .legacy backup, writes custom color/layout/spacing files, and updates the root to select them. Settings and Theme Gen own intentional normalization and later theme changes. See Configuration overview for app-specific reload behavior.