How to Use BorderSurface with Omarchy Theme Tokens in QML

BorderSurface is the Omarchy UI primitive that renders rectangle-compatible backgrounds while honoring theme-driven border specifications, automatically selecting between hardware-accelerated native rendering and custom Shape-based overlays depending on border complexity.

The Omarchy desktop environment provides a sophisticated theming system for QML-based user interfaces. Understanding how to leverage BorderSurface with Omarchy theme tokens allows developers to create consistent, performant UI components that respect system-wide design specifications defined in shell.toml configuration files.

What is BorderSurface?

BorderSurface is a core visual primitive located in shell/Ui/BorderSurface.qml that extends standard Rectangle capabilities with theme-aware border rendering. Unlike a basic Rectangle, it accepts a structured borderSpec property instead of simple border.color and border.width values.

The component implements an intelligent rendering strategy:

• Native rendering: When the border specification contains uniform widths and no gradient, BorderSurface sets the underlying Rectangle.border properties directly, leveraging GPU acceleration
• Overlay rendering: For asymmetric widths or gradient borders, it dynamically loads BorderOverlay from shell/Ui/BorderOverlay.qml to draw complex paths using QML Shape

The Border singleton in shell/Commons/Border.qml serves as the factory that converts raw theme tokens into these structured border specifications.

Converting Theme Tokens to Border Specifications

Omarchy themes define border aesthetics in shell.toml (or default/themed/shell.toml.tpl) using a hierarchical token system:

[panel]
border = "#444"                      # Solid color or gradient definition

border-width = "2"                   # Uniform width, or "2 0 2 0" for per-side

border-alpha = 0.9
border-gradient = "45deg #444 #555"    # Optional gradient with angle

The Border.qml singleton transforms these declarations into JavaScript specification objects using the surfaceSpec factory function:

import qs.Commons  // Imports Border, Color, Style singletons

// Generate spec from theme tokens
var spec = Border.surfaceSpec(
    "panel",          // Theme section name
    "border",         // Token key
    Color.accent,     // Fallback color if theme undefined
    1,                // Fallback width
    "border-alpha"    // Optional alpha multiplier key
)

The resulting specification object follows this structure:

{
    color: Qt.rgba(...),           // Resolved color value
    widths: {
        top: 2,
        right: 2,
        bottom: 2,
        left: 2
    },
    gradient: {
        colors: ["#444", "#555"],
        angle: 45,
        enabled: true
    }
}

Border.needsOverlay(spec) determines whether the specification requires the overlay renderer based on gradient presence or width asymmetry.

Implementing BorderSurface in QML

To render a themed border surface, import the Omarchy Commons module and bind a generated specification to the borderSpec property:

import QtQuick 2.15
import qs.Commons

Rectangle {
    width: 200
    height: 100
    radius: 6

    BorderSurface {
        anchors.fill: parent
        borderSpec: Border.surfaceSpec(
            "panel", 
            "border", 
            Color.accent, 
            1, 
            "border-alpha"
        )
        padding: 8    // Content inset from border edge
        
        Column {
            anchors.centerIn: parent
            Text { text: "Themed Panel" }
        }
    }
}

Key implementation details:

• borderSpec accepts any specification object returned by Border.surfaceSpec, Border.controlSpec, or Border.hyprlandActiveSpec
• padding creates interior space between the border edge and child content
• The component automatically falls back to native Rectangle borders when possible for optimal performance

Practical Examples from the Omarchy Codebase

Button Backgrounds

In shell/Ui/Button.qml, BorderSurface provides the clickable background:

BorderSurface {
    id: bg
    anchors.fill: parent
    borderSpec: Border.surfaceSpec(
        "button", 
        "border", 
        Color.background, 
        1
    )
}

Menu Panels

The menu system in shell/plugins/menu/Menu.qml uses themed borders for panel chrome:

BorderSurface {
    id: menuBg
    anchors.fill: parent
    borderSpec: Border.surfaceSpec(
        "menu", 
        "border", 
        Color.background, 
        1
    )
}

Asymmetric Border Widths

For panels requiring different border widths per side, the theme can define border-width = "3 0 3 0" (top right bottom left). BorderSurface automatically detects the non-uniform widths and instantiates BorderOverlay to render the complex geometry:

BorderSurface {
    borderSpec: Border.surfaceSpec(
        "panel", 
        "border", 
        Color.accent, 
        2
    )
    // Theme overrides specific sides via border-width-top, etc.
}

Rendering Strategy and Performance

BorderSurface optimizes rendering paths based on specification complexity:

Hardware-accelerated path: When Border.needsOverlay(spec) returns false (uniform widths, solid color, no gradient), the component sets Rectangle.border properties on its internal rectangle instance. This uses the graphics driver's native border rendering.

Shape-based path: For gradients or asymmetric widths, the component loads BorderOverlay.qml, which constructs a QML Shape with PathLine and PathArc elements to draw the border geometry with precise gradient stops or varying stroke widths.

This dual-path approach ensures complex themed borders render correctly while maintaining performance for standard use cases.

Summary

• BorderSurface in shell/Ui/BorderSurface.qml renders themed borders with automatic complexity detection
• Border.qml provides factory functions like surfaceSpec() to convert shell.toml tokens into structured specifications
• Theme tokens include border, border-width, border-alpha, and border-gradient under section headers like [panel]
• The component automatically selects between native Rectangle borders and BorderOverlay Shape rendering based on specification requirements
• Import qs.Commons to access the Border singleton and Color references in your QML files

Frequently Asked Questions

What is the difference between BorderSurface and a standard Rectangle?

A standard Rectangle accepts only uniform border.color and border.width with no gradient support. BorderSurface accepts a structured borderSpec object that supports per-side width variations, gradient borders, and theme token resolution, delegating to BorderOverlay when native Rectangle capabilities are insufficient.

How do I define custom border widths in the theme?

In your theme's shell.toml, use the [panel] section (or relevant widget section) to specify border-width as either a single integer for uniform borders or a space-separated string of four integers representing top, right, bottom, and left widths (e.g., border-width = "2 0 2 0").

When does BorderSurface use BorderOverlay instead of native rendering?

BorderSurface loads BorderOverlay when the border specification contains a gradient, when per-side widths differ (asymmetric borders), or when the alpha channel requires special compositing. Uniform solid borders use the native Rectangle border properties for better performance, as determined by Border.needsOverlay().

Can I use BorderSurface without importing the Omarchy Commons module?

No. BorderSurface requires the Border singleton from qs.Commons to resolve theme tokens into valid border specifications. While you could theoretically construct a specification object manually, the component is designed to work within the Omarchy theme system, relying on Border.surfaceSpec() or similar factory functions to ensure consistency with the active theme.

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