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

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.

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

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():

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:

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)
• 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 file in your theme directory (e.g., 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.

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