# Omarchy theming Omarchy themes live under `themes//` in the source tree (installed at `/usr/share/omarchy/themes//`), with optional user themes under `~/.config/omarchy/themes//`. A theme normally starts with a `colors.toml`; Omarchy generates the active theme files from `default/themed/*.tpl` when `omarchy-theme-set ` runs. Beyond `colors.toml` and hand-written config overrides, a first-party theme can ship `backgrounds/` (users overlay their own via `~/.config/omarchy/backgrounds//`; the active image is the `~/.local/state/omarchy/current/background` symlink), `preview.png` and `preview-unlock.png` for the theme switcher, `keyboard.rgb`, `unlock.png`, and a `light.mode` marker file. A theme can pair a still background with a silent intro video using matching filenames: `backgrounds/0-winding-road.webp` and `backgrounds/intros/0-winding-road.mp4`. The video plays automatically at login, when switching to that theme with this background selected, and when this background is chosen within the current theme (`omarchy-theme-bg-set`, `omarchy-theme-bg-next`, the background picker, or reselecting the theme). No registration, checksum file or manual setting is needed. Supported video extensions are `mp4`, `m4v`, `mov`, `webm`, `mkv` and `avi`. Intro videos stay inside the nested `intros/` directory so the background picker does not list them as looping wallpapers. An image selected from another directory looks for its intro in that directory's own `intros/`, so a same-named custom image cannot inherit a theme's video. The built-in themes' intros live in [omacom/omarchy-themes-intros](https://github.com/omacom/omarchy-themes-intros), not in this repository, and ship as the `omarchy-themes-intros` package into these same `backgrounds/intros/` directories. Aim for a video between five and seven seconds long that opens on its scene setup and ends on the matching still. The shell provides the opening crossfade, so an added fade from black is unnecessary. OWE owns decoding, mute and the handoff back to that image. The theme picker prepares the highlighted theme's remembered intro offscreen, paused at its opening frame. OWE keeps one prepared clip and an idle renderer for up to one minute, then releases them. A theme switch also starts preparation while its templates render; OWE compares the selected video with the prepared clip before resuming it. Older OWE versions use the ordinary startup path. Hyprland and the SDDM greeter use a black compositor background. On a fresh login, the persistent shell host keeps an opaque black cover above the bar and wallpaper until the bar has loaded and OWE has a moving video frame, then fades both in together over 420 ms. With intros disabled or unavailable, it waits for the still to be ready instead. A ten-second deadline releases the cover if a missing wallpaper or failed plugin never becomes ready. Ordinary shell restarts preload the selected still alongside the bar without mapping that login cover. Login intros use the Hyprland instance signature, so logging out and back in plays the intro again. The launcher consumes the current session before waiting up to five seconds for OWE. Shell restarts and a daemon starting after that window cannot play a delayed intro. The shell's `BackgroundSwitch` service sequences every change that involves an intro: `omarchy-theme-set` puts up its cover and hands the rest over with `omarchy-shell shell playThemeIntro`, and `omarchy-theme-bg-set` hands a whole background change over with `omarchy-shell shell switchBackground`. Each step waits on the event that allows it: the background link moves once the cover is on screen, the new still goes in under the cover before OWE starts the clip in its first-frame mode, and the cover fades once the clip is moving. An interrupted video supplies its currently playing frame as the outgoing snapshot. Rapid selections wait for the previous opening fade to finish before capturing it. Theme replacement and playback wait for the outgoing cover to decode and reach the compositor on every screen. A persistent layer holds that outgoing wallpaper until OWE hides the shell background and reports a ready video with an advancing playback position and no outgoing still transition, then crossfades it over 420 ms while applying the new bar palette. The shell retains its background service and decoded wallpaper while it is hidden, so handing the still back does not recreate them. App retints wait until the opening crossfade completes, with a three-second bound, so they do not compete with its first frames. The compositor reload waits until playback finishes because reloading Hyprland pauses video presentation. A switch superseded during its intro carries its reload over until no intro plays. Failed playback releases the pending palette, and a newer theme invalidates the older handoff. A background change uses the same cover and crossfade with the unchanged palette and no compositor reload; reselecting the background already shown plays nothing. A change to a still without an intro of its own, made while an intro plays, holds the playing frame under the cover and opens it with the ordinary slanted cut once OWE hands the desktop back. Refreshing a theme and headless setup do not trigger intros. Appearance > Animations suppresses playback along with the other animations. The `omarchy theme bg intro toggle` command can toggle intros separately. A still can also have a loop under the same name in `backgrounds/loops/`, such as `backgrounds/loops/0-winding-road.mp4`. OWE plays it in the still's place, after the still's intro if it has one, and goes back to the still when animations are turned off or the machine runs on battery, since decoding a loop costs a laptop several watts. It resumes on AC power. The background link keeps naming the still, so the background picker, cycling, theme memory and the lock screen only ever see stills. A loop's first frame is its still and its last frame leads straight back into it, so it repeats without a jump. Keep the motion small and steady through the whole clip, since easing in or out at the ends reads as the picture starting and stopping. Keep a loop to twenty seconds or less, so its file stays small. Encode it as H.264 at no more than the still's size, with one keyframe per loop, no B-frames, and colour tags matching the matrix it was encoded with, so its first frame matches the still on screen. The built-in themes' loops live in [omacom/omarchy-themes-loops](https://github.com/omacom/omarchy-themes-loops), not in this repository, and ship as the `omarchy-themes-loops` package into these same `backgrounds/loops/` directories. A theme installed from a git repo is held to a much shorter list; see [What an installed theme may not ship](#what-an-installed-theme-may-not-ship). ## Theme activation flow `omarchy-theme-set ` builds a clean staging directory at `~/.local/state/omarchy/current/next-theme`: 1. Copy the first-party theme from `themes//`. 2. Overlay `~/.config/omarchy/themes//`, in full when the user wrote it and filtered when it came from a git repo, naming anything it dropped on stderr. 3. If needed, generate `colors.toml` from `alacritty.toml`. 4. Run `omarchy-theme-set-templates` to render templates into the staging theme. 5. Move the staging theme into `~/.local/state/omarchy/current/theme`, write `~/.local/state/omarchy/current/theme.name`, and notify the running shell. Template rendering only happens when the staged theme has `colors.toml`. Existing files are never overwritten by a template, so a hand-written `themes//shell.toml` or `hyprland.lua` wins over `default/themed/shell.toml.tpl` or `hyprland.lua.tpl`. User templates in `~/.config/omarchy/themed/*.tpl` are processed before the built-in templates. If a user template has the same output filename as a built-in template, the built-in output is skipped. After activation, `omarchy-theme-set` retints what is on screen first: the terminals and the programs inside them (`visible_theme_commands`), plus the Hyprland reload when no background intro is playing (an intro reloads after playback). Those run in parallel and the command waits for them. The rest of the apps — GTK, the browser policy, editors, agents, the keyboard backlight (`other_theme_commands`) — then retint in parallel, followed by the `theme-set` hook (`~/.config/omarchy/hooks/theme-set*`, theme name in `$1`). During an intro they wait for its reveal first. A switch from the theme picker, the menu or a script does not wait for that second group: the command returns and the group finishes in the background, writing its output to `~/.local/state/omarchy/theme-set.log` and naming any retint that failed in a notification. Run in a terminal, or with `OMARCHY_THEME_WAIT=1`, it waits for everything and reports failures on stderr, so a browser policy update can ask for a sudo password there. A systemd service or timer that sets the theme should set `OMARCHY_THEME_WAIT=1` as well: when a oneshot unit finishes, systemd stops whatever is left in its cgroup, and the background group with it. A failed retint never changes the exit status. Batches from quick successive switches run one at a time, and a batch whose theme was replaced before it got its turn skips the retints (its hook still runs), so an older theme's slow write can't land after a newer one. Making a new app follow theme changes means adding its restart/retint command to one of the two lists in `bin/omarchy-theme-set`. Runs serialize on a `flock`, so scripted theme changes queue instead of racing. Last, it starts `omarchy-theme-set-herdr-machines` detached. That command sets the same theme on every enabled `herdr machine list` target that runs Omarchy, over SSH inside the remote's live Hyprland session, and logs each machine's result to `~/.local/state/omarchy/theme-set-herdr-machines.log`. Sync is off by default. The `herdr-theme-sync` toggle turns it on, and a machine only sends and accepts themes while it is on. A mirrored change carries `OMARCHY_THEME_SYNC_FROM`, so the receiving machine never sends it on. ## Herdr desktop app `herdr-app.json.tpl` generates the Herdr desktop app's terminal palette and primary-button colors, and `omarchy-theme-set-herdr-app` publishes it atomically as `themes/omarchy.json` in Herdr's home (`$HERDR_APP_HOME`, otherwise `$XDG_CONFIG_HOME/herdr-app`, otherwise `~/.config/herdr-app`) when that home exists. Herdr 0.1.11 and newer reload that file live. This is separate from the terminal Herdr client's remote-machine theme mirroring above. A theme switch only replaces that file: it never contacts Herdr, touches its `settings.json` or reselects a theme, so a theme picked inside Herdr stays picked. Selecting Omarchy is `omarchy-theme-set-herdr-app --activate`, which runs `herdr-app do app.theme --name omarchy` against the running window. `omarchy-install-ai-herdr` does that once the freshly installed app opens. Herdr keeps one theme choice for light and one for dark and `app.theme` sets the half that matches the palette, so the other appearance keeps its own choice until Omarchy is picked there too. The helper holds the theme-switch staging lock while it reads and publishes, so a queued run can't publish an older palette. A palette with unresolved or invalid colors keeps the last good theme and skips without failing the switch. ## What an installed theme may not ship `themes//` in this repo is Omarchy's own code and is trusted. So is a theme the user wrote by hand in `~/.config/omarchy/themes//`: it is their machine and their file, and both stage in full. `omarchy theme install ` is different. It clones a stranger's git repo straight into that same directory, so the contents are whatever the theme author pushed. `omarchy-theme-set` tells the two apart the way `omarchy-theme-extras` already does — a `.git` directory means it was cloned, while a plain directory or a symlink to a working copy is the user's own — and from a cloned one it drops only what can run code: - any `*.lua` — Hyprland `require`s a theme's `hyprland.lua` and `gum_env.lua` at login, and Neovim loads its `neovim.lua` at startup - `alacritty.toml`, `foot.ini`, `ghostty.conf`, `kitty.conf` — each names the program the terminal launches - `vscode.json` — names the extension `omarchy-theme-set-vscode` installs, and a VS Code extension is arbitrary JavaScript Symlinks are dropped with them, at any depth; in a cloned theme they point wherever the theme author chose. Everything a cloned theme ships that is colour is kept, including files Omarchy would otherwise have generated — `btop.theme`, `chromium.theme`, `helix.toml`, `shell.toml`, `keyboard.rgb` and the rest — so a theme can still say exactly how it wants each app to look. What is dropped gets generated from `default/themed/*.tpl` instead, and is named on stderr. A denylist is only right while it is maintained. Adding a template for another terminal, or for another editor that loads Lua, means adding it to `INSTALLED_THEME_DENIED` in `bin/omarchy-theme-set`; `test/shell.d/theme-staging-test.sh` fails on any `default/themed/*.tpl` whose output is recorded as neither code nor colour, so a new template cannot be added without that decision being made. A theme predating `colors.toml` is not left without a palette: its `alacritty.toml` is read through `omarchy-theme-colors-from-alacritty` into a scratch directory and only the resulting `colors.toml` is staged, so the colors survive and the terminal config does not. The restriction lives in `omarchy-theme-set` rather than in `omarchy-theme-install` on purpose. Filtering at staging also covers themes installed before the rule existed and files a theme gains later through `omarchy theme update`. What this does not cover: a theme distributed as an archive rather than a git repo, extracted into `~/.config/omarchy/themes/` by hand, is indistinguishable from one the user wrote and stages in full. `omarchy theme install` only takes git URLs, so the supported path is always filtered, but the check is a statement about where a theme came from and not a sandbox. ## `colors.toml` `colors.toml` provides the palette keys used by templates. Keys are grouped semantic-first: accent/selection/muted, then the backgrounds, then the foregrounds, then the named colors: ```toml mode = "dark" accent = "#7aa2f7" selection = "#292e42" muted = "#414868" background = "#1a1b26" dark_background = "#13141c" darker_background = "#0e0e14" lighter_background = "#24283b" foreground = "#a9b1d6" dark_foreground = "#565f89" light_foreground = "#b4bee6" bright_foreground = "#c0caf5" red = "#f7768e" blue = "#7aa2f7" ``` Any key can be referenced from a template with `{{ key }}`. The foundational shell palette is loaded from: - `foreground` — primary readable text color - `background` — primary background color - `accent` — preferred when present; otherwise some places fall back to `color4` - `muted` — de-emphasized elements (comments, placeholders, dividers); also serves as ANSI `color8` - `red` / `color1` — populate the shell's urgent role; there is no `urgent` palette key (one defined in `colors.toml` is ignored) Themes and user templates using the legacy short names remain supported. Canonical names take precedence when both forms are defined, and resolved canonical values are also exposed through their legacy names: | Canonical | Legacy | |-----------|--------| | `background` | `bg` | | `dark_background` | `dark_bg` | | `darker_background` | `darker_bg` | | `lighter_background` | `lighter_bg` | | `foreground` | `fg` | | `dark_foreground` | `dark_fg` | | `light_foreground` | `light_fg` | | `bright_foreground` | `bright_fg` | The neutral ramp is centered on `background -> bright_foreground`. Dark themes should read from darkest to lightest; light themes should read from lightest to darkest. Terminal and editor cursors use `bright_foreground`; there is no separate cursor palette key. `selection` is the text-selection background stop in that ramp; Omarchy derives `selection_background = selection` and `selection_foreground = bright_foreground`. Use `omarchy dev theme-preview [theme]` to inspect that ramp, including `dark_background`, `darker_background`, and a selected-text sample. ## Template placeholders Templates are plain files ending in `.tpl`. `omarchy-theme-set-templates` replaces placeholders with values from `colors.toml`. ### Color placeholders For a color key such as `accent = "#7aa2f7"`: | Placeholder | Output | |-------------|--------| | `{{ accent }}` | `#7aa2f7` | | `{{ accent_strip }}` | `7aa2f7` | | `{{ accent_rgb }}` | `122,162,247` | ### Color mixing `mix`, `mix_strip`, and `mix_rgb` blend two hex colors by a fraction or percentage: ```text {{ mix background foreground 15% }} {{ mix_strip background accent 0.35 }} {{ mix_rgb color0 color7 50 }} ``` ### Gradient helpers Some theme keys can be either a solid color or a Hyprland-style gradient: ```toml hyprland_active_border = "rgba(33ccffee) rgba(00ff99ee) 45deg" ``` Gradient helper placeholders understand those values: | Helper | Use | Example output | |--------|-----|----------------| | `{{ hypr_gradient hyprland_active_border accent }}` | Hyprland Lua config | `{ colors = { "rgba(33ccffee)", "rgba(00ff99ee)" }, angle = 45 }` | | `{{ shell_gradient hyprland_active_border accent }}` | shell border tokens | `rgba(33ccffee) rgba(00ff99ee) 45deg` | | `{{ gradient_start hyprland_active_border accent }}` | flat-color-only consumers | `#33ccff` | The second argument is a fallback. For example, `{{ shell_gradient hyprland_active_border accent }}` means: use `hyprland_active_border` if the theme defines it; otherwise use `accent`. The helper does not choose the first color unless you use `gradient_start`. ## `shell.toml` `shell.toml` contains shell surface roles, control states, spacing, typography, and bar sizing. The default generated file comes from `default/themed/shell.toml.tpl`. Themes can override the entire generated file by shipping `shell.toml`, or just one section by shipping `shell.
.toml`. For example, `shell.lock.toml` replaces only the `[lock]` section after the default `shell.toml` has been generated: ```toml text = "#ffffff" placeholder = "#ffffff" border = "#ffffff" ``` The filename decides the target section, so the `[lock]` header is optional. The running shell reads `shell.toml` into two QML singletons: - `Color` for palette and surface roles like `Commons.Color.menu.border`. - `Style` for controls, spacing, font scale, corner radius, and bar sizing. ### Borders Shell border tokens accept either a solid color or a gradient in the same key: ```toml [notifications] border = "#7aa2f7" ``` or: ```toml [notifications] border = "rgba(33ccffee) rgba(00ff99ee) 45deg" ``` Do not add a separate `border-gradient` key for new themes. The parser still accepts `border-gradient` and `*-border-gradient` for compatibility with older configs, but the canonical form is the border key itself. Border alphas apply to solid borders and to every gradient stop: ```toml [notifications] border = "rgba(33ccffee) rgba(00ff99ee) 45deg" border-alpha = 0.8 ``` If a color stop already includes alpha, the stop alpha and `border-alpha` are combined. ### Border widths Border widths accept CSS-style lists: ```toml border-width = 2 # all sides border-width = "2 4" # top/bottom, right/left border-width = "2 4 6" # top, right/left, bottom border-width = "2 4 6 8" # top, right, bottom, left ``` Per-side keys override the list: ```toml [notifications] border-width = 2 border-width-left = 6 ``` That gives notifications a 2px border on the top, right, and bottom, and a 6px left edge. State-specific borders follow the same pattern. A selected menu row can use a different width from the card border: ```toml [menu] selected-border = "accent" selected-border-width = "1 1 1 4" ``` For state-specific surfaces such as lock and polkit, the token name prefixes the width key: ```toml [lock] border-active = "rgba(33ccffee) rgba(00ff99ee) 45deg" border-active-width-left = 6 ``` ### Control borders `[controls]` governs shared controls such as buttons, dropdowns, text fields, toggles, and cursor rows. Each state has a fill color, optional border value, border width, and border alpha: ```toml [controls] normal-color = "#a9b1d6" normal-border = "#a9b1d6" normal-border-width = 1 normal-border-alpha = 0.4 hover-cursor-color = "#a9b1d6" hover-cursor-border = "#a9b1d6" hover-cursor-border-width = 1 hover-cursor-border-alpha = 0.25 ``` The `*-border` keys can also be gradients: ```toml [controls] focus-border = "rgba(33ccffee) rgba(00ff99ee) 45deg" focus-border-width = "2 2 2 4" ``` Set a border width to `0` to keep the fill but remove that state border. ### Surface sections Common shell sections include: - `[bar]` - `[controls]` - `[popups]` - `[tooltip]` - `[notifications]` - `[launcher]` - `[menu]` - `[polkit]` - `[lock]` - `[image-picker]` - `[spacing]` - `[font]` Clipboard and emojis inherit menu tokens. Popups are used by bar flyouts, dropdowns, OSD, and popup cards. ## QML border API Plugin and shell QML should use `BorderSurface` for theme-aware borders: ```qml import qs.Commons import qs.Commons as Commons import qs.Ui BorderSurface { color: Commons.Color.popups.background borderSpec: Border.surfaceSpec("popups", "border", Commons.Color.popups.border, 2) padding: Style.spacing.popupPadding Item { anchors.fill: parent anchors.topMargin: parent.contentTopInset anchors.rightMargin: parent.contentRightInset anchors.bottomMargin: parent.contentBottomInset anchors.leftMargin: parent.contentLeftInset } } ``` Use `Border.surfaceSpec(section, token, fallbackColor, fallbackWidth, alphaKey)` for shell theme tokens (the optional `alphaKey` names the alpha token, e.g. `"border-alpha"`), `Border.controlSpec(state, foreground, accent, urgent)` for shared controls, and `Border.flat(color, width)` for a deliberate local border that should not be overridden by the active theme. `Commons.Color.
.border` is the flat first-stop color for consumers that cannot render full border specs. ## Hyprland templates Hyprland theme output is generated from `default/themed/hyprland.lua.tpl`. Use `hypr_gradient` for border values because Hyprland's Lua config wants a Lua string for solid colors and a Lua table for gradients: ```lua local active_border_color = {{ hypr_gradient hyprland_active_border accent }} ``` For a solid fallback this renders: ```lua local active_border_color = "#7aa2f7" ``` For a gradient it renders: ```lua local active_border_color = { colors = { "rgba(33ccffee)", "rgba(00ff99ee)" }, angle = 45 } ``` ## Fcitx candidate window The input method's candidate window is drawn by Fcitx's classicui, from `default/themed/fcitx5-theme.conf.tpl`. `omarchy-theme-set-fcitx5` copies the rendered file to `~/.local/share/fcitx5/themes/omarchy/theme.conf`, links fcitx5's neutral grey page and menu glyphs beside it, and asks a running Fcitx to reload classicui without starting one. Setup and the migration run it with `--activate`, which also points `Theme` and `DarkTheme` in `~/.config/fcitx5/conf/classicui.conf` at `omarchy`, writing through a symlinked file. It replaces only fcitx5's stock `default` and `default-dark`, which a configtool save writes even when only the font changed, so a theme the user installed is kept. Theme switches never reselect it, so choosing fcitx5's own theme afterwards sticks. ## Qt apps Qt apps are themed by the qtengine platform theme (`QT_QPA_PLATFORMTHEME=qtengine` in `default/hypr/envs.lua`), configured by `~/.config/qtengine/config.json`, seeded from `config/qtengine/config.json`. Its `colorScheme` points at `~/.local/state/omarchy/current/theme/qtengine.colors`, a KDE color scheme rendered from `default/themed/qtengine.colors.tpl`; a theme can ship its own `qtengine.colors` instead. qtengine layers `~/.config/kdeglobals` under that file, so the template defines colour roles for both normal and inactive groups. KColorScheme selects an existing inactive subgroup instead of the normal group; omitting one would let a KDE install supply its unfocused-window colours. Content (lists, text fields, editors) sits on `background`, the color a theme's hues are drawn against in the terminal, and the window chrome around it on `dark_background`. Switching themes needs no retint for the palette. The first Qt process to start (normally the shell) claims `org.qtengine.ConfigWatcher` on the session bus and watches the config and the color scheme file; swapping in the new theme directory replaces the file, and that process tells every Qt app to reload. QWidget apps repaint with the new palette; Qt Quick apps only pick it up at their next launch. KDE apps that choose Breeze and their own color scheme are left to do so. The icon theme lives in the config rather than the theme, so `omarchy-theme-set-qt` writes `Adwaita`, the icons every theme uses as GTK does, into `.theme.iconTheme` on each switch, leaving the rest of the file alone. That write also makes running apps reload their icons. Native file dialogs are delegated to the XDG desktop portal (`misc.dialogTheme`), and `config/xdg-desktop-portal/hyprland-portals.conf` sends the file chooser to Files (`folio chooser`), falling back to the GTK one where Files doesn't provide it, so Qt and GTK apps alike get Files' Open and Save dialogs. ## App icons The launcher and dock show an **icon set**: a directory of app icons, picked on its own with `omarchy icons set ` or _Appearance > Icons_, which opens the picker the theme switcher uses over one large preview per set (`omarchy-icons-switcher`). A set and a theme are separate choices. The set says what each icon looks like, the theme says which colors it is drawn in, and a theme ships no icons of its own. Each file in a set is named after the `Icon=` of the desktop entry it is for, so a set may draw any app: - `.svg.tpl` is a template, drawn in the current theme's colors and redrawn on every theme switch. - `.svg` is a finished drawing, used as it is under every theme. Print Settings asks for the `printer` device icon, so its file is `printer.svg.tpl`; it shows in the launcher and dock, while GTK apps keep reading the icon theme's printer. | Set | Where | What it draws | |-----|-------|---------------| | `papercraft` (the default) | `icons/papercraft/` | Omarchy's own apps (Files, Omacut, Omasnap, Hype, Omawrite, Omacalc, Gliff, Plain, Monologue, Signed, Fantasi, Flowtunes and Game Vibes), the launcher's Terminal, Browser, Agent and Activity Monitor (btop), the launchers signing in to an agent or installing a harness adds (Claude Code, Codex, Grok Build and every other harness but Hermes and OpenClaw, which bring their own apps), the other apps a fresh install puts in the launcher (Image Viewer, Media Player, Media Viewer, Document Viewer, Disks, Print Settings, Foot, Neovim, Pinta, LibreOffice Writer, Calc and Impress, Aether, LocalSend, Obsidian, Superwhisper, Herdr, cliamp and disktree), and the apps known by their logos: Google Chrome, Chromium, ChatGPT, Signal, Slack, 1Password, Tailscale, Vim, the default web apps (Basecamp, HEY, Discord, WhatsApp, X, YouTube, Spotify, Netflix, Zoom, and Google Contacts, Maps, Messages and Photos), and Brave Origin, Ghostty, Herdr's desktop app, Kdenlive, Moonlight, OBS Studio, RAWmakase, the Spotify app and WeChat. Herdr's desktop app is its ram on its own, as the terminal window is the Herdr TUI's. A logo keeps its own shape and takes the theme's colors: the logo in the main color, and its details and what it leaves open pale, as the white in the logos themselves; the highlight is left to the rest of the set. The intent is that everything Omarchy launches with has an icon in the set. | | `arcade` | `icons/arcade/` | The same apps as Papercraft, as 8-bit pixel art on a 16 by 16 grid, in the theme's colors. An example of a second look to switch to. | | `original` | nowhere; it is the set with nothing in it | Nothing, so every app shows the icon its package installed. | | the user's own | `~/.config/omarchy/icons//` | Whatever it holds. Written by hand, or cloned by `omarchy icons install `, which names the set after the repo without a leading `omarchy-` and a trailing `-icons`. | A set draws only what it holds; an app it has no file for shows its packaged icon. A user's set with the name of a built-in one is laid over it icon by icon, so `~/.config/omarchy/icons/papercraft/plain.svg.tpl` redraws just Plain in the default set, and a finished `.svg` there replaces the built-in template of that name. `omarchy icons list` lists the sets, `omarchy icons current` names the one in use (`~/.local/state/omarchy/current/icons.name`; the default until one is picked), and `omarchy icons remove` deletes one of the user's, falling back to the default when it was in use. Custom sets are handled the way custom themes are: `omarchy icons install` clones a git repo into `~/.config/omarchy/icons/` (through a staging dir, so a clone that fails leaves the set that was there; it replaces only a set it cloned before that holds no work of the user's own (uncommitted or stashed changes, or commits no remote has, on a branch or a detached `HEAD`), and refuses one the user wrote or linked in), `omarchy icons extras` lists the cloned ones, and `omarchy icons update` (_Update > Extra Icons_) pulls them and draws the set in use again. The default set is not a package of its own; it ships in `icons/` with the rest of Omarchy. A set shows in the picker by its `preview.png` (or `.jpg`, `.jpeg`, `.webp`), 2560 by 1440 in full color for the built-in ones, as a theme's preview is, with the icons kept to the middle since the picker fills its frame and crops the sides; the user's goes ahead of the built-in set of its name. A set that came without one gets a sheet of its icons drawn in the current theme by `omarchy-icons-preview`, cached under `~/.cache/omarchy/icons-selector/` until an icon of the set or a color of the theme changes. The built-in previews are drawn the same way, in Tokyo Night: `omarchy-icons-preview icons/ icons//preview.png themes/tokyo-night`. Original's shows the apps' own icons. Nothing in a set is run: only its `*.svg` and `*.svg.tpl` files are read, and templates only have their color tokens filled in. A set cloned from a git repo (one with a `.git` directory, as with themes) has its symlinks left out, since they point wherever its author chose. `omarchy-theme-set-icons` draws the set in use. Drawing never holds up a theme switch: it runs alongside the terminal restarts once the shell has the new palette (and directly when a theme is set headless), so the dock's icons change with it, and `omarchy icons set` runs it straight away. Draws run one at a time under `current/.icons.lock`, and each reads the set and theme once it holds the lock, so the last to run draws what is current; `omarchy icons set` writes `icons.name` under the same lock, and `omarchy icons remove` removes a set and clears a selection of it under that lock too. It renders the templates with `omarchy-theme-set-templates --icons` into a scratch dir and renames each icon over its predecessor in `~/.local/state/omarchy/current/icons/`, so anything reading an icon mid-switch gets the old one or the new one. Each is linked once by name into `$XDG_DATA_HOME/icons/hicolor/scalable/apps/` (`~/.local/share` by default), ahead of the icon the package installs in `/usr/share`; the links never change, so no icon cache needs rebuilding. An icon the user put there themselves is never replaced. An icon the set in use no longer draws is removed with its link, which brings the packaged icon back: after a switch to a set without it, or under a theme whose colors can't be read. Last it writes `current/icons.revision`, which the shell's app library watches: it rescans its icons and adds the revision to those icons' URLs, so the menu and dock redraw them. The dock keeps each icon until its successor has loaded and fades the new one in over the same 250ms as the bar's palette. The icons don't use palette keys directly, because a key means different things across themes: `magenta` is Tokyo Night's violet but Gruvbox's and Nord's pink, and `bright_foreground` is the lightest color of a dark theme but the darkest of a light one. `omarchy-theme-icon-palette` derives roles from the palette instead, and templates may use them like any other key: | Role | Drawn from | |------|------------| | `icon_main` | `accent`, or `blue` when the accent is grey or too close to the paper | | `icon_main_end` | `icon_main` mixed 30% toward the paper, for gradients | | `icon_mark` | handles, cursors and keys: the theme's violet, else its amber, else its most vivid other color, else a mid grey | | `icon_paper` | `bright_foreground`; `background` in a light theme | | `icon_body` | `background`; `lighter_background` in a light theme | | `icon_edge` | `muted` | | `icon_ink` | `dark_foreground` | | `icon_shadow` | `darker_background`; `dark_background` mixed toward `foreground` in a light theme | | `icon_contrast` | what stands out most on the paper: `icon_shadow` in a dark theme, `foreground` in a light one | | `icon_red`, `icon_orange` | `red` and `orange`, whatever their hue; drawn from the accent's strength when the theme has none | A theme picks any role itself by setting it in `colors.toml` (for example `icon_mark = "#bb9af7"`); that is all a theme says about icons. Any theme gets a best guess, a custom one that only sets its accent, background and foreground included: colors written as `rgb()`, `rgba()`, `0xAARRGGBB` or `#rrggbbaa` are read as `#rrggbb`; a neutral the palette leaves out, or sets to the same color as its neighbor, is mixed from the background and foreground; and a palette that names no hues of its own gets its accent turned 40 degrees for the highlight. Under a theme whose background, foreground or accent can't be read as a color, templates are not drawn and those apps show their packaged icons; a set's finished `.svg` icons still show. ## Adding or overriding theme files - Add palette values to `themes//colors.toml`. - Hand-written overrides work everywhere except a `.lua`, a terminal config or a `vscode.json` in a theme cloned from a git repo; see [What an installed theme may not ship](#what-an-installed-theme-may-not-ship). - Prefer generated files when the theme can be expressed with templates. - Add a hand-written file in `themes//` only when that theme needs to override the generated output entirely. - Add a new built-in template under `default/themed/.tpl` when every theme should generate that file. - Add a user-wide template under `~/.config/omarchy/themed/.tpl` when a local customization should apply across themes. When changing templates or theme helpers, run focused tests such as: ```bash ./test/cli ./test/shell ```