Creating Your Own Theme

🛠 Theme Architecture

File Structure

• Directory~/.local/share/pawlette/themes/

  • Directorytheme-name/

    • Directoryconfigs/

      • Directorykitty/

        • kitty.conf
        • kitty.conf.prepaw (patch file)
      • Directorywaybar/

        • config.json
        • style.css
      • Directoryhypr/

        • …
      • Directoryrofi/

        • …
      • Directorybspwm/

        • …
      • Directorydunst/

        • …
      • Directorybtop/

        • …
      • Directorycava/

        • …
      • Directoryfish/

        • …
      • Directoryzsh/

        • …
      • Directorystarship/

        • …
      • Directorytmux/

        • …
      • Directorymicro/

        • …
      • Directoryqt5ct/

        • …
      • Directoryqt6ct/

        • …
      • Directorypolybar/

        • …
      • Directorymeowrch-code-theme/

        • …
    • Directorygtk-theme/ (GTK theme)

      • …
    • Directoryicons/ (icon pack)

      • Directorycursors/ (cursor themes)

        • …
      • Directoryhyprcursors/ (cursor themes for Hyprland)

        • …
    • Directorywallpapers/ (desktop wallpapers)

      • …

🔧 Patch System

Pawlette supports two modes of configuration application:

Full Replacement

Regular configuration files will completely replace existing settings.

Partial Changes (Patches)

Patch suffixes

• .prepaw — content is added before the original configuration
• .postpaw — content is added after the original configuration
• .jsonpaw — JSON object is merged into the target JSON file (deep merge; applied before .prepaw/.postpaw)

JSON merge (.jsonpaw)

If the target file is JSON, you can place a file next to it with the .jsonpaw suffix (e.g. waybar/config.json.jsonpaw). Its content must be a JSON object; it will be merged into the target file:

• existing keys are overridden by .jsonpaw values;
• missing keys are created;
• nested objects are merged recursively.

Example:

Original ~/.config/waybar/config.json:

{
  "layer": "bottom",
  "modules-left": ["menu"],
  "style": { "font": "Sans 10" }
}

Patch configs/waybar/config.json.jsonpaw:

{
  "layer": "top",
  "style": { "font": "JetBrainsMono 11", "color": "#cba6f7" },
  "custom-key": true
}

Result:

{
  "layer": "top",
  "modules-left": ["menu"],
  "style": { "font": "JetBrainsMono 11", "color": "#cba6f7" },
  "custom-key": true
}

Example: the file kitty/kitty.conf.prepaw will add its content to the beginning of the existing kitty.conf.

How to Create Your Own Theme?

1. Create Structure

   Create a directory for your theme:

   mkdir -p ~/.local/share/pawlette/themes/my-theme
   cd ~/.local/share/pawlette/themes/my-theme
   mkdir -p configs wallpapers gtk-theme icons

2. Add Configurations

   Create configurations for the required applications:

   # Example for kitty
   mkdir -p configs/kitty
   cat > configs/kitty/kitty.conf << EOF
   foreground #ffffff
   background #1a1a1a
   cursor #ffffff
   EOF
   
   # Example patch for waybar
   mkdir -p configs/waybar
   echo '* { border-radius: 10px; }' > configs/waybar/style.css.prepaw

3. Add Resources

   • Place GTK theme in gtk-theme/ folder
   • Add icons to icons/ folder
   • For custom cursors create icons/cursors/ and icons/hyprcursors/ folders (for Hyprland)
   • Place wallpapers in wallpapers/ folder

4. Apply Theme

   Apply your new theme:

   pawlette set-theme my-theme