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

Omarchy themes rely on a single 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 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 File Structure

Every Omarchy theme stores its palette in themes/<name>/colors.toml. This file follows a strict schema defined in 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 from the built-in nord theme:

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

The omarchy-theme-set script orchestrates the flow that transforms 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 docs/theming.md#L18-L24.

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.

Step 3: Runtime Consumption

The Omarchy shell loads the generated shell.toml and 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.

Placeholder Syntax for colors.toml Values

Templates use double-brace placeholders to access 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:

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

Color Mixing

The mix helper blends two palette entries by percentage:

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

Gradient Generation

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

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

If hyprland_active_border exists in 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.

Creating a Custom colors.toml

To build your own Omarchy theme, create a new directory under themes/ with a minimal colors.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, then activate with:

omarchy-theme-set my-light

The script immediately processes your 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.

Key Implementation Files

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

Summary

• Single source of truth: Each Omarchy theme's colors.toml in themes/<name>/ defines the complete color palette.
• Template-driven propagation: Placeholders in .tpl files receive values from 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 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?

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 for the complete required schema, and validate your file by running omarchy-theme-set-templates manually to catch errors.

Can I use 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?

The omarchy-theme-set script includes fallback logic that can generate colors.toml from an alacritty.toml file if no explicit colors.toml exists in the theme directory 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.

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