Understanding Omarchy Theme Components: Colors and Typography Explained

An Omarchy theme consists of a 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 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, 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

# 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.

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:

[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 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 – Replaces the entire generated shell configuration
• shell.lock.toml – Overrides only the lock screen section (lines 84-90 in docs/theming.md)

# 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 exists, generating one from 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:

# 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 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 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 or shell.lock.toml in your theme directory. According to 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.

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