What Is the Purpose of colors.toml in an Omarchy Theme?

The colors.toml file serves as the canonical color palette definition for an Omarchy theme, supplying the semantic values that populate template placeholders across the entire desktop environment.

In the basecamp/omarchy repository, colors.toml acts as the single source of truth for all chromatic styling. This mandatory configuration file defines every hue used by the shell, window manager, and terminal emulators, ensuring a consistent visual identity from boot to shutdown.

The Core Purpose of colors.toml

colors.toml operates as the cornerstone of the Omarchy theming engine. Located at themes/<name>/colors.toml within a theme directory, it declares semantic colour keys—such as accent, background, foreground, and named slots like red or blue—that abstract specific hex values from the underlying configuration files.

The file follows a semantic-first grouping structure. According to docs/theming.md, keys are organized by function: accent, selection, and muted tones appear first, followed by background shades, foreground shades, and finally named colours. This organization allows the template renderer to quickly resolve placeholders like {{ accent }} or {{ background }} during theme activation.

How colors.toml Drives Template Rendering

When you activate a theme via omarchy-theme-set <name>, the script bin/omarchy-theme-set orchestrates a build process that renders every file under default/themed/*.tpl. These template files contain placeholders such as {{ accent }}, {{ key_strip }}, or {{ mix … }}. The omarchy-theme-set-templates utility replaces each placeholder with the corresponding value defined in the active theme's colors.toml.

If a theme lacks a colors.toml file, the system automatically generates one by parsing an existing alacritty.toml, ensuring a palette is always available for rendering. This fallback mechanism guarantees that template processing never fails due to missing colour definitions.

Template Example

Consider the template file default/themed/shell.toml.tpl:

[bar]
background = "{{ background }}"
foreground = "{{ foreground }}"
accent     = "{{ accent }}"

When the engine processes this template, it substitutes the placeholders with values from themes/white/colors.toml (for example, background = "#1a1b26" and accent = "#7aa2f7"), producing the final shell.toml consumed by the runtime environment.

Runtime Color Resolution

After activation, the running shell loads the generated shell.toml (produced from shell.toml.tpl). Inside the shell's QML interface, colour tokens are accessed through the Color singleton. For instance, the expression Color.menu.border resolves back to a value originally defined in colors.toml.

This architectural pattern ensures that borders, gradients, terminal cursor colours, and UI chrome all draw from the same palette. Because colors.toml is the single source of truth, changing one value in the palette immediately cascades through every themed component without manual edits to individual application configs.

Security and Theme Distribution

The role of colors.toml extends beyond aesthetics into system security. When installing themes from remote git repositories, the Omarchy engine restricts the staging process to colour-related files only. This constraint prevents malicious themes from shipping executable scripts or arbitrary code, as documented in docs/theming.md under the section detailing what an installed theme may not ship.

By limiting the attack surface to colour definitions, Omarchy allows users to install third-party themes safely while maintaining strict control over the code that executes on their system.

Inspecting and Debugging Colors

To verify the active palette or debug colour values, use the following commands:

# Display the current theme's colour palette

omarchy dev theme-preview current

# Manually inspect the resolved palette file

cat ~/.local/state/omarchy/current/theme/colors.toml

These utilities read directly from the staged theme state, showing the exact hex values that the template engine extracted from the source colors.toml.

Summary

• colors.toml defines the semantic colour palette for an Omarchy theme, serving as the single source of truth for all UI colouring.
• The bin/omarchy-theme-set script renders templates in default/themed/*.tpl by substituting placeholders like {{ accent }} with values from this file.
• If absent, the system auto-generates the palette from alacritty.toml, ensuring template rendering always succeeds.
• Runtime QML code accesses these values through the Color singleton (e.g., Color.menu.border), maintaining visual consistency across the shell and applications.
• Security policies restrict git-based themes to colour files only, mitigating risks by preventing arbitrary code execution.

Frequently Asked Questions

What happens if a theme is missing colors.toml?

If a theme directory lacks a colors.toml file, Omarchy automatically generates one by extracting colour values from an existing alacritty.toml configuration. This fallback ensures that the template rendering pipeline in bin/omarchy-theme-set always has a valid palette to populate placeholders like {{ background }} and {{ accent }}.

How are color values referenced in Omarchy templates?

Template files located in default/themed/*.tpl reference colours using double-brace syntax: {{ key }} for standard values, {{ key_strip }} for variants without the # prefix, and {{ mix … }} for blended colours. The omarchy-theme-set-templates utility processes these directives during theme activation, pulling concrete hex codes from the active colors.toml.

Can colors.toml contain color mixing or manipulation functions?

No, colors.toml stores static colour definitions only. However, the template engine supports manipulation through placeholder syntax such as {{ mix … }}, allowing dynamic colour generation during the rendering phase without requiring complex logic inside the palette file itself.

Where is the active colors.toml stored after theme activation?

Once a theme is activated, the resolved colors.toml is staged in the runtime state directory. You can inspect the active palette at ~/.local/state/omarchy/current/theme/colors.toml, which reflects the final values used by the shell and UI components after any auto-generation or template processing has occurred.

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