# Omarchy Shell Theme Token System: How Quickshell Manages Theming

> Discover the Omarchy theme token system for shell theming. Learn how Quickshell uses TOML and QML singletons for consistent, state-aware desktop theming.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-28

---

**The Omarchy shell theme token system uses a declarative configuration in TOML files that exposes visual primitives to QML through three read-only singletons—`Style`, `Color`, and `Border`—enabling consistent, state-aware theming across the desktop environment.**

The **theme token system** in Omarchy (built by Basecamp on the Quickshell framework) decouples visual design from component implementation. By storing colors, dimensions, spacing, and gradients as named tokens, the system allows users and theme authors to customize the entire shell appearance without modifying QML source code.

## How the Token Architecture Works

Omarchy’s theming layer rests on three core concepts that bridge configuration files and the QML runtime.

### Token Definitions in TOML

**Theme tokens** are name-value pairs defined in [`config/shell.toml`](https://github.com/basecamp/omarchy/blob/main/config/shell.toml) for base values or overridden by `~/.config/omarchy/shell.toml` and theme-specific [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) files. These entries can specify simple hex colors, numeric dimensions, or complex gradient literals.

```toml
[ui]
accent = "#ff5722"
cornerRadius = 6
headerGradient = "rgba(#ff9a00ff) rgba(#ff4500ff) 90deg"

```

The system supports **semantic tokens** (e.g., `Style.spacing.small`) and **raw tokens**, with state-aware variants for interactive elements like `selected` or `hovered`.

### QML Singleton Exposures

When Quickshell initializes, it constructs a token map from the merged configuration and exposes it through three immutable singletons:

- **`Style`** – Structural properties (spacing, radii, dimensions)
- **`Color`** – Palette values (backgrounds, accents, text colors)
- **`Border`** – Border specifications and helper functions

In `shell/qml/Style.qml`, these singletons provide read-only access to the token map, ensuring visual consistency at runtime since tokens cannot be modified dynamically.

### The Configuration Hierarchy

Token resolution follows a predictable precedence:

1. **Base tokens** load from [`config/shell.toml`](https://github.com/basecamp/omarchy/blob/main/config/shell.toml) in the repository
2. **User overrides** apply from `~/.config/omarchy/shell.toml`
3. **Theme definitions** load from `themes/*/colors.toml`

This hierarchy allows safe customization while preserving defaults for undefined values.

## Using Theme Tokens in QML Components

QML files consume tokens directly through singleton imports or compute derived values using helper methods.

### Reading Structural and Color Tokens

Components access tokens via property bindings to the singletons:

```qml
import QtQuick 2.15
import Omarchy.Style 1.0

Rectangle {
    width: 200
    height: 100
    radius: Style.cornerRadius
    color: Color.accent
}

```

**Semantic tokens** like `Color.background` or `Style.spacing.medium` automatically adapt when the active theme changes, eliminating hard-coded values in UI logic.

### Border Helpers and State-Aware Tokens

The `Border` singleton provides `surfaceSpec()`, a helper function that resolves border colors with automatic state detection and alpha application. The signature reads:

```

Border.surfaceSpec(section, token, fallbackColor, fallbackWidth, alphaKey)

```

This function checks for state-specific token variants (e.g., `border.selected`) and falls back to defaults when state tokens are undefined:

```qml
Rectangle {
    border.width: Border.surfaceSpec("panel", "border", "#000", 2, "borderAlpha")
}

```

The `alphaKey` parameter optionally applies transparency without redefining the base color token, supporting dynamic opacity adjustments while maintaining palette coherence.

## Overriding Tokens for Custom Themes

Users and theme authors customize the shell by overriding base tokens without touching QML source files.

### User Configuration Overrides

Create or edit `~/.config/omarchy/shell.toml` to adjust specific visual properties:

```toml
[ui]
accent = "#2a9d8f"
cornerRadius = 8

```

These changes apply immediately on shell restart, affecting all components that reference `Color.accent` or `Style.cornerRadius`.

### Theme Color Definitions

Complete themes reside in the `themes/` directory, each containing a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) that replaces or extends the default token set. This file-based approach enables version-controlled theming and community distribution of visual presets.

## Summary

- **Token storage** lives in [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) files (base and user overrides) and theme-specific [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml), defining colors, gradients, spacing, and radii.
- **QML exposure** occurs through three singletons—`Style`, `Color`, and `Border`—defined in `shell/qml/Style.qml` and imported as `Omarchy.Style 1.0`.
- **State awareness** enables interactive styling via `Border.surfaceSpec()`, which handles fallback logic and alpha blending for hover, selected, and active states.
- **Configuration precedence** flows from base defaults to user configs to theme definitions, ensuring safe customization without forking code.

## Frequently Asked Questions

### What files define the base Omarchy theme tokens?

Base tokens reside in [`config/shell.toml`](https://github.com/basecamp/omarchy/blob/main/config/shell.toml) within the repository. The system loads these defaults first, then overlays user-specific overrides from `~/.config/omarchy/shell.toml` and theme files from `themes/*/colors.toml` according to the hierarchy documented in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md).

### How do I change the accent color in Omarchy?

Add an `[ui]` section to your user configuration file at `~/.config/omarchy/shell.toml` and set the `accent` property: `accent = "#2a9d8f"`. This updates `Color.accent` across all QML components automatically.

### What are the three QML singletons for accessing tokens?

The `Omarchy.Style` import exposes `Style` (structural tokens like spacing and radii), `Color` (palette values), and `Border` (border specifications and helper functions). These singletons provide read-only access to the token map loaded at startup.

### Can Omarchy theme tokens define gradients?

Yes. The token system accepts gradient literals in the format `rgba(color1) rgba(color2) angle` within TOML definitions. Reference these in QML by passing the token name to gradient properties, allowing complex directional backgrounds through the same semantic naming system as solid colors.