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

> Discover how colors.toml defines the semantic color palette for Omarchy themes, influencing the entire desktop environment's look and feel.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-25

---

**The [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/colors.toml).

If a theme lacks a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file, the system automatically generates one by parsing an existing [`alacritty.toml`](https://github.com/basecamp/omarchy/blob/main/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`:

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

```

When the engine processes this template, it substitutes the placeholders with values from [`themes/white/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml) (for example, `background = "#1a1b26"` and `accent = "#7aa2f7"`), producing the final [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) consumed by the runtime environment.

## Runtime Color Resolution

After activation, the running shell loads the generated [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/colors.toml).

This architectural pattern ensures that borders, gradients, terminal cursor colours, and UI chrome all draw from the same palette. Because [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/colors.toml).

## Summary

- **[`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file, Omarchy automatically generates one by extracting colour values from an existing [`alacritty.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/colors.toml).

### Can colors.toml contain color mixing or manipulation functions?

No, [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.