Omarchy Shell Theme Tokens: Complete Configuration Guide

The Omarchy shell exposes a comprehensive design token system through shell/Commons/Style.qml and shell/Commons/Color.qml that allows deep customization of colors, spacing, typography, and component states via TOML configuration files.

The Omarchy shell from basecamp/omarchy implements a token-driven architecture that separates visual design from implementation logic. These Omarchy shell theme tokens are loaded at startup through Color.loadColors and Style.applyShellValues, and can be customized either within a theme's shell.toml or overridden globally in ~/.config/omarchy/shell.toml.

State Color and Appearance Tokens

Visual feedback for interactive states is controlled through specific color and alpha tokens defined in shell/Commons/Style.qml. These define how components behave during user interaction.

According to the source code in Style.qml lines 70-76, the following state color tokens are available:

• normal-color — Default component state
• hover-cursor-color — Mouse hover indicators
• selected-color — Highlighted selection states
• pressed-color — Active press feedback
• focus-color — Keyboard focus rings
• selection-color — Text or item selection highlights

Border widths for these states are controlled separately in lines 77-81 through state border-width tokens: normal-border-width, hover-cursor-border-width, selected-border-width, and focus-border-width.

Transparency levels use state alpha tokens (lines 82-92) for both fill and border properties:

• Fill alphas: normal-fill-alpha, hover-cursor-fill-alpha, selected-fill-alpha, pressed-fill-alpha, focus-fill-alpha, selection-fill-alpha
• Border alphas: normal-border-alpha, hover-cursor-border-alpha, selected-border-alpha, focus-border-alpha

Layout and Spacing Tokens

The shell uses a consistent spacing scale defined in Style.qml lines 31-45. These spacing tokens range from microscopic gaps to large panel padding:

• Scale tokens: xxs, xs, sm, md, lg, xl, xxl, xxxl, huge
• Control dimensions: control-gap, control-padding-x, control-padding-y, control-height, input-padding-y
• Popup sizing: popup-row-height, popup-padding, searchable-popup-min-height
• Dropdown widths: dropdown-width, searchable-dropdown-width, number-field-width
• Layout spacing: row-gap, row-padding-x, label-gap, panel-gap, panel-padding

Typography and Icon Tokens

Font sizing follows a semantic scale rather than arbitrary pixel values. As implemented in Style.qml lines 27-34, the font tokens include:

• Text sizes: caption, body-small, body, subtitle, title, heading, display, display-large
• Icon sizes: icon-small, icon, icon-large

Bar Configuration Tokens

The shell's top and side bars expose specific sizing and slot tokens in Style.qml lines 41-48:

• size-horizontal — Height of horizontal bars
• size-vertical — Width of vertical bars
• icon-slot — Reserved space for icon placement
• icon-canvas — Drawing area for icons
• icon-font — Font family used for bar icons
• status-slot — Area reserved for status indicators

Surface Color Tokens

Complex UI surfaces expose granular color controls through the Color singleton in shell/Commons/Color.qml lines 73-102. Each surface supports background, background-alpha, text, border, and border-alpha properties where applicable:

• Bar surfaces: bar.background, bar.text, bar.active
• Popup surfaces: popups.background, popups.text, popups.border
• Tooltip surfaces: tooltip.background, tooltip.text, tooltip.border
• Notification surfaces: notifications.background, notifications.text, notifications.border, notifications.countdown
• Menu surfaces: menu.background, menu.text, menu.border, menu.scrim, menu.selected-background, menu.selected-text
• Polkit surfaces: polkit.background, polkit.text, polkit.text-error, polkit.border, polkit.border-error, polkit.accent, polkit.scrim
• Lock screen surfaces: lock.background, lock.text, lock.placeholder, lock.text-error, lock.border, lock.border-active, lock.border-error, lock.selection
• Image picker surfaces: image-picker.scrim, image-picker.text, image-picker.selected-border, image-picker.unselected-border

Foundational Palette Tokens

Global color references are defined in Color.qml lines 19-23 as foundational palette tokens:

• foreground — Primary text color
• background — Canvas background
• accent — Brand/interactive highlight
• urgent — Error or critical states
• muted — Secondary or disabled content

How to Customize Theme Tokens

Users can modify Omarchy shell theme tokens through TOML configuration. Theme authors define defaults in the theme's shell.toml, while end users can override values in ~/.config/omarchy/shell.toml without modifying theme files.

# Override button appearance

[style]
normal-color = "foreground"
normal-fill-alpha = 0.07
hover-cursor-fill-alpha = 0.15

# Adjust bar dimensions

[bar]
size-vertical = 30
size-horizontal = 28

# Customize menu surfaces

[menu]
background = "#202020"
background-alpha = 0.95
selected-background = "accent"

Apply changes using the Omarchy CLI:

# Apply a complete theme refresh

omarchy refresh-config themes/my-theme

# Reload configuration without shell restart

omarchy reload-config

The system re-evaluates tokens during theme switches, making omarchy reload-config sufficient for most token adjustments.

Summary

• Omarchy shell theme tokens are defined in shell/Commons/Style.qml (spacing, fonts, states) and shell/Commons/Color.qml (surfaces, palette).
• State tokens control interactive feedback through color, border-width, and alpha properties for normal, hover, selected, pressed, and focus states.
• Surface tokens provide granular control over bars, popups, menus, notifications, the lock screen, and polkit dialogs.
• Customization occurs through shell.toml files, with user overrides supported in ~/.config/omarchy/shell.toml.
• Changes are loaded at runtime via Color.loadColors and Style.applyShellValues, and can be hot-reloaded using omarchy reload-config.

Frequently Asked Questions

Where are Omarchy shell theme tokens defined?

The tokens are defined in two primary QML files within the basecamp/omarchy repository: shell/Commons/Style.qml contains spacing, typography, bar configuration, and interactive state tokens (lines 27-92), while shell/Commons/Color.qml defines the foundational palette and surface-specific color tokens (lines 19-102).

How do I override theme tokens without modifying theme files?

Create or edit ~/.config/omarchy/shell.toml and add TOML sections matching the token categories (such as [style], [bar], or [menu]). Values specified here take precedence over theme defaults but remain independent of theme updates. Run omarchy reload-config to apply changes without restarting the shell.

What is the difference between Style.qml and Color.qml tokens?

Style.qml tokens primarily control dimensions, spacing, and interactive state styling (normal, hover, selected, pressed), while Color.qml manages the color system including the foundational palette (foreground, background, accent) and surface-specific colors for UI components like bars, popups, and menus.

Do theme token changes require restarting the shell?

No. The Omarchy shell supports hot-reloading of configuration values. After editing shell.toml files, run omarchy reload-config to trigger Style.applyShellValues and Color.loadColors, which re-evaluates the token values without requiring a shell restart.

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