# Omarchy Shell Theme Tokens: Complete Configuration Guide

> Explore the Omarchy shell theme tokens for deep customization. This guide covers configuring colors, spacing, typography, and component states via TOML.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/basecamp/omarchy/blob/main/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](https://github.com/basecamp/omarchy/blob/quattro/shell/Commons/Style.qml#L70-L76), 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](https://github.com/basecamp/omarchy/blob/quattro/shell/Commons/Style.qml#L31-L45). 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](https://github.com/basecamp/omarchy/blob/quattro/shell/Commons/Style.qml#L27-L34), 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](https://github.com/basecamp/omarchy/blob/quattro/shell/Commons/Style.qml#L41-L48):

- `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](https://github.com/basecamp/omarchy/blob/quattro/shell/Commons/Color.qml#L73-L102). 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](https://github.com/basecamp/omarchy/blob/quattro/shell/Commons/Color.qml#L19-L23) 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`](https://github.com/basecamp/omarchy/blob/main/shell.toml), while end users can override values in `~/.config/omarchy/shell.toml` without modifying theme files.

```toml

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

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.