Skip to content

Making Themes

Here we will walk you through the process of making themes for HyDE step by step. This tutorial will work for both hyprdots and HyDE.

Quick Start Guide

Clone the hyde-theme-starter repo into your themes directory, feel free to rename MyTheme to your theme name

Terminal window
git clone https://github.com/richen604/hyde-theme-starter ~/MyTheme
  1. Required components - all must be in tar.* format:

  2. A collection of wallpapers that match your desired style/color scheme

    • Wallhaven - For wallpapers
    • farbenfroh.io - For color match wallpapers if you have a desired color scheme in mind
    • Don’t add too many wallpapers, 8-10 is a good number
  3. Install just for running helper scripts yay -S just

    • cd into your theme directory cd ~/MyTheme
    • Change your theme name in justfile
    • Run just init to generate initial directory structure

Your theme should have the following structure:

Terminal window
~/MyTheme/
├── Config/ # Part of your final theme - Configuration files
└── hyde/
└── themes/
└── MyTheme/ # main theme directory
└── wallpapers/
├── refs/ # for reference files we generate
├── screenshots/ # for screenshots of your theme
├── Source/ # Part of your final theme - Arcs ie. gtk, cursor, icon, font
└── arcs/
├── .gitignore
├── justfile # for running helper scripts
└── README.md # links to this webpage

Arcs

Arcs are the GTK theme, icon, cursor, and font components that make up parts of your theme. Lets add these right away to the Source/arcs directory so they are ready for testing.

Your folder structure should look something like this:

Terminal window
~/MyTheme/
├── Source/
└── arcs/
├── Gtk_<Your-GTK-Theme>.tar.*
├── Cursor_<Your-Cursor-Theme>.tar.*
└── Icon_<Your-Icon-Theme>.tar.*
└── Font_<Your-Font-Name>.tar.*

Make sure to use the correct prefix for each arc. eg. Gtk_<Your-GTK-Theme>.tar.*

Viewing your theme with Wallbash

Copy your wallpapers to your theme directory

Terminal window
cp -r ~/wallpapers ~/MyTheme/Config/.config/hyde/themes/MyTheme/wallpapers

cd into your theme directory

Terminal window
cd ~/MyTheme

install your theme

Terminal window
just install

Testing your theme with wallbash

There are two ways to initialize your theme. from wallbash or from an existing theme.

We are going to use wallbash for this guide. as it gives you a good understanding of how wallbash generates the colors for your theme. You can learn more about wallbash here.

Open Wallbash, setting auto, dark, or light (Meta + Shift + R).
Set your chosen wallpaper as the current wallpaper (Meta + Shift + W)

Observe how wallbash adapts the colors to your wallpaper for the following applications:

  • GTK (nwg-look)
    • to test your arc gtk theme, change from wallbash mode to theme mode (Meta + Shift + R)
    • then check pavucontrol to see if your gtk theme looks weird. if it does, follow the instructions in Generate GTK4 to generate GTK4 theme files using wallbash
  • Kitty (kitty)
  • QT (qt5ct + qt6ct)
  • Waybar (waybar)
  • Spotify (spotify)
  • VSCode (code) - needs wallbash enabled as color theme
  • Cava (cava)

Generate theme files

Make sure the wallpaper you picked is the best wallpaper that wallbash generates for your theme.
Now run the following commands to generate the wallbash files.

Terminal window
just gen-all
just set-wall

You’ll see a bunch of new files in your theme refs directory.

Terminal window
~/MyTheme/
├── refs/ # for reference files we generate
├── gtk-4.0/ # GTK4 theme files
├── gtk.css # Light theme
└── gtk-dark.css # Dark theme
├── kvantum/ # Kvantum theme files
├── kvantum.theme # Kvantum theme config
└── kvconfig.theme # Kvantum config
├── hypr.theme # Hyprland theme
├── kitty.theme # Kitty terminal theme
├── rofi.theme # Rofi theme
├── theme.dcol # wallbash "theme" mode overrides
└── waybar.theme # Waybar theme
└── wall.set # First wallpaper theme uses

You can copy all the files to your Config/.config/hyde/themes/MyTheme directory.

Terminal window
cp -r ./refs/* ./Config/.config/hyde/themes/MyTheme

run install again to update your theme

Terminal window
just install

These files are used to set the “theme” mode for your theme. (Meta + Shift + R)

Editing *.theme files

Take a look at your theme files

  • Each *.theme file contains configuration lines

  • The first line has the format: file_path | command_to_execute

    • hypr.theme - $HOME/.config/hypr/themes/theme.conf|> $HOME/.config/hypr/themes/colors.conf
    • kitty.theme - $HOME/.config/kitty/theme.conf|killall -SIGUSR1 kitty
    • rofi.theme - $HOME/.config/rofi/theme.rasi
    • waybar.theme - $HOME/.config/waybar/theme.css|${scrDir}/wbarconfgen.sh
  • hypr.theme:

    • Becomes $HOME/.config/hypr/themes/theme.conf
    • Edit the variables for arcs, must match the name of the folder inside each arc in Source/arcs
    • You can use hypr.theme to set additional programs for your theme. such as SDDM or Vscode theme
    • example: Bad Blood hypr.theme

Any updates to your theme in either Config or Source should be run with just install to update your theme.

Editing theme.dcol

The theme.dcol file is used to override some generated wallbash colors for wallbash modes. Check out understanding wallbash for more information.

This file is entirely optional

Finalizing your theme

Your theme should now be ready to be added to the hyde-gallery!
A few more finishing touches:

  • Add some screenshots to ~/screenshots
  • Add your theme to the Hyde-Gallery

In your theme directory, generate the readme using

Terminal window
python3 generate_readme.py

Initialize git

Terminal window
git init && git branch -M main && git add . && git commit -m "My first HyDE theme"

create a github repo

Terminal window
git remote add origin <your-repo-url>
git push -u origin main

Fork hyde-gallery https://github.com/HyDE-Project/hyde-gallery
Add your theme to the list and hyde-themes.json

More Information

Generate GTK4 from wallbash

If your theme doesn’t include GTK4 support, pavucontrol and other GTK4 applications may appear with a plain white theme.

Run the following command to generate the GTK4 theme files

Terminal window
just gen-gtk4

Copy the refs/gtk-4.0 directory to your theme directory

Terminal window
mkdir -p ./Config/.config/hyde/themes/MyTheme/gtk-4.0
cp -r ./refs/gtk-4.0/* ./Config/.config/hyde/themes/MyTheme/gtk-4.0/

Understanding wallbash

Wallbash generates 4 primary colors from your wallpaper, then creates color groups around each primary color with the following structure:

For each primary color (wallbash_pry1 through wallbash_pry4):

  • Text color (wallbash_txt1 through wallbash_txt4)
  • 9 accent colors (wallbash_1xa1 through wallbash_1xa9 for group 1, etc.)

Each color has an RGBA variant with configurable opacity (e.g. wallbash_pry1_rgba(0.95))

Total: 44 base colors (4 groups × 11 colors) plus RGBA variants

Use just gen-dcol to generate a theme.dcol with all the wallbash generated colors for your active wallpaper for reference