# How Theming Is Managed in Omarchy > Discover how Omarchy manages theming using a decoupled architecture. Learn about TOML color definitions, QML templates, and CLI commands for active desktop configuration. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: internals - Published: 2026-08-21 --- **Omarchy manages theming through a decoupled architecture where TOML-based color definitions in `themes/*/colors.toml` are injected into QML template files using `{{ variable }}` placeholders, then processed by CLI commands like `omarchy-theme-set-templates` and `omarchy-theme-apply` to generate the active desktop configuration.** The open-source Omarchy desktop environment by Basecamp implements a strict separation between theme data and presentation logic. According to the basecamp/omarchy source code, the theming system relies on plain-text configuration files and template processing to render user-specific desktop environments without requiring direct QML manipulation. ## Core Architecture of Omarchy Themes Omarchy's theming system consists of four primary components that operate together to render the final desktop appearance. ### Color Definitions in TOML Theme palettes are defined in plain-text TOML files located at `themes/*/colors.toml` within the repository. These files specify the complete color palette including accent colors, background, foreground, and the full spectrum of bright and muted variants. For example, the bundled Catppuccin theme stores its palette in [`themes/catppuccin/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/catppuccin/colors.toml). ### Template Files with Variable Placeholders Presentation logic resides in `default/themed/*.tpl` files containing QML or other markup snippets with `{{ variable }}` placeholders. These templates serve as blueprints that get populated with color values during the rendering process. The separation allows the same structural templates to generate different visual appearances based solely on the TOML color data. ### Runtime Helper Commands The system provides specific CLI utilities to process and activate themes: - **`omarchy-theme-set-templates`**: Reads a theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) and substitutes values into all `*.tpl` files under `default/themed/`, writing the rendered output to the user config directory. - **`omarchy-theme-apply`**: Activates the rendered theme in the running desktop environment and signals the shell to reload its configuration. - **`omarchy-theme-set-colors`**: Directly updates color values in the active configuration without reprocessing templates. - **`omarchy-theme-list`**: Displays available themes containing valid [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) files. ### User-Level Configuration and Assets Rendered themes and user overrides are stored in `~/.config/omarchy/themes//`. Users may override any theme component by placing modified files in the corresponding relative path within their home directory. Additionally, themes may bundle optional `themes/*/background.png` images for desktop backgrounds or custom fonts referenced in [`default/fonts/omarchy/README.md`](https://github.com/basecamp/omarchy/blob/main/default/fonts/omarchy/README.md). ## Theming Workflow and Template Rendering The process of applying or creating themes follows a predictable pipeline that bridges the gap between source definitions and the running desktop environment. First, the system locates the theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file. Then `omarchy-theme-set-templates ` processes every `*.tpl` template in `default/themed/`, replacing `{{ variable }}` placeholders with corresponding hex values from the TOML file. Finally, `omarchy-theme-apply ` copies these rendered files into `~/.config/omarchy/` and refreshes the UI. ## Creating and Customizing Omarchy Themes You can create custom themes by duplicating an existing color definition and modifying the values, then regenerating the templates. ```bash # List all available themes with valid colors.toml files omarchy-theme-list # Apply the built-in catppuccin theme immediately omarchy-theme-apply catppuccin # Create a custom theme called "my-dark" mkdir -p ~/.config/omarchy/themes/my-dark cp ~/.config/omarchy/themes/catppuccin/colors.toml \ ~/.config/omarchy/themes/my-dark/ # Edit the color values to your preference nano ~/.config/omarchy/themes/my-dark/colors.toml # Render templates with your new color values omarchy-theme-set-templates my-dark # Apply the rendered theme to the desktop omarchy-theme-apply my-dark ``` ## Key Source Files and Documentation Several files in the basecamp/omarchy repository define and document this behavior: - **[`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md)**: Comprehensive documentation of the theme/template workflow. - **[`default/agents/skills/omarchy/theming.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/theming.md)**: Concrete step-by-step instructions for theme creation and customization. - **[`default/agents/skills/omarchy/SKILL.md`](https://github.com/basecamp/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md)**: References theming documentation as a core system skill. - **[`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md)**: Documents the helper commands including `omarchy-theme-set-templates` and `omarchy-theme-apply`. - **`default/themed/*.tpl`**: Source template files containing the `{{ variable }}` placeholder syntax. - **`themes/*/colors.toml`**: Canonical color definitions for all bundled themes. ## Summary - **TOML-based palettes**: Colors are defined in `themes/*/colors.toml` files separate from presentation code. - **Template injection**: The `*.tpl` files in `default/themed/` use `{{ variable }}` syntax to receive color values dynamically. - **CLI-driven workflow**: Commands like `omarchy-theme-set-templates` and `omarchy-theme-apply` handle rendering and activation without manual file copying. - **User overrides**: Customizations belong in `~/.config/omarchy/themes/` and take precedence over system defaults. - **Asset support**: Themes can bundle backgrounds at `themes/*/background.png` and custom font configurations. ## Frequently Asked Questions ### Where are theme colors defined in Omarchy? Theme colors are defined in plain-text TOML files located at `themes/*/colors.toml` in the repository, or `~/.config/omarchy/themes//colors.toml` for user themes. Each file contains hex color values for accents, backgrounds, foregrounds, and bright/muted variants. ### How do I apply a custom theme without editing QML files? Run `omarchy-theme-set-templates ` to process the QML templates with your color definitions, then execute `omarchy-theme-apply ` to activate it. This workflow injects TOML values into the `{{ variable }}` placeholders automatically, requiring no manual QML editing. ### What is the purpose of the *.tpl files in the default/themed directory? These files contain markup templates with placeholder variables like `{{ accent }}` or `{{ background }}`. The `omarchy-theme-set-templates` command renders these into final configuration files by substituting placeholders with values from the active theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml), as documented in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md). ### Can I override specific theme components for my user only? Yes. Place modified files in `~/.config/omarchy/themes//` following the same relative paths as the source repository. The system prioritizes user-level configurations in `~/.config/omarchy/`, allowing you to override colors, fonts, or individual templates without affecting the system-wide installation.