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

> Explore shell.toml surface roles in Omarchy, a guide to UI styling tokens. Learn how Omarchy's named style token groups define visual elements for your interface.

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

---

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

```toml
[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.

```toml
[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.

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

```

### tooltip

Hover information displays triggered by bar and panel widgets.

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

```

### notifications

Toast-style system alerts with countdown state coloring.

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

```

### launcher

The fullscreen application overlay with scrim dimming and selection states.

```toml
[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.

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

```

### polkit

Authentication prompts rendered by the `polkit-agent` component.

```toml
[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.

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

```

### font

Global typographic scale with optional per-token overrides.

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

```

### spacing

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

```toml
[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`](https://github.com/omacom/omarchy/blob/main/shell.toml) through a cascading priority system:

1. **Generated template** — `default/themed/shell.toml.tpl` produces base values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) palette definitions
2. **Theme override** — Complete replacement via theme's [`shell.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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:

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

```

```qml
// 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`](https://github.com/omacom/omarchy/blob/main/shell.toml) values, enabling runtime theme switching.

## Practical Customization Examples

### Override lock screen surface only

```toml

# ~/.config/omarchy/shell.toml

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

```

### Adjust bar dimensions via spacing

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

size-vertical   = 32   # wider side bar

```

### Custom tooltip with transparency

```toml
[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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) | Theming pipeline documentation (lines 78-87 for override behavior) |
| [`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.