# Omarchy Theming Architecture Components: A Complete Technical Guide

> Explore Omarchy's theming architecture components including theme directories, color palettes, template files, and runtime hooks to create unified desktop themes.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: architecture
- Published: 2026-09-03

---

**Omarchy's theming architecture consists of theme directories, a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) palette, template files, generated configs, runtime hooks, and a QML border API that work together to produce a unified desktop theme.**

Omarchy's theming system is built around a clear hierarchy of files and runtime steps that transform a simple color palette into a fully featured desktop environment. This architecture enables single-source color management, user-level customization, and safe third-party theme installation. Understanding these components helps developers and power users customize their Omarchy installation effectively.

## Theme Directories and Storage Locations

Themes reside in two distinct locations based on ownership and scope.

**System themes** live under `/usr/share/omarchy/themes/` with individual themes in subdirectories like `themes/<name>/`. These ship with Omarchy and serve as the foundation for all theme operations.

**User themes** occupy `~/.config/omarchy/themes/<name>/`. This directory allows personal themes and overrides without modifying system files. The separation ensures upgrades preserve customizations.

According to the Omarchy source code at [[`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md)](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L3-L5), this dual-path design enables overlay-based theme construction where user files augment or replace system defaults.

## The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) Color Palette

The **canonical color definition file** sits at the heart of every theme. The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file defines semantic keys that all templates consume:

- `accent` — primary interactive color
- `background` — main surface color
- `foreground` — text and icon color
- Additional semantic keys for specific UI roles

This single source of truth eliminates color drift across components. When a theme author updates `accent`, every template referencing `{{ accent }}` receives the new value upon regeneration.

The palette structure is documented in [[`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md)](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L68-L93) and serves as the input for all downstream template rendering.

## Template Files and Rendering Engine

Templates are plain-text files containing `{{ key }}` placeholders that the rendering engine substitutes with values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml).

**Built-in templates** reside in `default/themed/*.tpl`. These ship with Omarchy and cover core components:

| Template | Output |
|----------|--------|
| `shell.toml.tpl` | [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) for shell configuration |
| `hyprland.lua.tpl` | [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) for window manager settings |

**User templates** can be added to `~/.config/omarchy/themed/*.tpl` for custom components. This extensibility allows third-party applications to participate in the theming system without modifying core files.

The `omarchy-theme-set-templates` command performs the actual rendering, as referenced in [`bin/omarchy-theme-set-templates`](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L31-L35).

## Generated Configuration Files

Template rendering produces concrete configuration files that applications consume directly:

- [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) — shell appearance and behavior
- [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) — Hyprland window manager theming
- Terminal emulator configs (colormaps and cursor styles)
- Editor configurations (VS Code [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json))

**Hand-written overrides** bypass the template system entirely. Files like [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) replace specific sections of generated output. This hybrid approach supports complex cases where template logic proves insufficient.

The generation process and override behavior are detailed in [[`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md)](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L78-L88).

## Additional Theme Assets

Themes optionally bundle visual and input resources:

- `backgrounds/` — wallpaper images
- `preview.png` — thumbnail for theme selectors
- `icons.theme` — icon theme reference
- `keyboard.rgb` — keyboard LED color profiles
- `unlock.png` — lock screen background
- `light.mode` marker — indicates light theme variant

These files are copied or symlinked into the active theme location during activation. Their presence is optional; themes function with only [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and templates.

## Theme Activation Flow

The `omarchy-theme-set <name>` command orchestrates theme application through five distinct stages:

1. **Stage** — Create clean directory at `~/.local/state/omarchy/current/next-theme`
2. **Overlay** — Copy system theme, then apply user override files
3. **Generate** — Produce [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) from terminal configs if palette missing
4. **Render** — Execute `omarchy-theme-set-templates` to process all `*.tpl` files
5. **Activate** — Move result to active location and trigger `theme-set` hook

This atomic staging prevents partial theme application. If any stage fails, the current theme remains intact.

The complete flow is implemented in [`bin/omarchy-theme-set`](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L18-L30).

## Runtime Hooks for Live Application

After activation, Omarchy executes **hook scripts** matching `~/.config/omarchy/hooks/theme-set*`. These scripts propagate theme changes to running applications:

- Restart compositor or shell components
- Send retint signals to supported applications
- Update status bars and notification daemons

The hook system decouples theming from application-specific update logic. Application maintainers provide hooks rather than modifying core theme code.

Hook conventions are documented in [[`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md)](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L40-L45).

