# How to Use BorderSurface with Omarchy Theme Tokens in QML

> Learn to use BorderSurface with Omarchy theme tokens in QML. Optimize backgrounds and borders with hardware-accelerated rendering or custom Shape overlays for complex designs.

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

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/shell.toml) (or `default/themed/shell.toml.tpl`) using a hierarchical token system:

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

```qml
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:

```javascript
{
    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:

```qml
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:

```qml
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:

```qml
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:

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