Omarchy Shell Theme Token System: How Quickshell Manages Theming

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 for base values or overridden by ~/.config/omarchy/shell.toml and theme-specific colors.toml files. These entries can specify simple hex colors, numeric dimensions, or complex gradient literals.

[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 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:

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:

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:

[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 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 files (base and user overrides) and theme-specific 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 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.

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.

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