Omarchy Color Tokens: Complete Reference for Theme Customization

TLDR: Omarchy themes rely on a standardized colors.toml file that exposes a fixed set of color tokens—including background, foreground, accent, and ANSI palette values—that Hyprland, BTOP, and Neovim consume to maintain consistent visual styling across the desktop environment.

Omarchy, the declarative Linux desktop environment maintained by Basecamp, centralizes theme configuration through a token-based color architecture. Each theme directory contains a colors.toml file that defines a canonical set of color tokens, ensuring uniform aesthetics across window managers, terminals, and editors. Understanding these tokens is essential for customizing existing themes or creating new ones in the basecamp/omarchy repository.

Understanding the colors.toml Architecture

In Omarchy, color tokens are defined in TOML format within each theme's directory. The file themes/<theme>/colors.toml serves as the single source of truth for all color values in that theme. For example, the Catppuccin theme implementation stores its palette in themes/catppuccin/colors.toml.

This architecture ensures that color tokens remain consistent across the entire desktop environment. Each token represents a specific semantic color role, and applications reference these keys rather than hardcoding HEX values. When you switch themes, the underlying token names remain identical—only their assigned values change.

Complete List of Omarchy Color Tokens

The Omarchy color system exposes a comprehensive palette divided into functional groups. All themes must define these tokens to ensure compatibility with Hyprland, BTOP, and Neovim configurations.

Base Interface Tokens

These three tokens control the primary visual foundation of the desktop environment:

• background – The main background color for windows, terminals, and panels.
• foreground – The primary text color used in UI elements and terminal text.
• accent – The highlight color for selections, active indicators, and emphasized interface elements.

Standard ANSI Color Palette

Omarchy defines the standard 8-color terminal palette used by console applications:

• black
• red
• green
• yellow
• blue
• magenta
• cyan

These tokens map directly to ANSI color codes in terminal emulators and TTY interfaces.

Bright Color Variants

For high-intensity terminal colors and secondary UI highlights, Omarchy includes bright variants:

• bright_black
• bright_red
• bright_green
• bright_yellow
• bright_blue
• bright_magenta
• bright_cyan
• bright_white

These bright tokens provide contrast for bold text, highlighted search results, and distinct UI categories in system monitors.

Window Border Colors

Hyprland window decorations consume two specific tokens for border styling:

• active_border_color – The border color for the currently focused window.
• inactive_border_color – The border color for unfocused windows.

These tokens are referenced in themes/<theme>/hyprland.lua to maintain consistent window management aesthetics.

How Omarchy Applications Consume Color Tokens

Omarchy's modular configuration system allows different applications to ingest the same colors.toml tokens through specialized loader files. Each application translates these abstract tokens into application-specific color formats.

Hyprland Window Borders

The Hyprland compositor configuration in themes/<theme>/hyprland.lua reads active_border_color and inactive_border_color to style window borders. These values are typically rendered as RGBA strings for gradient and transparency support.

-- Example: Using a theme token in a Hyprland config (lua)
local active_border_color = { colors = { "rgba(8a8588ee)", "rgba(e2dddcee)" }, angle = 45 }
local inactive_border_color = "rgba(584e51aa)"

BTOP System Monitor

BTOP themes in themes/<theme>/btop.theme reference the base palette tokens to colorize CPU graphs, memory usage bars, and network statistics. The configuration uses variable substitution to map Omarchy tokens to BTOP's internal color scheme.

# Example: Referencing tokens in a BTOP theme file

foreground = "$foreground"
background = "$background"
red = "$red"
green = "$green"

Neovim Editor

Neovim configurations in themes/<theme>/neovim.lua set the background mode and inject accent colors into Vim globals. This allows the editor to synchronize its colorscheme with the desktop environment's active theme.

" Example: Setting Neovim colors based on a theme token
let g:omarchy_accent = get(g:omarchy_theme, "accent", "#ff00ff")
colorscheme catppuccin

Summary

• Omarchy themes define color tokens in themes/<theme>/colors.toml, with each theme supplying HEX values for a standardized set of keys.
• The token set includes base colors (background, foreground, accent), ANSI palette (black through cyan), bright variants, and border colors (active_border_color, inactive_border_color).
• Hyprland consumes border color tokens via themes/<theme>/hyprland.lua to render window decorations.
• BTOP references the ANSI palette through themes/<theme>/btop.theme for system monitor visualization.
• Neovim loads theme tokens via themes/<theme>/neovim.lua to synchronize editor colors with the desktop environment.

Frequently Asked Questions

Where are color tokens defined in Omarchy?

Color tokens are defined in the colors.toml file located within each theme directory (e.g., themes/catppuccin/colors.toml). This file contains the complete palette mapping for that specific theme, using standard TOML key-value pairs where keys are token names and values are HEX color codes.

How do I customize window border colors in Omarchy themes?

Modify the active_border_color and inactive_border_color values in your theme's colors.toml file. Hyprland automatically reads these tokens through themes/<theme>/hyprland.lua and applies them to window borders, supporting both solid colors and RGBA gradients.

Are color token names consistent across all Omarchy themes?

Yes. Every Omarchy theme uses the identical set of token names (background, foreground, accent, red, bright_red, etc.) defined in the color architecture. When switching themes, the token names remain constant while their assigned HEX values change, ensuring all applications update their appearance simultaneously.

Which applications support Omarchy's color token system?

The core Omarchy integration supports Hyprland (window borders), BTOP (system monitor), and Neovim (text editor) through dedicated configuration files: hyprland.lua, btop.theme, and neovim.lua respectively. Each file resides in the theme directory and translates the abstract colors.toml tokens into application-specific color formats.

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