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

Omarchy themes store their complete color scheme in a semantic 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/ or themes/nord/. At the heart of each directory sits a 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 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 does not remain isolated. Omarchy uses a template system located in 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/quattro/install/user/theme.sh), the script stages the 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/quattro/install/user/theme.sh), which handles the deployment of the selected theme's palette. The script copies or references the 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/quattro/test/shell.d/theme-staging-test.sh), where assertions verify that color values from 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:

# 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:

# 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/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, located in the theme's root directory (e.g., [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/ with the .tpl extension. These templates contain placeholders such as {{ background }} that get replaced with values from 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 or create a new theme directory with your own 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/ within the repository. These files use placeholder syntax to reference keys from colors.toml and are processed by the theme activation script to produce final configuration files.

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