# How Omarchy Themes Use `colors.toml` for Customization: A Complete Guide

> Learn how Omarchy themes use colors.toml for complete UI customization. This guide explains leveraging the single colors.toml file to define your entire color palette.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Omarchy themes rely on a single [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file in each theme directory to define the complete color palette that drives the entire UI and supporting applications.**

The Omarchy colors framework centralizes theme customization through declarative TOML files. Each theme directory contains a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) that specifies semantic colors, background/foreground ramps, and application-specific values. When activated, this file propagates through template rendering to configure everything from the shell UI to terminal emulators and window managers.

## The [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) File Structure

Every Omarchy theme stores its palette in `themes/<name>/colors.toml`. This file follows a strict schema defined in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) that separates concerns into clear sections.

### Core Sections

- **`mode`** — Either `"dark"` or `"light"`, determining default application behavior
- **Semantic colors** — `accent`, `selection`, `muted` for fundamental UI accents
- **Background ramp** — `background`, `dark_background`, `darker_background`, `lighter_background` for layered surfaces
- **Foreground ramp** — `foreground`, `dark_foreground`, `light_foreground`, `bright_foreground` for text hierarchy
- **Named colors** — Standard palette (`red`, `green`, `blue`, etc.) with bright variants

Here is the [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) from the built-in `nord` theme:

```toml
mode = "dark"

accent = "#81a1c1"
selection = "#5e81ac"
muted = "#4c566a"

background = "#2e3440"
dark_background = "#272c36"
darker_background = "#21252d"
lighter_background = "#3b4150"

foreground = "#d8dee9"
dark_foreground = "#616e80"
light_foreground = "#c0c5ce"
bright_foreground = "#eceff4"

red = "#bf616a"
green = "#a3be8c"
blue = "#5e81ac"
yellow = "#ebcb8b"
magenta = "#b48ead"
cyan = "#88c0d0"

```

## How Theme Activation Processes [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml)

The `omarchy-theme-set` script orchestrates the flow that transforms [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) into active configuration.

### Step 1: Staging

When you run `omarchy-theme-set <name>`, the script creates a staging directory at `~/.local/state/omarchy/current/next-theme` and copies the selected theme's files, including its [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) [docs/theming.md#L18-L24](https://github.com/basecamp/omarchy/blob/main/quattro/docs/theming.md).

### Step 2: Template Rendering

