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

> Discover the Omarchy files defining themes: TOML palette files and default themed template files. Learn how they interpolate RGBA hex color values for configurations. Get the complete technical guide.

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

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/themes/nord/colors.toml), [`themes/catppuccin/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/catppuccin/colors.toml), and [`themes/white/colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/themes/nord/colors.toml):

```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`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml), [`themes/kanagawa/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/kanagawa/colors.toml), and [`themes/catppuccin/colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
omarchy-theme-set nord

```

This command reads [`themes/nord/colors.toml`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
omarchy-theme-list

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

```

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

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

```

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

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.