# Omarchy Theme Template Placeholders: Complete Guide to {{ accent }} and All Color Variables

> Discover Omarchy theme template placeholders like {{ accent }} and color variables. Learn how these are substituted with hex colors from colors.toml for custom theme building.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-20

---

**Omarchy themes use template placeholders like `{{ accent }}`, `{{ background }}`, and `{{ foreground }}` in `*.tpl` files, which are substituted with hex color values from `themes/*/colors.toml` files during the build process.**

Omarchy's theming system is built around a straightforward template substitution engine. When you customize an Omarchy theme, you're working with `*.tpl` files in `default/themed/` that contain placeholder variables. These placeholders map directly to keys in [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) files, enabling consistent color application across VS Code, terminal emulators, and window compositor configurations.

## Core Template Placeholders in Omarchy

Omarchy defines **18 base color placeholders** that every theme must provide in its [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml). These are the foundation of all theme customization.

### Semantic Color Placeholders

These placeholders control the primary visual hierarchy of Omarchy themes:

| Placeholder | Purpose | Typical Usage |
|-------------|---------|-------------|
| `{{ accent }}` | Primary accent color | Highlights, borders, active elements, buttons |
| `{{ background }}` | General background | Window backgrounds, panels, base surfaces |
| `{{ foreground }}` | Default text color | Primary text, icons, labels |
| `{{ muted }}` | Dimmed secondary text | Disabled states, captions, metadata |
| `{{ selection_background }}` | Selected item highlight | Text selection, list selection, active tabs |
| `{{ theme_type }}` | Theme kind identifier | `"dark"` or `"light"` for conditional logic |
| `{{ dark_foreground }}` | Dark variant of foreground | Specialized contrast scenarios |

### ANSI-Style Color Placeholders

These map to standard terminal color slots and semantic meanings:

- `{{ red }}` — Errors, danger states, deletion indicators
- `{{ green }}` — Success states, additions, confirmations
- `{{ blue }}` — Information, links, primary actions
- `{{ cyan }}` — Auxiliary information, regex highlights
- `{{ magenta }}` — Special keywords, magenta-tinted elements
- `{{ yellow }}` — Warnings, highlights, attention items
- `{{ orange }}` — Orange-tinted warnings, secondary alerts

### Bright Variant Placeholders

Each base hue has a bright counterpart for emphasized states:

- `{{ bright_red }}`, `{{ bright_green }}`, `{{ bright_blue }}`
- `{{ bright_cyan }}`, `{{ bright_magenta }}`, `{{ bright_yellow }}`

Bright variants are commonly used for **hover states** and **active selections**. For example, `{{ bright_blue }}` often defines link hover colors in VS Code themes, while `{{ bright_cyan }}` highlights regular expression matches.

## Opacity Modifiers: Hex + Suffix Pattern

Omarchy's template engine supports **opacity modifiers** by appending two-digit hex suffixes directly to placeholder names. This creates semi-transparent variants without requiring additional color definitions.

| Pattern | Result | Example Output |
|---------|--------|--------------|
| `{{ accent }}80` | 50% opacity accent | `#ff6f0080` |
| `{{ accent }}40` | 25% opacity accent | `#ff6f0040` |
| `{{ accent }}20` | ~12% opacity accent | `#ff6f0020` |
| `{{ background }}80` | 50% opacity background | `#ffffff80` |
| `{{ muted }}80` | 50% opacity muted | `#77777780` |
| `{{ muted }}40` | 25% opacity muted | `#77777740` |

The suffix is **concatenated literally**—the engine reads the base hex from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) and appends the modifier. This occurs in templates like `default/themed/vscode-theme.json.tpl` for focus borders, hover backgrounds, and subtle separators.

## How Placeholders Resolve: Build-Time Substitution

Understanding the resolution pipeline helps debug theme issues.

### Step 1: Template Files Reference Placeholders

Templates in `default/themed/` use Mustache-style syntax. From `default/themed/vscode-theme.json.tpl`:

```json
{
  "button": {
    "background": "{{ accent }}",
    "foreground": "{{ background }}",
    "border": "{{ accent }}20"
  }
}

```

### Step 2: Color Values Defined in TOML

Each theme directory contains [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml). From [`themes/white/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml):

```toml
accent = "#ff6f00"
background = "#ffffff"
foreground = "#265b6d"
muted = "#6d7e83"
selection_background = "#ffdcae"
red = "#e70000"
green = "#008800"
blue = "#0052d6"
cyan = "#00afcb"
magenta = "#d300d8"
yellow = "#f4cc00"
orange = "#d65b00"
theme_type = "light"

```

### Step 3: Substitution Produces Final Config

The build engine replaces placeholders and concatenates opacity suffixes:

```json
{
  "button": {
    "background": "#ff6f00",
    "foreground": "#ffffff",
    "border": "#ff6f0020"
  }
}

```

## Practical Code Examples

### Creating a Custom Theme with New Colors

Define colors in [`themes/my-theme/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/my-theme/colors.toml):