## QML Border API for Shell Rendering

The **QML border API** provides programmatic access to theme-aware border specifications:

- `Border.surfaceSpec` — borders for background surfaces
- `Border.controlSpec` — borders for interactive controls
- `Border.flat` — flat style indicator

These specifications respect the active palette, producing solid colors or gradients derived from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). Shell code uses these APIs rather than hardcoding colors, ensuring visual consistency.

The API surface is described in [[`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md)](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L22-L25).

## Security: Theme Installation Denylist

Omarchy implements **defensive filtering** when installing themes from remote git repositories. The `INSTALLED_THEME_DENIED` logic in `bin/omarchy-theme-set` restricts which files enter the staging directory:

- **Allowed**: `*.lua`, terminal configs, [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json), symlinks
- **Denied**: All other files, especially executable scripts

This security boundary ensures that [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and templates remain the only inputs to generated configs. Malicious themes cannot inject arbitrary code—only color values and template logic execute.

The denylist implementation appears in [[`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md)](https://github.com/omacom/omarchy/blob/quattro/docs/theming.md#L48-L60).

## Practical Usage Examples

Activate a built-in theme:

```bash
omarchy-theme-set catppuccin

```

Re-render templates after manual [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) edit:

```bash
omarchy-theme-set-templates

```

Create a custom lock screen override:

```bash
cat > ~/.config/omarchy/themes/mytheme/shell.lock.toml <<'EOF'
text        = "#ffffff"
placeholder = "#444444"
border      = "#ff00ff"
EOF
omarchy-theme-set mytheme

```

## Key Files in the Architecture

| Path | Purpose |
|------|---------|
| [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) | Comprehensive design documentation |
| `bin/omarchy-theme-set` | Core theme activation command |
| `bin/omarchy-theme-set-templates` | Template rendering engine |
| `default/themed/*.tpl` | Built-in template collection |
| `themes/*/colors.toml` | Built-in theme palettes |
| `~/.config/omarchy/hooks/theme-set*` | Post-activation hook scripts |

## Summary

- **Single source of truth**: [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) centralizes all color definitions
- **Template-driven generation**: `*.tpl` files produce consistent configs across components
- **User overlay system**: Personal themes extend system defaults without modification
- **Atomic activation**: Five-stage `omarchy-theme-set` flow prevents partial states
- **Hook-based propagation**: Runtime scripts update running applications
- **Security boundaries**: Installation denylist blocks executable code from remote themes

## Frequently Asked Questions

### How do I create a custom Omarchy theme from scratch?

Create a directory at `~/.config/omarchy/themes/yourname/` containing [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) with your palette and any template overrides in `themed/*.tpl`. Run `omarchy-theme-set yourname` to activate. The command copies your files over the system defaults, renders templates, and fires hooks.

### Why does Omarchy use templates instead of direct config files?

Templates ensure **color consistency** across dozens of configuration files. When `accent` changes in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), every template referencing `{{ accent }}` updates automatically. Without templates, manual synchronization across shell, terminal, editor, and WM configs would be error-prone.

### What happens if I edit a generated file directly?

Direct edits to generated files like [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) are **overwritten on next theme activation**. Persist changes by creating an override file (e.g., [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml)) or modifying the source template. The [`.lock.toml`](https://github.com/omacom/omarchy/blob/main/.lock.toml) suffix signals Omarchy to use your version instead of the generated one.

### Can I use themes from untrusted Git repositories safely?

Yes, within limits. The `INSTALLED_THEME_DENIED` filter in `bin/omarchy-theme-set` strips all files except `*.lua`, terminal configs, [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json), and symlinks. Executable scripts and arbitrary binaries never reach the staging directory. However, review [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and templates for malicious Lua code before activation.