---

name: omarchy-theming description: Create and manage Omarchy desktop themes. Use when working with colors.toml, terminal themes (Alacritty/Kitty/Ghostty), Hyprland colors, Waybar styling, btop themes, or theme installation/removal.

Omarchy Theme Creation

Create themes for Omarchy by defining colors in colors.toml. Colors automatically propagate to all desktop applications.

Quick Start

1. Create colors.toml with all 22 required variables (see schema below)

2. Add wallpaper images to backgrounds/

3. Apply theme:

   Copyomarchy-theme-set my-theme
   

Instructions

When creating or modifying Omarchy themes:

1. Always define all 22 color variables in colors.toml - missing variables cause errors
2. Use HEX format only (#RRGGBB) - no RGB, HSL, or named colors
3. Include backgrounds/ directory with at least one wallpaper image
4. For light themes, create empty light.mode file in theme directory
5. Test with omarchy-theme-set after changes

For detailed variable usage per application, see reference.md.

Theme Structure

Copy~/.config/omarchy/themes/{theme-name}/
├── colors.toml        # [Required] 22 color definitions
├── backgrounds/       # [Required] Wallpaper images (PNG/JPG)
├── preview.png        # [Recommended] Theme preview
├── icons.theme        # [Recommended] GTK icon theme name
├── neovim.lua         # [Recommended] LazyVim colorscheme
├── vscode.json        # [Recommended] VS Code theme metadata
├── btop.theme         # [Recommended] btop color theme
├── light.mode         # [Optional] Empty file = light theme
├── chromium.theme     # [Optional] Browser theme RGB
└── hyprland.conf      # [Optional] Static Hyprland override

colors.toml Schema

ANSI Normal (8 variables)

color0 = "#45475a" # Black color1 = "#f38ba8" # Red (errors) color2 = "#a6e3a1" # Green (success) color3 = "#f9e2af" # Yellow (warnings) color4 = "#89b4fa" # Blue (links) color5 = "#f5c2e7" # Magenta (special) color6 = "#94e2d5" # Cyan (code) color7 = "#bac2de" # White (text)

ANSI Bright (8 variables)

color8 = "#585b70" # Bright Black (muted/disabled) color9 = "#f38ba8" # Bright Red color10 = "#a6e3a1" # Bright Green color11 = "#f9e2af" # Bright Yellow color12 = "#89b4fa" # Bright Blue color13 = "#f5c2e7" # Bright Magenta color14 = "#94e2d5" # Bright Cyan color15 = "#a6adc8" # Bright White

Copy</schema>

## Template Variables

Each color supports 3 formats for different contexts:

| Format | Example | Output | Use Case |
|--------|---------|--------|----------|
| `{{ name }}` | `{{ accent }}` | `#89b4fa` | CSS, TOML |
| `{{ name_strip }}` | `{{ accent_strip }}` | `89b4fa` | Hyprland `rgb()` |
| `{{ name_rgb }}` | `{{ accent_rgb }}` | `137,180,250` | RGBA values |

## Examples

<example title="Dark Theme (Tokyo Night)">
```toml
accent = "#7aa2f7"
cursor = "#c0caf5"
foreground = "#a9b1d6"
background = "#1a1b26"
selection_foreground = "#c0caf5"
selection_background = "#7aa2f7"

color0 = "#32344a"
color1 = "#f7768e"
color2 = "#9ece6a"
color3 = "#e0af68"
color4 = "#7aa2f7"
color5 = "#ad8ee6"
color6 = "#449dab"
color7 = "#787c99"
color8 = "#444b6a"
color9 = "#ff7a93"
color10 = "#b9f27c"
color11 = "#ff9e64"
color12 = "#7da6ff"
color13 = "#bb9af7"
color14 = "#0db9d7"
color15 = "#acb0d0"

color0 = "#bcc0cc" color1 = "#d20f39" color2 = "#40a02b" color3 = "#df8e1d" color4 = "#1e66f5" color5 = "#ea76cb" color6 = "#179299" color7 = "#5c5f77" color8 = "#acb0be" color9 = "#d20f39" color10 = "#40a02b" color11 = "#df8e1d" color12 = "#1e66f5" color13 = "#ea76cb" color14 = "#179299" color15 = "#6c6f85"

Copy</example>

<example title="neovim.lua">
```lua
return {
    { "folke/tokyonight.nvim", priority = 1000 },
    { "LazyVim/LazyVim", opts = { colorscheme = "tokyonight" } },
}

Theme Commands

Copyomarchy-theme-set my-theme      # Apply theme
omarchy-theme-current           # Show current theme
omarchy-theme-list              # List available themes
omarchy-theme-install <git-url> # Install from git
omarchy-theme-remove my-theme   # Remove theme
omarchy-theme-update            # Update git themes
omarchy-theme-bg-next           # Cycle wallpaper

Troubleshooting

App not themed:

• Place static config in theme folder to override template
• Check variable names match colors.toml keys

yq errors:

Copysudo pacman -S yq