Shell.toml Surface Roles in Omarchy: Complete Guide to UI Styling Tokens

Shell.toml surface roles in Omarchy are named style token groups (like bar, menu, popups, launcher) that define colors, spacing, typography, and sizing for each UI surface, consumed by the Quickshell layer via Color and Style singletons.

Omarchy's desktop environment renders its interface through a generated shell.toml configuration file. This file organizes visual styling into discrete surface roles—logical groupings that map directly to UI components such as the status bar, application menus, notifications, and lock screen. Understanding these roles is essential for anyone customizing Omarchy's appearance or creating third-party themes.

What Are Surface Roles in Shell.toml?

A surface role is a top-level table in shell.toml that bundles related styling tokens. Each role corresponds to a specific UI "surface" or component type, providing the Quickshell QML layer with values for colors, opacity, borders, dimensions, and fonts.

The shell consumes these values through two runtime singletons defined in the source:

• Color — exposes palette values and per-surface color tokens (e.g., Color.menu.border)
• Style — exposes spacing, font scales, and dimensional values (e.g., Style.font.baseSize)

Both singletons are populated at runtime from the active theme's shell.toml, falling back to a generated default template. The parsing logic lives in shell/Commons/Color.qml (lines 9-25) and shell/Commons/Style.qml (lines 36-38).

Core Surface Roles Defined

The following surface roles ship with Omarchy's default template in default/themed/shell.toml.tpl:

bar

The main panel rendered across each monitor edge. Controls background color, text color, active state indicators, and dimensional sizing.

[bar]
background       = "#1e1e2e"
text             = "#cdd6f4"
active           = "#b4befe"
size-horizontal  = 28
size-vertical    = 28

controls

Interactive chrome elements including buttons, dropdowns, and tabs. Defines normal, hover, focus, and selected states with border widths and alpha values.

[controls]
normal-color        = "#313244"
hover-cursor-color  = "#f5e0dc"
focus-color         = "#cba6f7"
selected-color      = "#b4befe"
hover-border-width  = 2

popups

Generic fly-out panels including OSD displays and card-style dialogs.

[popups]
background    = "#181825"
border        = "#313244"
border-alpha  = 0.8

tooltip

Hover information displays triggered by bar and panel widgets.

[tooltip]
background = "#11111b"
text       = "#cdd6f4"
border     = "#313244"

notifications

Toast-style system alerts with countdown state coloring.

[notifications]
background = "#1e1e2e"
text       = "#cdd6f4"
border     = "#313244"
countdown  = "#fab387"

launcher

The fullscreen application overlay with scrim dimming and selection states.

[launcher]
background          = "#1e1e2e"
scrim               = "#000000"
scrim-alpha         = 0.7
selected-background = "#313244"
selected-text       = "#cdd6f4"

menu

The summoned application menu (including clipboard and emoji pickers). Shares token structure with launcher but scoped independently.

[menu]
background          = "#1e1e2e"
selected-background = "#313244"
selected-text       = "#cdd6f4"

polkit

Authentication prompts rendered by the polkit-agent component.

[polkit]
background    = "#1e1e2e"
text          = "#cdd6f4"
text-error    = "#f38ba8"
border        = "#313244"
border-error  = "#f38ba8"

hyprland

Bridge surface exposing Hyprland window manager integration tokens for active border gradients.

[hyprland]
active-border           = "#b4befe"
active-border-foreground = "#cdd6f4"

font

Global typographic scale with optional per-token overrides.

[font]
base-size = 10
caption   = 9
title     = 12

spacing

Global scaling factor and specific dimensional overrides for margins, padding, and gaps.

[spacing]
scale           = 1.0
scale-with-font = true
xxs             = 2
xs              = 4
sm              = 6
md              = 10
lg              = 16
xl              = 24
xxl             = 32

How Surface Roles Are Loaded and Prioritized

Omarchy resolves shell.toml through a cascading priority system:

1. Generated template — default/themed/shell.toml.tpl produces base values from colors.toml palette definitions
2. Theme override — Complete replacement via theme's shell.toml or partial via shell.<section>.toml
3. User configuration — ~/.config/omarchy/shell.toml wins for any present keys

The shell monitors the user-level file and hot-reloads changes without restart, as documented in docs/omarchy-shell.md (lines 176-190). Theme authors can ship granular overrides targeting specific surface roles only.

Consuming Surface Roles in QML Components

The Color and Style singletons expose surface tokens through dotted property paths matching the TOML structure:

// Rectangle using menu surface colors
Rectangle {
    color: Color.menu.background
    border.color: Color.menu.border
    border.width: Style.spacing.xs
    radius: Style.spacing.sm
}

// Text using font scaling
Text {
    font.pixelSize: Style.font.baseSize * 1.2
    color: Color.bar.text
}

The singleton implementations in shell/Commons/Color.qml and shell/Commons/Style.qml dynamically bind to shell.toml values, enabling runtime theme switching.

Practical Customization Examples

Override lock screen surface only

# ~/.config/omarchy/shell.toml

[lock]
background    = "#0b0b0b"
text          = "#ffffff"
border        = "#ff5555"
border-error  = "#ff0000"

Adjust bar dimensions via spacing

[spacing]
size-horizontal = 30   # taller top bar

size-vertical   = 32   # wider side bar

Custom tooltip with transparency

[tooltip]
background      = "#11111bff"  # explicit alpha

text            = "#cdd6f4"
border          = "#f5c2e7"
border-alpha    = 1.0

Key Source Files

Path	Purpose
default/themed/shell.toml.tpl	Template generating complete shell.toml from palette
shell/Commons/Color.qml	QML singleton loading color tokens
shell/Commons/Style.qml	QML singleton loading spacing/font tokens
docs/theming.md	Theming pipeline documentation (lines 78-87 for override behavior)
docs/omarchy-shell.md	Shell consumption and IPC documentation

Summary

• Shell.toml surface roles are named token groups defining visual properties for each Omarchy UI component
• Core roles: bar, controls, popups, tooltip, notifications, launcher, menu, polkit, hyprland, font, spacing
• Runtime access via Color.* and Style.* QML singletons populated from shell.toml
• Resolution order: generated template → theme override → user ~/.config/omarchy/shell.toml
• Hot-reload: Changes to user configuration apply without shell restart

Frequently Asked Questions

How do I override just one surface role without replacing the entire shell.toml?

Create a partial file named shell.<role>.toml in your theme directory, or add only the target [role] table to ~/.config/omarchy/shell.toml. Per docs/theming.md, these partial files merge with the base configuration, replacing only their scoped section.

Why are my shell.toml changes not appearing immediately?

Verify the file is at ~/.config/omarchy/shell.toml with correct TOML syntax. The shell monitors this path for changes, but syntax errors may prevent loading. Check journalctl for Quickshell parsing errors. Theme-level shell.toml files require a shell restart unless the theme is reloaded through Omarchy's theme switcher.

What is the difference between launcher and menu surface roles?

Both share identical token structures but target distinct UI surfaces. The launcher role styles the fullscreen application grid, while menu styles the summoned application menu (including clipboard history and emoji picker). This separation allows themes to differentiate fullscreen versus popup presentation contexts.

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