# Understanding Omarchy Theme Components: Colors and Typography Explained

> Explore Omarchy theme components including colors and typography. Learn how colors.toml and font configurations create stunning interfaces in the Omarchy theme.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-05

---

**An Omarchy theme consists of a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) palette file, a `[font]` configuration block defining the typographic scale, background assets, icon sets, and template files that render these components into final configuration files.**

Every theme in the omacom/omarchy repository follows a strict, modular architecture that separates visual design from configuration logic. The **Omarchy theme components** work together through a template rendering system that generates shell configurations, window manager settings, and terminal themes from a single source of truth.

## Core Color Palette Configuration

The foundation of any Omarchy theme is the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, which defines the complete color system used across all generated configurations.

### The colors.toml Structure

Located at `themes/<name>/colors.toml`, this file provides **semantic color tokens** that templates consume via `{{ key }}` placeholders. According to the source code in [`themes/nord/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/nord/colors.toml), the palette includes:

- **Mode and accent colors** – Defines the primary accent hue used for selections and highlights
- **Background and foreground shades** – Multiple intensities for layered UI elements
- **ANSI color mapping** – Named colors (red, green, blue, etc.) for terminal compatibility
- **Semantic tokens** – `selection`, `muted`, and other UI-specific identifiers

```toml

# Example from themes/nord/colors.toml

accent = "#81a1c1"
background = "#2e3440"
foreground = "#d8dee9"
red = "#bf616a"
green = "#a3be8c"

```

Templates reference these values using double-brace syntax. When the rendering engine processes `default/themed/hyprland.lua.tpl` or similar files, it substitutes `{{ accent }}` with the corresponding hex value from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml).

## Typography and Font Configuration

Unlike color definitions, **Omarchy theme typography** is configured through the `[font]` section inside `shell.toml.tpl` templates, specifically in `default/themed/shell.toml.tpl` (lines 101-118).

### The Font Block Structure

The typographic system revolves around a single **base-size** value that serves as the root `rem` unit:

```toml
[font]
base-size = 12          # Root size in points

scale-with-font = true  # Enable global UI scaling

```

From this base size, Omarchy automatically computes derived tokens:
- **caption** – Approximately 0.833x base size
- **body** – Base size (1x)
- **subtitle** – Approximately 1.083x base size  
- **heading** – Approximately 1.333x base size
- **display** – Approximately 2.0x base size

Themes can optionally override specific tokens without altering the base scale. Uncommenting `heading = 16` in the font block pins that specific token while maintaining the proportional relationships for other text elements.

## Background Assets and Icon Sets

Visual themes extend beyond colors and fonts into static assets and cursor themes.

### Required Asset Directories

- **backgrounds/** – Contains wallpaper images symlinked to `~/.local/state/omarchy/current/background`
- **preview.png** – Theme thumbnail displayed in selection interfaces
- **unlock.png** and **preview-unlock.png** – Lock screen-specific imagery

### Icon and Cursor Configuration

The `icons.theme` file defines the cursor set, while `keyboard.rgb` controls backlighting colors for supported hardware. These files are copied verbatim into the active theme directory at `~/.local/state/omarchy/current/theme` during activation.

## Template Files and Override Mechanisms

The **Omarchy theme components** include a powerful templating system that generates final configuration files from the palette and font definitions.

### Template Rendering Process

Files in `default/themed/*.tpl` (such as `shell.toml.tpl` and `hyprland.lua.tpl`) serve as blueprints. The renderer processes these templates against [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and the font base-size, producing finalized configs in `~/.local/state/omarchy/current/theme`.

### Hand-Written Overrides

Themes can bypass template generation entirely by shipping static configuration fragments:
- [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) – Replaces the entire generated shell configuration
- [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) – Overrides only the lock screen section (lines 84-90 in [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md))

```toml

# Example override in themes/<name>/shell.lock.toml

[lock]
text = "#ffffff"
border = "#ffffff"

```

This override file takes precedence over generated content for its specific section, allowing precise control without maintaining full configuration files.

## How Theme Components Work Together

The `bin/omarchy-theme-set` command orchestrates the assembly process when activating a theme:

1. **Validation** – Copies the theme directory and ensures [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) exists, generating one from [`config/alacritty/alacritty.toml`](https://github.com/omacom/omarchy/blob/main/config/alacritty/alacritty.toml) if necessary
2. **Rendering** – Processes all `*.tpl` files, substituting `{{ color_key }}` placeholders with values from the palette and computing font sizes from the `[font]` base-size
3. **Deployment** – Places rendered files and copied assets into the active state directory where the running shell immediately consumes them

### Advanced Template Functions

Templates support color manipulation functions for dynamic UI generation:

```toml

# Blend 15% foreground into background for subtle borders

border = "{{ mix background foreground 15% }}"

```

This generates a calculated hex value that maintains visual harmony with the base palette while creating hierarchical depth.

## Summary

- **colors.toml** defines the complete semantic color palette used by all templates in `omacom/omarchy`
- **Font configuration** in `shell.toml.tpl` uses a single `base-size` value to compute the entire typographic scale
- **Template files** (`*.tpl`) render final configurations by substituting `{{ }}` placeholders with palette values
- **Override files** like [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) allow themes to bypass generation for specific configuration sections
- **Asset directories** (`backgrounds/`, icon sets) are copied directly to the active theme state at `~/.local/state/omarchy/current/theme`

## Frequently Asked Questions

### How do I reference custom colors in an Omarchy theme template?

Use double-brace syntax with the key name from your [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file. For example, `border = "{{ accent }}"` renders as `border = "#81a1c1"` when processed against the Nord theme palette. The template engine substitutes these placeholders during the `omarchy-theme-set` activation process.

### What is the relationship between base-size and heading sizes in Omarchy typography?

The `base-size` value in `shell.toml.tpl` serves as the root unit (1rem) for all typographic calculations. Derived tokens like `heading` and `display` compute automatically as multiples of this base (approximately 1.333x and 2.0x respectively). Setting `scale-with-font = true` ensures the entire UI scales proportionally when you adjust the base size.

### Can I modify theme colors without editing the original colors.toml file?

Yes, you can create override files such as [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) or [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) in your theme directory. According to [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md), these hand-written files replace generated sections entirely, allowing you to specify exact hex values like `text = "#ffffff"` that take precedence over templated values.

### Where does Omarchy store the active theme configuration files?

After running `omarchy-theme-set <name>`, all rendered templates and copied assets reside in `~/.local/state/omarchy/current/theme`. The shell and window manager read configurations directly from this location, symlink backgrounds to `.../current/background`, and immediately apply changes without requiring manual file copying.