The Omarchy Style Token System: Centralized QML Theming Architecture

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

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

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

[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 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 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 or font.body independently through [spacing] and [font] sections in 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.

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