blomarchy/docs/themes.md

Themes

A theme is a directory under themes/ holding at minimum a colors.toml. blob-theme-set <name> stages it, renders every template against it, and retints the running desktop.

What a theme can ship

File	Used by
colors.toml	required; the palette everything else derives from
backgrounds/	the background switcher
shell.lock.toml	lock screen surface tokens
neovim.lua	the editor colorscheme
icons.theme	GTK icon theme name
preview.png, unlock.png, preview-unlock.png	theme and lock previews

colors.toml

Named keys are preferred: background, foreground, accent, muted, selection, the eight base colors, and their bright_ variants. The pywal color0..color15 form also works and is resolved through the same cascade: color0 is the background, color4 is blue, color5 is magenta.

That cascade lives in blob-theme-color, and Commons/Color.qml mirrors it so the shell and the CLI never disagree about what a slot means.

Templates

default/themed/*.tpl are rendered per theme into ~/.local/state/blob/current/theme/. Nine ship: foot, kitty, btop, chromium, hyprland, the screenshare picker, neovim, shell.toml, and zen.

An app picks its colors up in one of two ways. Most include the generated file directly, so nothing has to run:

include ~/.local/state/blob/current/theme/kitty.conf

Zen does the same through a CSS import in userChrome.css. The rest are pushed by a short applier listed in post_theme_commands inside blob-theme-set: blob-theme-foot, blob-theme-browser, blob-restart-terminal, blob-restart-btop, blob-hypr-restart.

Adding a template for another app means dropping a .tpl in default/themed/ and, if it cannot include a file, adding an applier to that list.

The three ways to set a theme

Command	Does
blob theme menu	pick from the bundled and local sets
blob theme set <name>	apply one by name
blob wallpaper set <image>	extract a palette from a wallpaper with pywal, fix flat palettes with blob-theme-contrast, and apply it as blob-dynamic
blob theme share <link>	fetch a shared palette and apply it as blob-dynamic

Aether is also installed and does the same job with a GUI. To have its palettes land where these do, add Blob as a custom app in Aether with a template writing colors.toml into ~/.local/state/blob/current/theme/ and a post-apply hook calling blob-theme-refresh.

Bundled themes

Twenty-two came across from upstream, plus flats and pitch-dark. Their backgrounds/ directories are empty on purpose: the upstream images were Omarchy branding, and ~/wallpapers holds 103 of your own. A theme with no background of its own leaves the current wallpaper alone.

Because of that, a machine with no wallpaper yet would get none from the theme either. The installer covers the gap: it symlinks ~/wallpapers to the checkout, applies flats, and points the background symlink at the first image it finds. See install.md.