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

The 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 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 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, 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, if a theme lacks a 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:

1. Stage the theme: Copy the selected theme's directory (themes/<name>/) into a staging area.
2. Load the palette: Parse the 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.
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 propagates consistently across all generated configuration files.

Template Substitution and Color Functions

During the rendering phase, the theming engine processes colors.toml values through a template syntax that supports various formatting helpers.

Basic Placeholder Substitution

Reference any key from colors.toml using double braces:

# 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 (for example, #6e6e6e).

Stripped Values and RGB Components

For contexts requiring different color formats, use suffixes:

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

{{ 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:

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 values are exposed to the running desktop environment through the Color singleton. QML components can access the active palette directly:

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 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 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 at runtime.

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