# Theming Omarchy Shell Borders with Gradients Using shell.toml

> Customize Omarchy shell borders with vibrant gradients by defining colors in colors.toml and applying them in shell.lock.toml. Elevate your shell's appearance today.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-11

---

**You configure gradient borders in Omarchy by defining rgba() color stops in your theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and referencing those values in [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) to override the default shell border colors.**

The omacom/omarchy repository provides a modern Linux desktop environment built on the Quickshell UI framework and configurable through TOML files. Theming Omarchy shell borders with gradients using [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) requires understanding how [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) defines color tokens and how [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) maps those tokens to specific border states for the Hyprland window manager.

## Understanding the Configuration Hierarchy

Omarchy resolves shell border styling through a two-layer configuration system located in each theme directory under `$OMARCHY_PATH/themes/<theme-name>/`.

### Base Color Definitions in colors.toml

The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file defines the base color palette and gradient tokens available to the shell. Key keys include `hyprland_active_border`, `hyprland_inactive_border`, and `active_border_color`.

Gradient syntax follows CSS-like notation using space-separated `rgba()` declarations. For example, in [`themes/tokyo-night/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/tokyo-night/colors.toml):

```toml
hyprland_active_border = "rgba(8a8588ee) rgba(e2dddcee)"
hyprland_inactive_border = "rgba(584e51aa)"
active_border_color = "#d6d3de"

```

### Shell-Specific Overrides in shell.lock.toml

The [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) file maps generic border keys to the color tokens defined in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). This layer allows themes to replace simple hex colors with gradient values for specific UI states.

Standard border keys include `border`, `border-active`, and `border-error`. In [`themes/tokyo-night/shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/themes/tokyo-night/shell.lock.toml):

```toml
border = "#a9b1d6"
border-active = "#a9b1d6"
border-error = "#a9b1d6"

```

To apply a gradient, reference the exact string defined in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml):

```toml
border-active = "rgba(8a8588ee) rgba(e2dddcee)"

```

## Gradient Syntax and Examples

Quickshell supports both two-stop linear gradients and angle-based gradients for border rendering.

### Two-Stop Linear Gradients

Define gradients by separating two rgba() declarations with a space. This creates a smooth transition between color stops along the window edge.

From the Tokyo-Night theme:

```toml

# themes/tokyo-night/colors.toml

hyprland_active_border = "rgba(8a8588ee) rgba(e2dddcee)"

```

Then activate it in your shell configuration:

```toml
border-active = "rgba(8a8588ee) rgba(e2dddcee)"

```

### Angle-Based Gradients

For diagonal gradients, append a degree value after the color stops. The Hackerman theme demonstrates this syntax:

```toml

# themes/hackerman/colors.toml

hyprland_active_border = "rgba(26a269ee) rgba(2ec27eee) 45deg"

```

Apply the angled gradient to shell borders:

```toml
border-active = "rgba(26a269ee) rgba(2ec27eee) 45deg"

```

## Runtime Border Resolution

When Quickshell initializes, it resolves border colors through the following sequence:

1. Quickshell reads the active theme from `$OMARCHY_PATH/themes/<theme>/`.
2. The engine loads [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) first, exposing keys like `hyprland_active_border`.
3. [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) is parsed next, mapping `border`, `border-active`, and `border-error` to the color tokens.
4. If the value contains multiple rgba() stops or an angle, Quickshell generates a linear gradient for the Hyprland window borders.
5. The computed color or gradient is applied to the window manager's border rendering layer.

## Disabling Outer Borders

To completely remove outer window borders regardless of gradient configuration, set `pane_outer_borders` to `false` in [`config/herdr/config.toml`](https://github.com/omacom/omarchy/blob/main/config/herdr/config.toml):

```toml
pane_outer_borders = false

```

This toggle overrides all theme-specific border settings.

## Summary

- **Color tokens** are defined in `themes/<theme>/colors.toml` using keys like `hyprland_active_border`.
- **Gradient syntax** uses space-separated `rgba()` values or appends angles like `45deg` for directional effects.
- **Shell overrides** occur in `themes/<theme>/shell.lock.toml` where `border-active` maps to color tokens.
- **Resolution order** loads [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) first, then applies [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) overrides before rendering via Quickshell.
- **Global disable** via `pane_outer_borders = false` in [`config/herdr/config.toml`](https://github.com/omacom/omarchy/blob/main/config/herdr/config.toml) removes borders entirely.

## Frequently Asked Questions

### What is the difference between colors.toml and shell.lock.toml?

The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file defines available color tokens and gradients for the entire theme, while [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) maps those tokens to shell UI elements like `border` and `border-active`. Quickshell reads [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) first to establish the palette, then uses [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) to determine which colors apply to specific border states.

### How do I create a custom two-color gradient for active borders?

Define the gradient in your theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) using two rgba() values separated by a space, then reference that string in [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) under the `border-active` key. For example, set `hyprland_active_border = "rgba(ff7f00ee) rgba(ff007fee)"` in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), then set `border-active = "rgba(ff7f00ee) rgba(ff007fee)"` in [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml).

### Does Omarchy support angled gradients for window borders?

Yes, the Quickshell engine supports angle-based gradients by appending a degree value after the color stops in your [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) definition. The Hackerman theme demonstrates this with `hyprland_active_border = "rgba(26a269ee) rgba(2ec27eee) 45deg"`, which creates a diagonal gradient across the window border.

### How do I completely disable window borders in Omarchy?

Set `pane_outer_borders = false` in the [`config/herdr/config.toml`](https://github.com/omacom/omarchy/blob/main/config/herdr/config.toml) file. This global configuration overrides all theme-specific border colors and gradients, effectively hiding window borders entirely.