Creating Desktops

This guide walks you through creating a new desktop for Gtheme, from the initial skeleton to a fully themed configuration.

Quick start

Generate a skeleton

gtheme desktop new-skeleton my-desktop

This creates the following structure in ~/.config/gtheme/desktops/:

my-desktop/
├── desktop_config.json
├── desktop_info.toml
├── .config/
└── gtheme/
    ├── patterns/
    ├── post-scripts/
    └── extras/

Add your dotfiles

Copy your existing ~/.config/ files into the .config/ directory of your new desktop. Only include the files your desktop needs (window manager, status bar, terminal, etc.).

Fill in desktop metadata

Edit desktop_info.toml:

author = 'Your Name (@username)'
description = 'A short description of your desktop'
credits = 'https://link-to-inspiration'
dependencies = [
  'hyprland',
  'waybar',
  'kitty',
]
optional_dependencies = [
  'firefox',
  'alacritty',
]

Set a default theme

Edit desktop_config.json:

{
  "default_theme": "Dracula",
  "actived": {},
  "inverted": {}
}

Create patterns

For each config file that should change colors with the theme, create a pattern. See Writing Patterns for a detailed walkthrough.
Add post-scripts

For applications that need reloading, add a matching post-script. See Post-Script Specification.
Add extras (optional)

For theme-specific settings like wallpapers, add scripts to gtheme/extras/. See Extra Specification.

Enabling patterns

After creating patterns, register them in desktop_config.json:

{
  "default_theme": "Dracula",
  "actived": {
    "kitty": true,
    "waybar-colors": true,
    "rofi": true
  },
  "inverted": {
    "kitty": false,
    "waybar-colors": false,
    "rofi": false
  }
}

Testing your desktop

Apply the desktop:
Terminal window
```
gtheme desktop apply my-desktop
```

Try a few different themes:

gtheme theme apply Dracula
gtheme theme apply Nord
gtheme theme apply Catppuccin-Mocha

Check that all applications update their colors correctly.

Desktop exit script

If your desktop uses a window manager that needs to be stopped before switching to another desktop, create gtheme/post-scripts/desktop-exit.sh:

#!/bin/sh
sleep 1
killall -u $(whoami)
exit $?

To share your desktop, you can add it to the gtheme-desktops repository via a pull request, or distribute the desktop directory on its own.

Others can install it with:

gtheme desktop add /path/to/my-desktop