```toml
accent = "#4a90e2"
background = "#1e1e1e"
foreground = "#d0d0d0"
muted = "#777777"
selection_background = "#264f78"
red = "#f48771"
green = "#89d185"
blue = "#569cd6"
cyan = "#9cdcfe"
magenta = "#c586c0"
yellow = "#dcdcaa"
orange = "#ce9178"
theme_type = "dark"

```

All templates referencing `{{ accent }}`, `{{ background }}`, and other keys automatically adopt these values.

### Using Opaque Colors for Subtle Effects

From `default/themed/vscode-theme.json.tpl`, focus indicators use partial opacity:

```json
{
  "focusBorder": "{{ accent }}80",
  "selection.background": "{{ selection_background }}80",
  "inputOption.activeBackground": "{{ accent }}40"
}

```

This produces `#4a90e280`, `#264f7880`, and `#4a90e240` respectively—visible but not overwhelming.

### Terminal Template with ANSI Mapping

From `default/themed/kitty.conf.tpl`:

```

foreground            {{ foreground }}
background            {{ background }}
selection_foreground  {{ background }}
selection_background  {{ selection_background }}
color0                {{ background }}
color1                {{ red }}
color2                {{ green }}
color4                {{ blue }}
color6                {{ cyan }}
color9                {{ bright_red }}
color10               {{ bright_green }}
color12               {{ bright_blue }}
color14               {{ bright_cyan }}

```

## Key Source Files for Placeholder Reference

| File Path | Description |
|-----------|-------------|
| `default/themed/vscode-theme.json.tpl` | Most comprehensive placeholder usage; defines VS Code UI and syntax tokens |
| `default/themed/hyprland.lua.tpl` | Window compositor colors using semantic placeholders |
| `default/themed/kitty.conf.tpl` | Kitty terminal configuration with full ANSI mapping |
| `default/themed/foot.ini.tpl` | Foot terminal configuration |
| [`themes/white/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml) | Reference light theme with complete color set |
| [`themes/black/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/black/colors.toml) | Reference dark theme with complete color set |

To discover all placeholders used in your Omarchy installation, search template files: `grep -oE '\{\{ [a-z_]+ \}\}' default/themed/*.tpl | sort -u`.

## Summary

- **18 base placeholders** define Omarchy's color system: semantic colors (6), ANSI hues (7), bright variants (7), plus `{{ theme_type }}`
- **Opacity modifiers** append two-digit hex suffixes (`80`, `40`, `20`) directly to any color placeholder
- **Resolution is build-time**: templates in `default/themed/*.tpl` consume `themes/*/colors.toml` values
- **Pattern is extensible**: adding new keys to [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) creates new usable placeholders automatically
- **Key files**: `vscode-theme.json.tpl` demonstrates most placeholders; `hyprland.lua.tpl`, `kitty.conf.tpl`, and `foot.ini.tpl` show cross-application theming

## Frequently Asked Questions

### What happens if a placeholder is missing from my colors.toml?

Omarchy's template engine will fail to substitute the undefined placeholder, leaving the literal `{{ placeholder_name }}` string in the output file. Always verify your [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) contains all keys referenced by templates you intend to use. Compare against [`themes/white/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml) or [`themes/black/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/black/colors.toml) for the complete required set.

### Can I create custom placeholders beyond the standard set?

Yes. The template system treats any key in [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) as a valid placeholder. Adding `custom_highlight = "#ff00ff"` to your [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) enables `{{ custom_highlight }}` in templates. However, custom placeholders won't be recognized by default Omarchy templates unless you modify those `*.tpl` files directly.

### How do transparency values work with the hex suffix pattern?

The suffix is appended as a raw string. For `accent = "#4a90e2"`, the template `{{ accent }}80` becomes `#4a90e280`—standard 8-digit hex RGBA where the last two digits represent alpha (80 = 128/255 ≈ 50% opacity, 40 = 64/255 ≈ 25%, 20 = 32/255 ≈ 12.5%). This matches CSS hex color syntax and is parsed accordingly by target applications like VS Code and Kitty.

### Where is the template substitution code located?

The placeholder resolution logic is implemented in Omarchy's build scripts that process `default/themed/*.tpl` files. These scripts read the selected theme's [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) and perform simple key-to-value replacement before writing final configuration files to their respective application directories.