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

> Discover how Omarchy leverages colors.toml palette keys as the single source of truth for unified system theming across terminal emulators, shell UI, editors, browsers, and compositor configurations.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-03

---

**Omarchy treats [`colors.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/colors.toml) palette keys are modified, the changes cascade to every component that consumes them.

## The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/colors.toml) feed into **template substitution** via `omarchy-theme-render-templates`. Templates throughout the system use `{{ palette.<key> }}` syntax:

- **Terminal emulators**: Generates [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml), [`foot.ini`](https://github.com/omacom/omarchy/blob/main/foot.ini), [`kitty.conf`](https://github.com/omacom/omarchy/blob/main/kitty.conf)
- **Shell UI**: Renders [`default/shell.toml`](https://github.com/omacom/omarchy/blob/main/default/shell.toml) for top bar, menus, notifications, OSD, and lock screen
- **System monitors**: Produces `btop` themes
- **Prompts and syntax highlighting**: Configures [`starship.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/shell.toml) or `icons.theme`, those edits survive palette updates.

## Components Consuming [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) Palette Keys

| Component | How [`colors.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/default/shell.toml) reads palette directly; template rendering substitutes placeholders per [`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/themes/rose-pine/colors.toml) instantly updates every visual surface referencing that key.

## Working with [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) in Practice

### Modify a Palette Key and Reapply

```bash

# 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

```bash

# Confirm the new accent appears in generated terminal config

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

```

### Extract Legacy Palettes

Themes predating [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) require palette extraction:

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) | Complete palette key reference and theming architecture |
| [`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md) | Shell UI palette consumption specifics |
| [`manual/43-making-your-own-theme.md`](https://github.com/omacom/omarchy/blob/main/manual/43-making-your-own-theme.md) | Authoring guide for custom [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) files |
| [`default/agents/skills/omarchy/theming.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/theming.md) | Command workflows for palette editing |
| [`test/shell.d/theme-staging-test.sh`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/colors.toml) palette keys in my own shell scripts?

Yes. The staged [`colors.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/colors.toml). Templates that reference them via `{{ palette.custom_key }}` will substitute correctly; templates without those references simply ignore extra keys.