# How the Color Palette Is Defined in Omarchy Themes: A Declarative Guide to colors.toml

> Discover how Omarchy themes define color palettes using colors.toml. Learn how hex values map to UI roles for automatic application across configurations.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-08-30

---

**Omarchy themes store their complete color scheme in a semantic [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file within each theme directory, where hex values map to UI roles like `background` and `accent`, and the system automatically injects these values across all application configurations via templates.**

In the omacom/omarchy repository, the color palette is not hardcoded across dozens of configuration files. Instead, each theme encapsulates its entire chromatic identity in a single declarative file located at `themes/<name>/colors.toml`. Understanding how this file structures color roles and propagates through the system reveals why Omarchy themes remain consistent and maintainable.

## The Central Role of colors.toml in Omarchy Themes

Every Omarchy theme resides in its own subdirectory under `themes/`, such as [`themes/white/`](https://github.com/omacom/omarchy/tree/quattro/themes/white) or [`themes/nord/`](https://github.com/omacom/omarchy/tree/quattro/themes/nord). At the heart of each directory sits a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file that serves as the single source of truth for every color value used throughout the desktop environment.

This TOML file uses a flat key-value structure where keys represent **semantic UI roles** and values are hex color strings. The Omarchy framework consumes this file during theme activation, staging the palette for injection into various application configurations.

### Semantic Color Keys and the ANSI Spectrum

The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file defines three distinct categories of color variables:

- **Background Variations**: Keys like `background`, `dark_background`, `darker_background`, and `lighter_background` create depth for windows, panels, and widgets.
- **Foreground and Accent**: The `foreground` key sets default text color, while `accent` drives interactive highlights, selections, and links.
- **ANSI Terminal Colors**: Standard keys including `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, and their `bright_*` variants ensure terminal applications render consistently with the GUI.

## How the Color Palette Propagates Through Templates

The color palette defined in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) does not remain isolated. Omarchy uses a template system located in [`default/themed/`](https://github.com/omacom/omarchy/tree/quattro/default/themed) where files use the `.tpl` extension. These templates contain placeholders such as `{{ background }}`, `{{ accent }}`, or `{{ bright_red }}`.

When a user activates a theme via [[`install/user/theme.sh`](https://github.com/omacom/omarchy/blob/main/install/user/theme.sh)](https://github.com/omacom/omarchy/blob/quattro/install/user/theme.sh), the script stages the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file and processes these templates, substituting placeholders with actual hex values from the palette. This generates concrete configuration files for Hyprland, btop, VS Code, and other tools without manual duplication of color values.

## Theme Activation and Runtime Staging

The activation logic lives in [[`install/user/theme.sh`](https://github.com/omacom/omarchy/blob/main/install/user/theme.sh)](https://github.com/omacom/omarchy/blob/quattro/install/user/theme.sh), which handles the deployment of the selected theme's palette. The script copies or references the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) into the runtime state, ensuring that subsequent template processing pulls from the correct palette.

Validation occurs in [[`test/shell.d/theme-staging-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/theme-staging-test.sh)](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/theme-staging-test.sh), where assertions verify that color values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) correctly propagate into staged configuration files. This automated testing guarantees that modifications to a theme's palette immediately reflect across all supported applications.

## Practical Color Palette Examples from the Source

The **White theme** demonstrates a high-contrast light palette:

```toml

# themes/white/colors.toml

background = "#ffffff"
dark_background = "#f5f5f5"
darker_background = "#e8e8e8"
lighter_background = "#c0c0c0"

accent = "#7aa2f7"
foreground = "#000000"

red = "#ff5f5f"
green = "#5fff5f"
yellow = "#ffff5f"
blue = "#5f87ff"
magenta = "#ff5fff"
cyan = "#5fffff"

bright_red = "#ff8787"
bright_green = "#87ff87"
bright_yellow = "#ffff87"
bright_blue = "#5fafdf"
bright_magenta = "#ff87ff"
bright_cyan = "#5fffff"

```

Conversely, the **Nord theme** uses a polar-inspired dark scheme:

```toml

# themes/nord/colors.toml

background = "#2e3440"
dark_background = "#222730"
darker_background = "#191c23"
lighter_background = "#3b4252"

accent = "#88c0d0"
foreground = "#eceff4"

red = "#bf616a"
green = "#a3be8c"
yellow = "#ebcb8b"
blue = "#81a1c1"
magenta = "#b48ead"
cyan = "#88c0d0"

bright_red = "#d08770"
bright_green = "#8fbcbb"
bright_yellow = "#e5e9f0"
bright_blue = "#5e81ac"
bright_magenta = "#b48ead"
bright_cyan = "#88c0d0"

```

These files illustrate the declarative nature of Omarchy's theming system—authors modify only the hex values while the framework handles distribution to all UI components.

## Summary

- **Single Source of Truth**: Each Omarchy theme stores its complete color palette in `themes/<theme-name>/colors.toml` using semantic key names.
- **Three-Tier Structure**: Palettes define background variations, foreground/accent colors, and a full ANSI terminal spectrum.
- **Template Injection**: The `default/themed/*.tpl` files consume the palette via `{{ variable }}` syntax, automatically generating application configs.
- **Automated Staging**: The [[`install/user/theme.sh`](https://github.com/omacom/omarchy/blob/main/install/user/theme.sh)](https://github.com/omacom/omarchy/blob/quattro/install/user/theme.sh) script and test suite ensure color values propagate correctly without manual intervention.

## Frequently Asked Questions

### What file defines the color palette in an Omarchy theme?

The color palette is defined in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), located in the theme's root directory (e.g., [[`themes/white/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/white/colors.toml)](https://github.com/omacom/omarchy/blob/quattro/themes/white/colors.toml)). This file contains all hex color values mapped to semantic keys like `background`, `accent`, and `red`.

### How does Omarchy apply the color palette to different applications?

Omarchy uses template files stored in [`default/themed/`](https://github.com/omacom/omarchy/tree/quattro/default/themed) with the `.tpl` extension. These templates contain placeholders such as `{{ background }}` that get replaced with values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) during theme activation, generating final config files for tools like Hyprland and btop.

### Can I use custom color values in an Omarchy theme?

Yes, you can modify any hex value in a theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) or create a new theme directory with your own [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). As long as you maintain the required semantic key names (e.g., `foreground`, `accent`, `red`), the system will automatically apply your custom palette across all templated configurations.

### Where are the color palette templates located?

Template files reside in [`default/themed/`](https://github.com/omacom/omarchy/tree/quattro/default/themed) within the repository. These files use placeholder syntax to reference keys from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and are processed by the theme activation script to produce final configuration files.