How the Omarchy Theming System Uses TOML for Color Definitions

Omarchy stores theme color palettes in colors.toml files within each theme directory, which the omarchy-theme-set command reads to propagate color values consistently across the desktop environment, terminal emulators, and UI components.

The Omarchy desktop environment from Basecamp uses a declarative approach to theming where color definitions live in structured TOML files. Each theme directory contains a colors.toml file that serves as the single source of truth for all visual styling, from UI widgets to terminal emulator palettes.

Structure of the colors.toml File

The TOML file uses simple key-value pairs to define the color scheme. Located at themes/<theme-name>/colors.toml, this file specifies both the theme mode and the hexadecimal color values for every UI element.

Key fields include:

• mode: Specifies "light" or "dark" to guide contrast calculations
• accent: Primary interaction color
• background/foreground: Base colors with variants (dark_background, light_foreground, etc.)
• Semantic colors: red, yellow, green, cyan, blue, magenta and their bright variants

Example from the white theme located at themes/white/colors.toml:

mode = "light"

accent = "#6e6e6e"
selection = "#c0c0c0"
muted = "#808080"

background = "#ffffff"
dark_background = "#f5f5f5"
darker_background = "#e8e8e8"
lighter_background = "#c0c0c0"

foreground = "#000000"
dark_foreground = "#c0c0c0"
light_foreground = "#000000"
bright_foreground = "#000000"

red = "#2a2a2a"
yellow = "#4a4a4a"
green = "#3a3a3a"
cyan = "#3e3e3e"
blue = "#1a1a1a"
magenta = "#2e2e2e"

bright_red = "#2a2a2a"
bright_yellow = "#4a4a4a"
bright_green = "#3a3a3a"
bright_cyan = "#3e3e3e"
bright_blue = "#1a1a1a"
bright_magenta = "#2e2e2e"

Loading and Applying Color Definitions

When you activate a theme, the system follows a specific pipeline to move colors from the TOML definition to active use.

Parsing the TOML Palette

The omarchy-theme-set command, located in bin/omarchy-theme-set, serves as the entry point. It reads the specified theme's colors.toml file and parses the key-value pairs to extract the complete palette for system-wide application.

Staging and Verification

Before full system application, the theme enters a staging phase. The test suite in test/shell.d/theme-staging-test.sh demonstrates this process using the write_colors function to copy the TOML file to a staging area accessed via the staged helper.

The test verifies correct staging by checking for specific hex values:

write_colors "$THEME_DIR/colors.toml"
grep -q '#7aa2f7' "$(staged colors.toml)" && echo "Palette staged correctly"

System-Wide Propagation

After staging, the parsed colors propagate to every component requiring theme data:

• UI Components: QML and JavaScript code query the palette to color widgets, panels, and icons
• Terminal Emulators: Generated configuration files receive the same hexadecimal definitions from the TOML source
• Shell Assets: Environment variables and scripts access the staged palette for consistent theming across the desktop

Practical Usage Examples

Activate a built-in theme using the command-line tool:

omarchy-theme-set "Tokyo Night"

Programmatically stage and verify a custom theme:

THEME_DIR="$HOME/.config/omarchy/themes/mytheme"

# Stage the colors file

write_colors "$THEME_DIR/colors.toml"

# Verify the palette was applied

if grep -q '#abcdef' "$(staged colors.toml)"; then
    echo "Custom palette active"
fi

Summary

• Omarchy uses TOML files named colors.toml within each theme directory to store complete color palettes
• The omarchy-theme-set command reads these files to apply themes system-wide
• A staging mechanism using write_colors and staged functions verifies color values before full propagation
• Each TOML file includes a mode field (light/dark) and hexadecimal definitions for backgrounds, foregrounds, accents, and ANSI colors
• The test suite in test/shell.d/theme-staging-test.sh validates that color values are correctly staged and accessible

Frequently Asked Questions

Where does Omarchy store theme color definitions?

Omarchy stores color definitions in colors.toml files located inside each theme directory under the themes/ folder. For example, the white theme's colors are defined in themes/white/colors.toml according to the repository source code.

What keys are required in a colors.toml file?

A valid colors.toml file requires a mode key (set to "light" or "dark") and color definitions for background, foreground, accent, and the six base ANSI colors (red, yellow, green, cyan, blue, magenta) along with their bright variants.

How does Omarchy validate theme colors during application?

The system uses the test suite located at test/shell.d/theme-staging-test.sh to validate themes. It stages the colors.toml file using the write_colors function, then verifies specific hexadecimal values exist in the staged file using grep before completing the theme application.

Can I manually edit TOML theme files?

Yes, you can manually edit any colors.toml file within a theme directory. After editing, run omarchy-theme-set <theme-name> to reload the TOML definitions and propagate your changes to the UI and terminal configurations.

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