What Files Define a Theme in Omarchy? A Complete Technical Guide

Omarchy themes are defined by TOML palette files located in themes/<name>/colors.toml that declare RGBA/hex color values, and template files in default/themed/ that interpolate those values into application-specific configurations.

Omarchy is a desktop environment configuration system created by Basecamp that manages dotfiles and consistent theming across Linux applications. Understanding what files define a theme in Omarchy is essential for customizing your desktop appearance or developing custom themes. The architecture cleanly separates color definitions from configuration templates, enabling synchronized theming across Alacritty, Hyprland, VS Code, and other supported components.

The Two Core Components of an Omarchy Theme

An Omarchy theme consists of two distinct file types that work together during the theme application process.

Palette Definition Files

The palette is the source of truth for all color values. Each theme lives in its own subdirectory under themes/ and contains a colors.toml file that declares the full color palette used by the rest of the system.

Key characteristics:

• Located at themes/<theme-name>/colors.toml
• Defines colors as RGBA/hex values (foreground, background, accent, etc.)
• Examples include themes/nord/colors.toml, themes/catppuccin/colors.toml, and themes/white/colors.toml

Component Template Files

The templates consume the palette values and generate concrete configuration files. These reside in default/themed/ and use various templating formats to produce application-ready configs.

Key characteristics:

• Located in default/themed/ with extensions like .tpl or .tmpl
• Support multiple formats including QML, INI, Lua, and JSON
• Files include alacritty.toml.tpl, hyprland.lua.tpl, vscode-theme.json.tpl, kitty.conf.tpl, and foot.ini.tpl

Palette Files: The Color Source of Truth

Every Omarchy theme begins with a colors.toml file. When you select a theme, helper scripts read this file to extract the color definitions.

For example, the Nord theme defines its colors in themes/nord/colors.toml:

background = "#2E3440"
foreground = "#D8DEE9"
accent     = "#88C0D0"

These values provide the raw data that template engines substitute into configuration placeholders. The repository includes palette files for multiple built-in themes including themes/white/colors.toml, themes/kanagawa/colors.toml, and themes/catppuccin/colors.toml.

Template Files: Rendering Colors to Application Configs

Templates in default/themed/ contain the structural logic for each application but use placeholder variables for colors. When omarchy-theme-set executes, it renders these templates using the active palette's values.

Important template files include:

• default/themed/alacritty.toml.tpl — Terminal emulator configuration
• default/themed/hyprland.lua.tpl — Window manager configuration
• default/themed/vscode-theme.json.tpl — Editor color scheme
• default/themed/kitty.conf.tpl — Alternative terminal configuration
• default/themed/foot.ini.tpl — Wayland terminal configuration

These templates generate final configuration files in the user's $HOME/.config/ directory hierarchy.

How Theme Application Works

When you execute the theme switch command, Omarchy follows a specific pipeline to apply the theme.

The omarchy-theme-set command performs three operations:

1. Loads the selected theme's colors.toml from the themes/ directory
2. Renders all templates in default/themed/ by interpolating color values into placeholders
3. Writes the generated configuration files to appropriate locations in ~/.config/

You can trigger this process manually:

omarchy-theme-set nord

This command reads themes/nord/colors.toml, processes all templates in default/themed/, and outputs concrete config files for Alacritty, Hyprland, and other supported applications.

Listing and Inspecting Available Themes

Before applying a theme, you can view available options using the list command:

omarchy-theme-list

# → white, nord, catppuccin, kanagawa, ...

To inspect a theme's specific color definitions without applying it:

cat "$(omarchy-theme-dir)/nord/colors.toml"

For debugging or manual template rendering, use the specific template command:

omarchy-theme-set-tpl \
  --theme nord \
  --template default/themed/alacritty.toml.tpl \
  --output ~/.config/alacritty/alacritty.toml

Summary

• Palette files (themes/<theme-name>/colors.toml) define color values using TOML format with hex or RGBA declarations
• Template files (default/themed/*.tpl) consume palette values and generate application-specific configurations
• The omarchy-theme-set command orchestrates the rendering process, reading palettes and writing final configs to ~/.config/
• Template files exist for major components including Alacritty, Hyprland, VS Code, Kitty, and Foot
• Changing a colors.toml file or its associated templates affects the rendered output the next time the theme is applied

Frequently Asked Questions

What is the main file that defines an Omarchy theme color palette?

The main file is themes/<theme-name>/colors.toml. This TOML file contains the complete color definition including foreground, background, and accent colors used throughout the system. Each theme has its own subdirectory under themes/ containing this specific file.

Where are Omarchy theme templates stored?

Theme templates are stored in the default/themed/ directory. These files use extensions like .tpl or .tmpl and include formats such as alacritty.toml.tpl, hyprland.lua.tpl, and vscode-theme.json.tpl. They serve as blueprints that get populated with color values from the active palette.

How do I create a custom theme in Omarchy?

To create a custom Omarchy theme, create a new subdirectory under themes/ (e.g., themes/mycustom/) and add a colors.toml file with your color definitions. The file should declare colors as hex values for properties like background, foreground, and accent. Once created, run omarchy-theme-set mycustom to apply it.

Why does Omarchy separate palettes from templates?

Omarchy separates palettes from templates to maintain DRY (Don't Repeat Yourself) principles and ensure consistency. By defining colors once in a palette file and referencing them across multiple application templates, changing a single color value updates every application configuration simultaneously. This architecture prevents configuration drift across Alacritty, Hyprland, VS Code, and other supported tools.

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