# Understanding colors.toml in Omarchy Theming: The Centralized Palette System

> Discover how Omarchy's colors.toml acts as a centralized palette system, defining named colors for consistent desktop environment visuals. Learn about this key theming file.

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

---

**The [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file serves as the single source of truth for color palettes in Omarchy, defining named color values that the theming engine substitutes into templates during theme activation to ensure consistent visuals across the desktop environment.**

In the Omarchy desktop environment, all visual consistency stems from a single declarative configuration. Located within each theme directory, [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) acts as the centralized palette that drives every theme-specific rendering decision, from shell notifications to window borders. According to the Omarchy source code, this file is parsed during the activation workflow defined in `bin/omarchy-theme-set` and exposed to both template processors and QML runtime components.

## What Is colors.toml?

[`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) is the core palette file for every Omarchy theme. It defines the set of named color values that the theming engine uses when generating all theme-specific configuration files, including [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml), Hyprland Lua scripts, and other QML assets.

The file organizes colors into semantic categories:

- **Semantic palette**: `accent`, `selection`, `muted`
- **Backgrounds**: `background`, `dark_background`, `darker_background`, `lighter_background`
- **Foregrounds**: `foreground`, `dark_foreground`, `light_foreground`, `bright_foreground`
- **Named colors**: `red`, `green`, `blue`, `cyan`, `magenta`, `yellow` (plus `bright_*` variants)
- **Mode flag**: `mode = "light"` or `mode = "dark"` (controls default light/dark behavior)

As documented in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md), if a theme lacks a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml), template rendering is skipped entirely and any hand-written files are used directly. Therefore, this file represents the **declarative foundation** that determines every visual component of the Omarchy desktop environment.

## The Theme Activation Pipeline

When you activate a theme using `omarchy-theme-set <name>`, Omarchy executes a four-step process that centers on [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml):

1. **Stage the theme**: Copy the selected theme's directory (`themes/<name>/`) into a staging area.
2. **Load the palette**: Parse the [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file from that directory to extract all color definitions.
3. **Render templates**: Process the built-in templates in `default/themed/*.tpl` (or user-provided templates) by substituting placeholders like `{{ accent }}` with values defined in [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml).
4. **Deploy**: Write the rendered files into the active theme location at `~/.local/state/omarchy/current/theme`.

This pipeline ensures that a single change in [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) propagates consistently across all generated configuration files.

## Template Substitution and Color Functions

During the rendering phase, the theming engine processes [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) values through a template syntax that supports various formatting helpers.

### Basic Placeholder Substitution

Reference any key from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) using double braces:

```toml

# default/themed/shell.toml.tpl (excerpt)

[notifications]
border = "{{ accent }}"
text   = "{{ foreground }}"

```

When the theme activates, `{{ accent }}` is replaced by the hex value from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) (for example, `#6e6e6e`).

### Stripped Values and RGB Components

For contexts requiring different color formats, use suffixes:

```toml

# Hex value without the hash prefix

{{ accent_strip }}   # → 6e6e6e

# Decimal RGB components

{{ accent_rgb }}     # → 110,110,110

```

### Color Mixing and Gradients

Generate intermediate colors for hover states or gradients:

```text
{{ mix background foreground 15% }}
{{ mix_strip background accent 0.35 }}
{{ mix_rgb color0 color7 50 }}

```

These helpers blend two palette colors by the specified percentage.

### Hyprland Lua Configuration

For window manager colors, use the gradient helper:

```lua
local active_border_color = {{ hypr_gradient hyprland_active_border accent }}

```

If `hyprland_active_border` defines a gradient, this expands to a Lua table; otherwise it falls back to the `accent` color value.

## Runtime QML Integration

Beyond template rendering, [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) values are exposed to the running desktop environment through the `Color` singleton. QML components can access the active palette directly:

```qml
import qs.Commons
import qs.Ui

BorderSurface {
  color: Color.notifications.border   // Runtime value from colors.toml
}

```

This ensures that applications and shell components remain synchronized with the current theme without requiring regeneration.

## Summary

- **[`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml)** defines the complete color palette for any Omarchy theme and resides at `themes/<name>/colors.toml`.
- The file drives the **four-step activation process** executed by `bin/omarchy-theme-set`, populating templates in `default/themed/*.tpl`.
- It supports **semantic keys**, background/foreground variants, and named terminal colors, plus a **mode flag** for light/dark behavior.
- Template placeholders like `{{ accent }}`, `{{ accent_strip }}`, and `{{ mix ... }}` enable flexible color substitution during rendering.
- Runtime access is available via the **`Color` singleton** in QML, ensuring live UI components reflect the active palette.
- Without this file, themes fall back to hand-written configurations without template processing.

## Frequently Asked Questions

### Where is colors.toml located in an Omarchy theme?

Each theme stores its palette at `themes/<name>/colors.toml` within the Omarchy repository. When activated via `omarchy-theme-set`, this file is read to populate templates in `default/themed/*.tpl` before the rendered output is staged to `~/.local/state/omarchy/current/theme`.

### What happens if a theme doesn't include a colors.toml file?

If [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) is missing, the theming engine skips all template rendering entirely. Any hand-written configuration files in the theme directory are copied directly without substitution, meaning placeholders like `{{ accent }}` will appear literally in the output rather than being replaced with color values.

### How do I use colors.toml values in custom templates?

Reference palette keys using double-brace syntax such as `{{ accent }}` for hex values, `{{ accent_strip }}` for hex without the hash prefix, or `{{ accent_rgb }}` for decimal RGB format. Advanced functions like `{{ mix color1 color2 50% }}` allow blending colors for gradients or hover states, while `{{ hypr_gradient ... }}` handles Lua table generation for Hyprland.

### Can I access colors.toml values from QML applications?

Yes, Omarchy exposes the palette through the `Color` singleton. Import `qs.Commons` and `qs.Ui` in your QML files, then reference values like `Color.notifications.border` to access the corresponding entry from the active theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) at runtime.