# How the Omarchy Theming System Uses TOML for Color Definitions

> Explore how Omarchy uses TOML for color definitions. Learn how colors.toml files ensure consistent palettes across your desktop, terminal, and UI with omarchy-theme-set.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-24

---

**Omarchy stores theme color palettes in [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml):

```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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
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:

```bash
omarchy-theme-set "Tokyo Night"

```

Programmatically stage and verify a custom theme:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml) according to the repository source code.

### What keys are required in a colors.toml file?

A valid [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/theme-staging-test.sh) to validate themes. It stages the [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.