# Omarchy Shell Theme Tokens: Color, Style, and Border Reference

> Explore Omarchy shell theme tokens for Color, Style, and Border. This QML-based system defines UI component appearance in basecamp/omarchy.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: api-reference
- Published: 2026-08-25

---

**Omarchy shell theme tokens are organized into three families—Color, Style, and Border—that define the visual appearance of UI components through a QML-based token system located in `shell/Color.qml`, `shell/Style.qml`, and `shell/Border.qml`.**

Omarchy is a QML-based shell environment that uses a comprehensive token system to separate visual design from component logic. Understanding these Omarchy shell theme tokens allows developers to customize appearances globally through theme definition files without modifying individual component source code.

## The Three Families of Omarchy Shell Theme Tokens

Omarchy's visual architecture relies on three distinct token families that work together to render the shell interface. Each family serves a specific purpose in the styling pipeline.

### Color Tokens (The Color Singleton)

Color tokens define the palette used throughout the shell and are exposed via the `Color` singleton declared in `shell/Color.qml`. These roles can be overridden by theme-specific values defined in `themes/*/colors.toml` files.

Core color roles include:

- `Color.foreground` – Primary text and icon colors
- `Color.background` – Base surface backgrounds  
- `Color.accent` – Interactive highlight colors
- `Color.urgent` – Attention-demanding alert colors

Surface-specific color tokens provide contextual coloring for distinct UI regions:

- `Color.menu.border` and `Color.menu.background`
- `Color.popups.border`
- `Color.tooltip.border`
- `Color.lock.borderError` and `Color.lock.borderActive`
- `Color.notifications.border`

### Style Tokens (Spacing and Sizing)

Style tokens provide spacing, sizing, and layout-related values through the `Style` singleton defined in `shell/Style.qml`. These tokens resolve to concrete pixel values based on the active theme configuration.

Key Style token functions include:

- `Style.space(x)` – Generic spacing token that returns theme-defined pixel values
- `Style.normalBorderFor(fg, accent)` – Calculates default border widths for specific color pairs
- `Style.spacing.rowPaddingX` – Horizontal padding for row layouts
- `Style.spacing.hairline` – Minimum border width values

### Border Tokens (Border Specifications)

Border tokens describe how widget borders should be drawn, combining color, width, and optional alpha adjustments. These helpers live in `shell/Border.qml` and return specification objects that QML components bind to via `borderSpec` properties.

Available Border helpers include:

- `Border.controlSpec(state, fg, accent)` – Returns state-aware borders for interactive controls
- `Border.surfaceSpec(surface, role, colour, width, alphaToken?)` – Generates surface-specific border specifications
- `Border.flat(colour, width)` – Creates simple flat borders
- `Border.none()` – Disables borders entirely

The `Border.controlSpec()` function accepts four distinct states: `normal`, `hover-cursor`, `selected`, and `focus`.

## How Omarchy Shell Theme Tokens Work Together

Components typically consume all three token families in a coordinated pattern. First, the component declares a **color** reference, then uses **Style** helpers to compute dimensions, and finally constructs a **Border** specification for the rendering engine.

```qml
property color border: Color.menu.border
property var borderSpec: Border.surfaceSpec(
    "menu",               // surface name
    "border",             // role identifier
    border,               // color from Color token
    Math.max(1, Style.space(2)) // width from Style token
)

```

This separation allows themes to modify [`themes/white/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml) (or any theme directory) to change `Color.menu.border` values globally, while spacing adjustments in theme configuration automatically propagate through `Style.space()` calls.

## Practical Implementation Examples

### Menu Items with Surface Borders

The following pattern from `shell/plugins/menu/Menu.qml` demonstrates surface-specific border application:

```qml
MenuItem {
    property color border: Color.menu.border
    property var borderSpec: Border.surfaceSpec(
        "menu", "border", border,
        Math.max(1, Style.space(2))   // resolves to theme spacing
    )
    // UI engine applies borderSpec automatically
}

```

### Interactive Controls with State-Aware Borders

For interactive elements that change appearance based on input state, use `Border.controlSpec()`:

```qml
TextField {
    readonly property var _borderSpec: Border.controlSpec(
        _focused ? "focus" : (_hot ? "hover-cursor" : "normal"),
        foreground,         // Color.foreground
        accent              // Color.accent
    )
    borderSpec: _borderSpec
}

```

### Notification Cards Using Surface Tokens

As implemented in `shell/plugins/notifications/components/NotificationCard.qml`:

```qml
NotificationCard {
    readonly property var cardBorderSpec: Border.surfaceSpec(
        "notifications", "border",
        Color.notifications.border,
        Math.max(1, Style.space(2))
    )
    borderSpec: cardBorderSpec
}

```

## Key Source Files for Omarchy Theme Tokens

Understanding where these tokens are declared helps when debugging or extending the system:

- `shell/Color.qml` – Declares the `Color` singleton with all color roles
- `shell/Style.qml` – Provides spacing, sizing, and layout calculation helpers
- `shell/Border.qml` – Implements `controlSpec`, `surfaceSpec`, `flat`, and `none` helpers
- `themes/*/colors.toml` – Theme-specific color values that populate `Color` tokens (e.g., [`themes/white/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml))
- `shell/plugins/reminders/ReminderFlow.qml` – Reference implementation showing `Color.menu.border` with `Border.surfaceSpec` bindings

## Summary

- **Color tokens** (`shell/Color.qml`) define the palette through the `Color` singleton, with overrides in `themes/*/colors.toml` files
- **Style tokens** (`shell/Style.qml`) provide spacing and sizing through functions like `Style.space(x)` and `Style.normalBorderFor()`
- **Border tokens** (`shell/Border.qml`) construct rendering specifications via `Border.controlSpec()` for state-aware borders and `Border.surfaceSpec()` for surface-specific borders
- Components bind to these tokens through `borderSpec` properties, allowing global theme changes without code modification
- The system supports four interaction states (`normal`, `hover-cursor`, `selected`, `focus`) through the control specification API

## Frequently Asked Questions

### How do I override Omarchy color tokens in a custom theme?

Create a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file in your theme directory (e.g., [`themes/mytheme/colors.toml`](https://github.com/basecamp/omarchy/blob/main/themes/mytheme/colors.toml)) and define values for the color roles. The `Color` singleton in `shell/Color.qml` automatically loads these values at runtime, overriding the defaults. For example, setting the menu border color requires defining the `menu.border` key in your TOML configuration.

### What is the difference between `Border.controlSpec` and `Border.surfaceSpec`?

`Border.controlSpec(state, fg, accent)` creates borders for interactive controls that change based on user interaction states (normal, hover-cursor, selected, focus), while `Border.surfaceSpec(surface, role, colour, width, alphaToken?)` creates static borders specific to UI surfaces like menus, notifications, or lock screens. Use control specs for buttons and input fields; use surface specs for cards, panels, and containers.

### Can I disable borders entirely using Omarchy theme tokens?

Yes. Call `Border.none()` to return a border specification that disables rendering. This is useful for flat design implementations or when components should blend seamlessly with their parent containers without visual separation.

### Where are spacing values defined in Omarchy?

Spacing values are defined in `shell/Style.qml` and resolved through the `Style.space(x)` function, where `x` represents a spacing scale factor. Theme configurations provide the base pixel values that this function returns, allowing consistent rhythm across the shell interface. Specific spacing constants like `Style.spacing.rowPaddingX` and `Style.spacing.hairline` are also exported for common layout patterns.