The `omarchy-theme-set-templates` script reads `$NEXT_THEME_DIR/colors.toml` and renders every `.tpl` file in `default/themed/` (or user-provided templates). Placeholders like `{{ accent }}` are substituted with concrete values from the TOML file [bin/omarchy-theme-set-templates#L6-L11](https://github.com/basecamp/omarchy/blob/main/quattro/bin/omarchy-theme-set-templates).

### Step 3: Runtime Consumption

The Omarchy shell loads the generated [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) and [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) into QML singletons. In `shell/Commons/Color.qml`, these become the `Color` and `Style` singletons that expose the palette to UI components [shell/Commons/Color.qml#L8-L9](https://github.com/basecamp/omarchy/blob/main/quattro/shell/Commons/Color.qml).

## Placeholder Syntax for [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) Values

Templates use double-brace placeholders to access [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) values with automatic format conversion.

| Placeholder | Output | Example |
|-------------|--------|---------|
| `{{ accent }}` | Full hex color | `#81a1c1` |
| `{{ accent_strip }}` | Hex without `#` | `81a1c1` |
| `{{ accent_rgb }}` | RGB tuple | `129,161,197` |

### Basic Template Usage

In `default/themed/shell.toml.tpl`:

```toml
[bar]
background = "{{ background }}"
foreground = "{{ foreground }}"
accent = "{{ accent_strip }}"      # stripped hex for compatibility

```

### Color Mixing

The `mix` helper blends two palette entries by percentage:

```toml

# In a template file

subtle_highlight = "{{ mix background accent 15% }}"

```

This produces a hex string like `#2f3a4b` in the rendered output [docs/theming.md#L26-L33](https://github.com/basecamp/omarchy/blob/main/quattro/docs/theming.md).

### Gradient Generation

For Hyprland configurations, the `hypr_gradient` helper creates Lua-compatible gradient objects:

```lua
-- In default/themed/hyprland.lua.tpl
local active_border = {{ hypr_gradient hyprland_active_border accent }}

```

If `hyprland_active_border` exists in [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) as a gradient definition, it expands to a Lua table; otherwise it falls back to the `accent` color [docs/theming.md#L45-L48](https://github.com/basecamp/omarchy/blob/main/quattro/docs/theming.md).

## Creating a Custom [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml)

To build your own Omarchy theme, create a new directory under `themes/` with a minimal [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml):

```toml
mode = "light"

accent = "#ff6f61"
selection = "#ffd7d0"
muted = "#e0e0e0"

background = "#ffffff"
dark_background = "#f0f0f0"
darker_background = "#e0e0e0"
lighter_background = "#fafafa"

foreground = "#111111"
dark_foreground = "#555555"
light_foreground = "#222222"
bright_foreground = "#000000"

red = "#d32f2f"
green = "#388e3c"
blue = "#1976d2"

```

Save this as [`themes/my-light/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/my-light/colors.toml), then activate with:

```bash
omarchy-theme-set my-light

```

The script immediately processes your [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) through the template pipeline and applies the resulting configuration.

## Legacy Name Support

Older Omarchy themes may use abbreviated color names (`bg`, `fg`, `color1` through `color16`). The templating engine in `bin/omarchy-theme-set-templates` resolves both canonical and legacy names, with canonical names taking precedence when conflicts occur [docs/theming.md#L85-L93](https://github.com/basecamp/omarchy/blob/main/quattro/docs/theming.md).

## Key Implementation Files

| Path | Purpose |
|------|---------|
| [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) | Complete specification of the [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) schema and placeholder semantics |
| `bin/omarchy-theme-set-templates` | Bash script that parses [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) and renders all `.tpl` files |
| `shell/Commons/Color.qml` | QML singleton loading [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) for runtime UI |
| [`manual/43-making-your-own-theme.md`](https://github.com/basecamp/omarchy/blob/main/manual/43-making-your-own-theme.md) | User guide for creating custom themes |
| `bin/omarchy-theme-set` | Theme activation orchestrator with [`alacritty.toml`](https://github.com/basecamp/omarchy/blob/main/alacritty.toml) fallback support |
| [`themes/nord/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/nord/colors.toml) | Reference implementation of a full dark palette |

## Summary

- **Single source of truth**: Each Omarchy theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) in `themes/<name>/` defines the complete color palette.
- **Template-driven propagation**: Placeholders in `.tpl` files receive values from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) through `omarchy-theme-set-templates`.
- **Multiple output formats**: Placeholders support hex, stripped hex, RGB, mixed colors, and gradients.
- **Runtime exposure**: The Omarchy shell loads [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) into QML singletons for live UI theming.
- **Legacy compatibility**: The system handles both modern semantic names and legacy abbreviated names.

## Frequently Asked Questions

### What happens if I omit a color in my [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml)?

The Omarchy theming system requires certain core colors (`mode`, `accent`, `background`, `foreground`) for basic operation. Missing optional colors may cause templates to fail rendering or fall back to defaults. Check [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) for the complete required schema, and validate your file by running `omarchy-theme-set-templates` manually to catch errors.

### Can I use [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) values in my own custom templates?

Yes. Place any `.tpl` file in `~/.config/omarchy/themed/` and use standard placeholders like `{{ accent }}` or `{{ mix background foreground 20% }}`. The `omarchy-theme-set-templates` script processes user templates alongside defaults, writing rendered files to `~/.config/omarchy/` without the `.tpl` extension.

### How do I convert an existing terminal theme to Omarchy's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml)?

The `omarchy-theme-set` script includes fallback logic that can generate [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) from an [`alacritty.toml`](https://github.com/basecamp/omarchy/blob/main/alacritty.toml) file if no explicit [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) exists in the theme directory [bin/omarchy-theme-set](https://github.com/basecamp/omarchy/blob/main/quattro/bin/omarchy-theme-set). For manual conversion, map Alacritty's color slots to Omarchy's semantic names: `background`/`foreground` directly, `colors.bright.*` to bright variants, and choose an appropriate `accent` from your palette's primary color.