Testing Omarchy Theme Changes with `omarchy dev theme-preview`

The omarchy dev theme-preview command is a Bash utility that renders Omarchy theme color palettes as terminal swatches, calculating WCAG contrast ratios and optionally applying the palette via OSC sequences to preview changes instantly.

When customizing Omarchy appearances, developers need rapid visual validation of color choices without restarting their desktop session. The omarchy dev theme-preview utility in the omacom/omarchy repository provides terminal-based palette visualization that validates hex codes, computes accessibility metrics, and leverages the same colors.toml definitions used by the underlying theming system documented in docs/theming.md.

How the Preview Script Works

The preview logic in bin/omarchy-dev-theme-preview executes a three-stage pipeline to transform raw theme definitions into visual output.

Resolving the colors.toml File

The script first determines which color definition file to load through the resolve_colors_file function (lines 65-84). This resolver accepts multiple input types: a theme name (which maps to themes/<name>/colors.toml), a directory path, or an explicit file path. If no argument is provided, the script falls back to the currently active theme configuration, ensuring developers can quickly test iterative changes without specifying paths repeatedly.

Loading Colour Definitions

Once the file is identified, the load_colors function (lines 98-110) invokes the omarchy-theme-color helper to parse the TOML structure. This loads both raw color values and fully-resolved palette variables into an associative array, including dark-mode variants such as dark_background and darker_background as defined in the Omarchy theming specification. The script stores these values for rendering while maintaining the semantic relationships between theme variables.

Rendering Swatches and Contrast Ratios

The final stage generates visual output through several specialized helper functions. The swatch function (starting at line 92) prints colored blocks of configurable width directly to the terminal. For accessibility validation, the contrast_ratio function (lines 38-56) calculates WCAG-compliant contrast ratios between foreground and background colors, while hex_valid (lines 27-29) ensures all color values conform to the #RRGGBB format before processing.

Terminal Palette Integration

Beyond static swatches, the script can temporarily reconfigure your terminal's actual color palette to match the theme being previewed. The apply_terminal_osc function (lines 77-88) calls omarchy-theme-osc to emit Operating System Command (OSC) escape sequences when stdout is a TTY. This behavior is controlled via command-line flags: --osc forces palette application even when piping output, while --no-osc suppresses it entirely. The --no-color flag disables all ANSI output for plain-text testing.

Usage Examples

Preview the currently active theme without arguments:

omarchy dev theme-preview

Test a specific theme by name:

omarchy dev theme-preview tokyo-night

Validate a custom colors.toml file directly:

omarchy dev theme-preview themes/gruvbox/colors.toml

Disable color output for accessibility testing in plain text:

omarchy dev theme-preview --no-color

Suppress OSC terminal palette changes while keeping colored swatches:

omarchy dev theme-preview --no-osc

Force OSC application even when redirecting output:

omarchy dev theme-preview --osc

Summary

• The omarchy dev theme-preview command validates and visualizes theme palettes directly in the terminal using the same colors.toml files that configure the Omarchy desktop environment.
• Key functions include resolve_colors_file for path resolution, load_colors for parsing TOML definitions, and contrast_ratio for WCAG accessibility calculations.
• The script optionally applies themes to your terminal emulator via OSC sequences through omarchy-theme-osc, providing immediate visual feedback without session restarts.
• Developers can target specific themes, directories, or explicit files while controlling output formatting with --no-color, --osc, and --no-osc flags.

Frequently Asked Questions

How does omarchy dev theme-preview handle invalid color definitions?

The script validates all color values through the hex_valid function (lines 27-29 of bin/omarchy-dev-theme-preview), which enforces strict #RRGGBB formatting. Invalid hex codes will fail validation before rendering, preventing malformed palettes from generating misleading preview output.

Can I preview themes that are not installed in the standard themes/ directory?

Yes. The resolve_colors_file function accepts absolute or relative paths to any colors.toml file. You can pass the path directly as an argument (e.g., omarchy dev theme-preview /path/to/custom/colors.toml) regardless of whether the theme resides in the standard Omarchy themes directory.

What is the difference between --osc and --no-osc flags?

By default, the script automatically applies OSC sequences only when stdout is a terminal (TTY). The --osc flag forces this behavior even when piping or redirecting output, while --no-osc explicitly disables the OSC palette changes even in interactive terminals. Both flags control the apply_terminal_osc function (lines 77-88) independently of color swatch rendering.

Where does the preview script source its color resolution logic?

The preview utility delegates TOML parsing and color resolution to the omarchy-theme-color helper script, which extracts both raw values and resolved variables from colors.toml files. This ensures consistency with the broader Omarchy theming system documented in docs/theming.md, where templates use identical palette data to generate shell, Hyprland, and terminal configurations.

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