Theme

Controls the colors used across the shell — bars, panels, widgets, OSD, backdrop, and notifications.

[theme]
mode              = "dark"        # dark | light | auto
source            = "builtin"     # builtin | wallpaper | community | custom
builtin           = "Noctalia"    # bundled palette name
community_palette = "Oxocarbon"   # community palette name when source = "community"
custom_palette    = "MyPalette"   # file name (without .json) when source = "custom"
wallpaper_scheme  = "m3-content"  # generator used when source = "wallpaper"

Pallette changes apply live when you edit config.toml. Wallpaper-derived themes re-resolve automatically when the default wallpaper changes.

`source`

Value	Description
`builtin`	Use one of the palette compiled into the binary.
`wallpaper`	Generate a palette from the current default wallpaper each time it changes.
`community`	Fetch a palette by name from `https://api.noctalia.dev/palette/<name>`.
`custom`	Load a palette JSON file from `~/.config/noctalia/palettes/`.

`builtin`

Names which bundled palette to load when source = "builtin". Unknown names fall back to Noctalia.

Available palettes: Ayu, Catppuccin, Dracula, Eldritch, Gruvbox, Kanagawa, Noctalia, Nord, Rosé Pine, Tokyo-Night

`community_palette`

Names a palette served by https://api.noctalia.dev/palette/<name>. The shell downloads the palette on first use and caches it in ~/.cache/noctalia/community-palettes/ (honoring XDG_CACHE_HOME). Subsequent launches load the cached file and never touch the network, so community palettes work offline.

The Settings GUI lists palette names from the cached https://api.noctalia.dev/palettes catalog when that catalog is available.

While the initial download is in flight — or if it fails — the shell falls back to Noctalia built-in and cross-fades once the download arrives.

To refresh a palette, delete the corresponding file under ~/.cache/noctalia/community-palettes/.

`custom_palette`

Names a palette file in ~/.config/noctalia/palettes/ (honoring XDG_CONFIG_HOME). The value is the file name without the .json extension — for example, custom_palette = "MyPalette" loads ~/.config/noctalia/palettes/MyPalette.json.

The JSON format is identical to community palettes: a root object with "dark" and "light" keys, each containing the 16 semantic color roles and a "terminal" object. If the "light" key is omitted, the dark variant is used for both modes.

If the file is missing or invalid, the shell falls back to the Noctalia built-in palette.

The Settings GUI lists palette files found in the directory when source = "custom" is selected.

`wallpaper_scheme`

Picks the generator when source = "wallpaper":

Value	Description
`m3-tonal-spot`	M3 default — balanced tones anchored on the seed color
`m3-content`	M3 for content-forward UIs — higher chroma
`m3-fruit-salad`	M3 with playful cross-hue accents
`m3-rainbow`	M3 spanning the full wheel for multi-accent layouts
`m3-monochrome`	M3 collapsed to a single hue
`vibrant`	Custom — saturated and high-contrast
`faithful`	Custom — stays close to the source image
`dysfunctional`	Custom — deliberately off-kilter
`muted`	Custom — low-saturation

`mode`

dark or light selects the palette variant. auto is treated as dark until system light/dark tracking lands.

Shell Color Roles

User-facing shell color settings can reference these 16 color roles:

primary, on_primary, secondary, on_secondary, tertiary, on_tertiary, error, on_error, surface, on_surface, surface_variant, on_surface_variant, outline, shadow, hover, on_hover

Role names are lowercase snake_case. Config fields parsed as palette colors may also accept hex colors where a fixed color is needed; Settings role pickers expose the 16 roles.

IPC

noctalia msg theme-mode-toggle

External App Templates

Noctalia can apply generated colors to external app config files whenever the resolved theme changes.

[theme.templates]
enable_builtin_templates   = true
enable_community_templates = true
builtin_ids                = []        # opt-in; run: noctalia theme --list-builtins
community_ids              = []        # opt-in; fetched from api.noctalia.dev/templates
enable_user_templates      = false
user_config                = "~/.config/noctalia/user-templates.toml"

enable_builtin_templates enables the shipped built-in template catalog.
builtin_ids selects which built-in templates run. Empty array = nothing applied until you opt in.
enable_community_templates enables fetching and applying templates from https://api.noctalia.dev/templates.
community_ids selects which community templates run. Metadata and files are cached in ~/.cache/noctalia/community-templates/ (honoring XDG_CACHE_HOME).
enable_user_templates enables loading your own template file.
user_config points at that extra file. When enabled, Noctalia creates a stub if it does not already exist.

[theme.templates]
enable_builtin_templates   = true
builtin_ids                = ["foot", "gtk3", "gtk4"]
enable_community_templates = true
community_ids              = ["discord", "walker", "vscode"]
enable_user_templates      = true
user_config                = "~/.config/noctalia/user-templates.toml"

List available built-in template ids:

noctalia theme --list-builtins