# The Omarchy Style Token System: Centralized QML Theming Architecture

> Discover the Omarchy Style token system a centralized QML singleton for dynamic theming. Easily manage colors spacing typography and dimensions with runtime overrides via shell.toml.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: architecture
- Published: 2026-09-04

---

**The Omarchy Style token system is a centralized QML singleton that exposes named, theme-aware values for colors, spacing, typography, and bar dimensions, enabling dynamic runtime theming through [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) overrides without hard-coding values in UI components.**

The Omarchy shell (omacom/omarchy) implements a sophisticated token-based design system to manage its entire visual layer. Rather than scattering pixel values and hex codes throughout individual QML files, the shell consolidates every visual property into a single source of truth defined in `shell/Commons/Style.qml`. This architecture guarantees consistent interactive states, responsive scaling, and seamless theme customization across the desktop environment.

## What Is the Style Token System?

The **Style token system** in Omarchy is a QML singleton that functions as a centralized registry of design tokens. A *token* is a named variable representing a specific visual value—such as `normalColorToken` for foreground colors or [`spacing.md`](https://github.com/omacom/omarchy/blob/main/spacing.md) for medium margins—that components reference instead of literal values.

This system resides in `shell/Commons/Style.qml` and operates through several key mechanisms:

- **Token lookup functions** resolve values by checking runtime override dictionaries before falling back to computed defaults
- **Theme injection** populates override objects when `Color.loadShell` calls `Style.applyShellValues(values)` (lines 84‑104)
- **Responsive scaling** multiplies base values by `spacingScale` and `fontScale` factors to adapt the UI to different display densities

## Core Token Categories in Style.qml

The singleton organizes tokens into logical sections that mirror CSS-in-JS design systems but optimized for Qt Quick.

### State Tokens for Interactive UI

Interactive states rely on a shared color vocabulary defined around lines 70‑75. Key tokens include:

- `normalColorToken` – resolved via `styleString("normal-color", "foreground")`
- `hoverColorToken` – for cursor hover states
- `selectedColorToken` – for highlighted or active elements
- `focusColorToken` – for keyboard navigation focus

These tokens work with alpha variants like `normalFillAlpha` (line 82) to produce final fill colors through functions such as `normalFillFor(foreground, accent, urgent)`.

### Spacing and Layout Scale

The spacing system implements a "rem-like" architecture (lines 31‑45) where raw pixel values are multiplied by `spacingScale`. Core tokens include:

- `spacing.scale` – the base multiplier
- `spacing.xs`, [`spacing.md`](https://github.com/omacom/omarchy/blob/main/spacing.md) – semantic size tokens
- `spacing.panelGap` – specific layout gaps

The helper function `spaceReal(px)` (line 13) converts pixel values to device-independent units, while `spacingToken` lookups allow themes to override specific gaps via `spacingOverrides`.

### Typography Tokens

Font sizing uses a similar scaling approach (lines 21‑33) with tokens like:

- `font.body` – standard interface text
- `font.title` – emphasized headers
- `font.iconLarge` – system tray and widget icons

The `fontScale` factor applies to all typography tokens, enabling global text size adjustments without touching individual `Text` elements.

### Bar Dimension Tokens

Physical dimensions for the top and bottom bars are controlled through tokens found around lines 41‑48:

- `bar.sizeHorizontal` – height of horizontal bars
- `bar.iconSlot` – width allocated for application icons
- `bar.statusSlot` – width for system indicators

These dimensions are queryable via `barToken` lookups that check `barOverrides` before returning defaults.

### Runtime Override Dictionaries

The system maintains four override objects (lines 46‑53 and 98‑106) that themes populate at runtime:

- `styleOverrides` – color and border properties
- `spacingOverrides` – margin and gap values
- `fontOverrides` – type size adjustments
- `barOverrides` – shell bar geometry

When a theme loads, its `[style]`, `[controls]`, `[spacing]`, `[font]`, and `[bar]` sections from [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) map into these dictionaries via `applyShellValues`.

## How Theme Injection Works

Theme integration follows a specific resolution path. When the shell initializes a theme:

1. `Color.loadShell` invokes `Style.applyShellValues(values)` (lines 84‑104)
2. The function parses TOML sections and populates override dictionaries
3. UI components query tokens through helper functions like `styleString`, `spacingToken`, `fontToken`, and `barToken`
4. These functions return override values if present, otherwise computed defaults

For example, `normalColorToken` resolves by calling `styleString("normal-color", "foreground")` (line 70), checking if the theme defined a `normal-color` key in its `[style]` section before defaulting to the palette's foreground color.

## Implementing Style Tokens in QML Components

Components import the singleton and reference tokens declaratively. Here is a button implementation using state-aware colors and spacing:

```qml
// Button using Style tokens for states and metrics
Rectangle {
    id: btn
    width: 120
    height: Style.space(8)          // spacing token for padding
    color: Style.normalFill         // state-aware fill color
    border.width: Style.normalBorderWidth
    border.color: Style.normalBorderColor

    MouseArea {
        anchors.fill: parent
        hoverEnabled: true
        onEntered: btn.color = Style.hoverFill
        onExited:  btn.color = Style.normalFill
        onPressed: btn.color = Style.pressedFill
    }

    Text {
        anchors.centerIn: parent
        text: "Click me"
        font.pixelSize: Style.font.body          // typography token
        color: Style.normalStateColor(Color.foreground, Color.accent, Color.urgent)
    }
}

```

Layout components use spacing tokens to maintain consistent gaps:

```qml
// Layout using spacing and bar dimension tokens
Row {
    spacing: Style.spacing.controlGap
    Rectangle { 
        width: Style.bar.iconSlot 
        height: Style.bar.iconSlot 
        color: Style.normalFill 
    }
    Rectangle { 
        width: Style.bar.statusSlot 
        height: Style.bar.statusSlot 
        color: Style.hoverFill 
    }
}

```

Themes override these values at runtime through [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml):

```toml
[style]
normal-color = "accent"
hover-cursor-border-width = 2

[spacing]
control-gap = 12

[font]
body = 14

[bar]
icon-slot = 48

```

## Summary

- **`shell/Commons/Style.qml`** serves as the central singleton exposing all design tokens through `Style` imports.
- **State tokens** provide consistent colors for normal, hover, selected, and focus interactions via `normalColorToken` and related helpers.
- **Spacing and typography** scale responsively using `spacingScale` and `fontScale` multipliers applied to base values.
- **Override dictionaries** allow themes to customize any token without modifying source code, populated via `applyShellValues` from [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) sections.
- **Bar dimension tokens** control shell geometry through `bar.iconSlot` and `bar.statusSlot`, ensuring layout consistency.

## Frequently Asked Questions

### What file defines the Style token system in Omarchy?

The Style token system is defined in `shell/Commons/Style.qml` according to the omacom/omarchy source code. This singleton exposes all tokens and helper functions like `styleString` and `spacingToken` that components use to resolve visual values.

### How do I override a specific color token in my theme?

Create a `[style]` section in your theme's [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) and define the token key. For example, setting `normal-color = "accent"` overrides the `normalColorToken` resolution. The `Style.applyShellValues` function parses these entries into the `styleOverrides` dictionary at runtime.

### Can spacing and fonts scale independently in Omarchy themes?

Yes. The system maintains separate `spacingScale` and `fontScale` factors (referenced in `spaceReal` calculations and font token resolution). Themes can adjust these multipliers or override specific tokens like [`spacing.md`](https://github.com/omacom/omarchy/blob/main/spacing.md) or `font.body` independently through `[spacing]` and `[font]` sections in [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml).

### How do bar dimension tokens affect the shell layout?

Tokens such as `bar.sizeHorizontal`, `bar.iconSlot`, and `bar.statusSlot` (defined around lines 41‑48 in `Style.qml`) determine the physical geometry of the top and bottom bars. When themes override these via the `[bar]` section or `barOverrides`, the shell layout recalculates automatically without requiring changes to individual widget implementations.