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

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 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. 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 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:

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

Step 2: Color Values Defined in TOML

Each theme directory contains colors.toml. From themes/white/colors.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:

{
  "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:

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:

{
  "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	Reference light theme with complete color set
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 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 contains all keys referenced by templates you intend to use. Compare against themes/white/colors.toml or 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 as a valid placeholder. Adding custom_highlight = "#ff00ff" to your 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 and perform simple key-to-value replacement before writing final configuration files to their respective application directories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}