# Omarchy `colors.toml` Structure: Complete Guide to Theme Configuration

> Explore the Omarchy colors.toml structure. Learn how to configure your theme's complete color palette across meta, core accents, backgrounds, foregrounds, and basic colors for a personalized look.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-01

---

**The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file in Omarchy is a flat TOML configuration that defines a theme's complete color palette through five logical sections: meta, core accents, background variants, foreground variants, and a basic color set with bright equivalents.**

Every theme in the Omarchy desktop environment ships its own [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) under `themes/<theme>/`. This single file drives the visual appearance across all UI components, from status bars to application menus. Understanding its structure is essential for custom theme development.

## Flat Key-Value Design Philosophy

Omarchy's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) **intentionally avoids nesting or TOML tables**. All entries are simple `key = "hex"` assignments. This flat design prioritizes **parsing speed** in the QML runtime that renders the desktop shell.

The layout remains identical across all themes—only hex values change. Whether you're working with the built-in **white**, **nord**, or **catppuccin** themes, you'll find the same keys in every file.

## The Five Structural Sections

### 1. Meta Information

The `mode` key declares the theme's brightness profile:

```toml
mode = "dark"  # or "light"

```

This boolean-like flag tells UI components whether to apply dark-mode or light-mode logic for automatic contrast adjustments.

### 2. Core Accent & UI Helpers

Three foundational colors define interactive states:

| Key | Purpose |
|-----|---------|
| `accent` | Primary highlight color for focused elements |
| `selection` | Background for selected text or items |
| `muted` | De-emphasized UI elements |

From [`themes/nord/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/nord/colors.toml):

```toml
accent = "#81a1c1"
selection = "#434c5e"
muted = "#4c566a"

```

### 3. Background Family

Four progressive shades handle layered surfaces:

```toml
background = "#2e3440"        # Default surface

dark_background = "#222730"   # Panels, sidebars

darker_background = "#1e222a" # Tooltips, overlays

lighter_background = "#3b4252" # Elevated cards

```

The **white theme** inverts this progression—`dark_background` becomes `#f5f5f5` (off-white) rather than a darker shade, because the base `background` is pure `#ffffff`.

### 4. Foreground Family

Text colors adapt to different surface contrast needs:

```toml
foreground = "#d8dee9"        # Primary text

dark_foreground = "#667080"   # Text on light surfaces

light_foreground = "#e5e9f0"  # Text on dark surfaces

bright_foreground = "#eceff4" # Emphasized text

```

### 5. Basic Color Set & Bright Variants

Sixteen colors (eight base + eight bright) complete the palette:

```toml

# Base colors

red = "#bf616a"
yellow = "#ebcb8b"
green = "#a3be8c"
cyan = "#88c0d0"
blue = "#5e81ac"
magenta = "#b48ead"

# Bright equivalents

bright_red = "#bf616a"
bright_yellow = "#ebcb8b"

# ... etc

```

Note: In many themes, bright variants duplicate base colors. Omarchy's design treats "bright" as a semantic label for **active/highlighted states** rather than requiring distinct values.

## Complete File Example: Nord Theme

[`themes/nord/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/nord/colors.toml) demonstrates full structure:

```toml
mode = "dark"

accent = "#81a1c1"
selection = "#434c5e"
muted = "#4c566a"

background = "#2e3440"
dark_background = "#222730"
darker_background = "#1e222a"
lighter_background = "#3b4252"

foreground = "#d8dee9"
dark_foreground = "#667080"
light_foreground = "#e5e9f0"
bright_foreground = "#eceff4"

red = "#bf616a"
yellow = "#ebcb8b"
green = "#a3be8c"
cyan = "#88c0d0"
blue = "#5e81ac"
magenta = "#b48ead"

bright_red = "#bf616a"
bright_yellow = "#ebcb8b"
bright_green = "#a3be8c"
bright_cyan = "#8fbcbb"
bright_blue = "#81a1c1"
bright_magenta = "#b48ead"

```

## Consuming [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) in QML

The shell loads this palette at runtime. Here's how `shell/shell.qml` parses it:

```qml
import QtQuick 2.15

property var themePath: Quickshell.env("OMARCHY_PATH") + "/themes/" + currentTheme + "/colors.toml"
property var palette: {}

Component.onCompleted: {
    const file = new TextFile(themePath, TextFile.ReadOnly)
    const lines = file.readAll().split("\n")
    for (let line of lines) {
        const match = line.match(/^(\w+)\s*=\s*"([^"]+)"/)
        if (match) palette[match[1]] = match[2]
    }
    file.close()
}

// Applied in components
Rectangle {
    color: palette.background
    Text {
        color: palette.foreground
        text: "Omarchy Desktop"
    }
}

```

The regex `^(\w+)\s*=\s*"([^"]+)"` exploits the flat structure—no nested tables means line-by-line parsing suffices.

## Template Integration

Non-QML files consume the same palette through `default/themed/*.tpl` templates:

```toml

# In default/themed/bar.tpl

background: {{ background }};
border-color: {{ accent }};
color: {{ bright_foreground }};

```

The template engine substitutes `{{ key }}` placeholders with hex values from the active theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml).

## Key File Reference

| Path | Purpose |
|------|---------|
| `themes/<theme>/colors.toml` | Theme palette definition (e.g., [`themes/nord/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/nord/colors.toml), [`themes/white/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/white/colors.toml)) |
| `default/themed/*.tpl` | Template files using `{{ key }}` substitution |
| `shell/shell.qml` | Core loader that parses [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) into the `palette` object |
| [`docs/theme.md`](https://github.com/omacom/omarchy/blob/main/docs/theme.md) | Official theming documentation |

## Summary

- **[`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)** uses a **flat key-value structure**—no tables, no nesting—for QML parsing performance
- **Five logical sections**: meta (`mode`), core accents (`accent`, `selection`, `muted`), backgrounds, foregrounds, and basic/bright colors
- **Identical key names** across all themes; only hex values vary
- **Runtime consumption** via QML `TextFile` parsing or template `{{ substitution }}`
- **Source paths**: `themes/<theme>/colors.toml` with `shell/shell.qml` as the primary consumer

## Frequently Asked Questions

### How do I create a custom Omarchy theme?

Create a new directory under `themes/` with a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file containing all standard keys. Copy an existing theme like `nord` as a template, then modify hex values. No registration is required—the theme becomes available by directory name immediately.

### Why are bright colors sometimes identical to base colors in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)?

Omarchy treats `bright_` prefixes as **semantic state markers** rather than color modifiers. Many themes reuse identical hex values because the UI distinguishes "active" versus "normal" through opacity or layering rather than hue shift. You may customize these independently if your design requires distinct bright variants.

### Can I add custom keys to [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)?

Additional keys won't break parsing, but they won't be utilized by core Omarchy components. The QML loader in `shell/shell.qml` captures all key-value pairs into the `palette` object, so custom QML components can access extended keys. Standard templates in `default/themed/` only reference the documented key set.

### Does `mode = "light"` change automatic behavior?

Yes—the `mode` key enables **adaptive contrast logic**. Components reading the palette can switch calculation strategies: light-mode themes may invert shadow directions, adjust overlay opacity, or select alternative text colors for readability without hardcoding theme names.