Pattern Specification

Patterns are template files with color placeholders that Gtheme fills with values from the selected theme. They live in {desktop}/gtheme/patterns/.

Example

Here’s a kitty terminal pattern:

<[output-file]>=~/.config/kitty/colors.conf
# <[theme-name]> - Kitty colors (gtheme generated)

font_family <[default-font|GeistMono Nerd Font]>
font_size <[default-font-size|11]>

cursor                   #<[cursor]>
cursor_text_color        #<[foreground]>

foreground               #<[foreground]>
background               #<[background]>
selection_foreground     #<[selection-foreground]>
selection_background     #<[selection-background]>

# black
color0   #<[black]>
color8   #<[black-hg]>

# red
color1   #<[red]>
color9   #<[red-hg]>

# green
color2   #<[green]>
color10  #<[green-hg]>

# yellow
color3   #<[yellow]>
color11  #<[yellow-hg]>

# blue
color4   #<[blue]>
color12  #<[blue-hg]>

# magenta
color5   #<[magenta]>
color13  #<[magenta-hg]>

# cyan
color6   #<[cyan]>
color14  #<[cyan-hg]>

# white
color7   #<[white]>
color15  #<[white-hg]>

Placeholder syntax

All placeholders use the format <[property]>. Gtheme replaces them with the corresponding value from the theme’s [colors] section or the user’s user_settings.toml.

<[output-file]>=<path>

Mandatory. Specifies where the filled pattern is written. Must be on its own line with nothing else.

<[output-file]>=~/.config/kitty/colors.conf

Note

This line is removed from the generated output — it only tells Gtheme where to write the file.

<[color-name]>

Replaced with the hex color value from the theme (without # prefix). Add the prefix in your pattern as needed:

# With # prefix
foreground #<[foreground]>

# With 0x prefix
foreground: '0x<[foreground]>'

# With rgba() wrapper
$primary = rgba(<[blue]>ff)

<[property|fallback]>

Replaced with the value of a user setting from user_settings.toml. If the setting doesn’t exist, the fallback value is used:

font_family <[default-font|JetBrains Mono]>
font_size <[default-font-size|12]>

<[theme-name]>

Replaced with the name field from the current theme file:

# <[theme-name]> - Generated by Gtheme

Modules and sub-modules

If an application uses multiple config files, you can organize related patterns into a module — a directory inside patterns/:

patterns/
├── kitty.pattern
├── rofi.pattern
└── spotify/
    ├── spotify-colors.pattern
    └── spotify-theme.pattern

The directory name becomes the module name (spotify). When a module is filled, all sub-patterns inside it are filled too. Enabling or disabling a module affects all its sub-patterns.

Note

Modules can be nested — a sub-module can itself be a directory containing more patterns.

Caution

Pattern names must be unique within a desktop, even across modules. Two patterns that differ only in file extension are considered the same name.

Pattern inversion

Some themes have wallpapers whose colors clash with text foreground colors, making text hard to read. Inverting a pattern swaps:

• foreground ↔ background
• selection-foreground ↔ selection-background

Toggle inversion with:

gtheme pattern invert <pattern>

Inversion state is stored in desktop_config.json under the inverted key.