How Omarchy Uses `colors.toml` Palette Keys for Unified System Theming

Omarchy treats colors.toml as the single source of truth for color palettes, automatically propagating palette keys to terminal emulators, shell UI, editors, browsers, and compositor configurations through a template-based rendering pipeline.

Omarchy's theming system revolves around a central colors.toml file found in each theme directory. This file defines named palette keys—accent, background, foreground, terminal colors, and extended variants—that power every color decision across the desktop environment. Understanding how Omarchy uses these palette keys enables precise, system-wide color customization.

Where colors.toml Lives and What It Defines

Each Omarchy theme stores its palette in themes/<name>/colors.toml. These keys are grouped into logical categories:

• Base colors: foreground, background, accent
• ANSI colors: red, green, yellow, blue, magenta, cyan
• Bright variants: bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_black, bright_white

When colors.toml palette keys are modified, the changes cascade to every component that consumes them.

The colors.toml Propagation Pipeline

Omarchy's theming engine follows a three-stage pipeline defined in bin/omarchy-theme-set and supporting utilities. Here's how colors.toml palette keys reach every corner of the system:

1. Staging the Palette

The omarchy-theme-set command first stages the selected theme's colors.toml into the active configuration area. If a user overlay exists at ~/.config/omarchy/themes/<name>/colors.toml, that version takes precedence over the bundled theme.

2. Template Rendering with omarchy-theme-render-templates

Palette keys from colors.toml feed into template substitution via omarchy-theme-render-templates. Templates throughout the system use {{ palette.<key> }} syntax:

• Terminal emulators: Generates alacritty.toml, foot.ini, kitty.conf
• Shell UI: Renders default/shell.toml for top bar, menus, notifications, OSD, and lock screen
• System monitors: Produces btop themes
• Prompts and syntax highlighting: Configures starship.toml and bat themes

3. Target Deployment

Rendered files copy into ~/.config/omarchy/ subdirectories. The pipeline preserves hand-written overrides—if you've customized shell.toml or icons.theme, those edits survive palette updates.

Components Consuming colors.toml Palette Keys

Component	How colors.toml Keys Apply
Terminal emulators (Alacritty, Foot, Kitty)	Direct interpolation into config templates
Shell UI (top bar, menus, notifications, lock screen)	default/shell.toml reads palette directly; template rendering substitutes placeholders per docs/omarchy-shell.md
Btop, Starship, Bat	Dedicated config generators receive palette mappings
Chromium/Chrome	Generated CSS themes driven by palette keys
Hyprland, Hyprpaper	Wallpaper and compositor accent colors sourced from background and accent keys
Neovim, Helix, VS Code, Obsidian	Editor theme files written with synchronized color variables

This architecture ensures that changing accent = "#ff6f00" in themes/rose-pine/colors.toml instantly updates every visual surface referencing that key.

Working with colors.toml in Practice

Modify a Palette Key and Reapply

# Edit the catppuccin theme's accent color

nano ~/.config/omarchy/themes/catppuccin/colors.toml

# Change: accent = "#ff6f00"

# Regenerate all dependent configurations

omarchy-theme-set catppuccin

Verify Propagation

# Confirm the new accent appears in generated terminal config

grep -F "#ff6f00" ~/.config/omarchy/term/alacritty.toml

Extract Legacy Palettes

Themes predating colors.toml require palette extraction:

# Generate colors.toml from an existing Alacritty configuration

omarchy-theme-colors-from-alacritty /path/to/old/theme/alacritty.toml > /tmp/colors.toml

# Install as proper theme palette

cp /tmp/colors.toml ~/.config/omarchy/themes/old-theme/colors.toml
omarchy-theme-set old-theme

Key Source Files and Documentation

Path	Purpose
themes/*/colors.toml	Canonical palette definitions per theme
docs/theming.md	Complete palette key reference and theming architecture
docs/omarchy-shell.md	Shell UI palette consumption specifics
manual/43-making-your-own-theme.md	Authoring guide for custom colors.toml files
default/agents/skills/omarchy/theming.md	Command workflows for palette editing
test/shell.d/theme-staging-test.sh	Verification that staged palettes supply correct values (e.g., #7aa2f7 assertions)
bin/omarchy-theme-set	Core orchestration of palette staging and template rendering

Missing Keys and Fallback Behavior

If a colors.toml palette key is absent, the rendering step falls back to the previous theme's value rather than failing. This permits incremental theme development and prevents broken configurations during palette transitions.

Summary

• colors.toml in each theme directory defines the canonical palette as foreground, background, accent, and ANSI color keys
• omarchy-theme-set stages the palette and triggers omarchy-theme-render-templates to propagate values system-wide
• Template substitution using {{ palette.<key> }} syntax applies colors to terminals, shell UI, editors, browsers, and the compositor
• User overlays at ~/.config/omarchy/themes/<name>/colors.toml enable persistent customization without modifying bundled themes
• Legacy themes integrate via omarchy-theme-colors-from-alacritty extraction

Frequently Asked Questions

What happens if I delete a key from colors.toml?

The rendering pipeline retains the previous theme's value for that key. Omarchy does not crash or produce broken configs—missing keys simply trigger fallback behavior until you define them.

Can I use colors.toml palette keys in my own shell scripts?

Yes. The staged colors.toml is available at a predictable path within ~/.config/omarchy/. Parse it with standard TOML tools or source helpers from the Omarchy environment to reference {{ palette.<key> }} values programmatically.

How do I preview a palette change without applying the full theme?

Run omarchy-theme-render-templates manually after editing colors.toml. This regenerates config files without the full omarchy-theme-set staging cycle, letting you inspect outputs before committing to the change.

Does Omarchy support extended color keys beyond the ANSI set?

The base pipeline expects standard palette keys, but nothing prevents adding custom keys to colors.toml. Templates that reference them via {{ palette.custom_key }} will substitute correctly; templates without those references simply ignore extra keys.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}