Material You GTK · Expressive

A Material 3 Expressive theme for GTK3, GTK4 and libadwaita. It follows your wallpaper through Matugen, and it looks the same whichever toolkit an app uses.

What you get

• Round, friendly buttons, switches, sliders, entries and menus in the Material 3 Expressive style, in light and dark.
• One set of colors for everything. When your wallpaper changes, Matugen rewrites colors.css and every app follows. The widget styling itself never has to change.
• The same look in GTK3 (adw-gtk3), plain GTK4 and libadwaita, plus flatpak apps.
• Readable text. Contrast is checked on several palettes in both modes.

Install

You need GTK 3.24 with adw-gtk3, GTK 4.20 or newer, and Matugen.

git clone https://code.milfs.party/alex/material-you-gtk.git
cd material-you-gtk
./install.sh --templates --settings --apply
./install.sh --flatpak        # optional: let flatpak apps see the theme

Your old files are backed up first (in ~/.local/state/material-you-gtk/backups/), and ./install.sh --uninstall puts them back. --dry-run shows what would happen.

It also keeps your existing colors.css, since that's your palette, not ours. Then point Matugen's GTK templates at colors.css (not gtk.css); there is a working example in matugen-templates/config.toml. Restart your apps and you're done.

If your dotfiles manage ~/.config/gtk-*, no problem: the installer writes through symlinks instead of replacing them.

Optional Nautilus preferences

./install.sh --nautilus-dots

This adds src/nautilus.css after the GTK4 theme: a darker accent-tinted sidebar, compact aligned headers with a faint gradient, flat breadcrumbs, separated view controls, and a full-width list header. It also includes the original dots' sidebar row hiding (rows 2–4, keeping Home and Trash visible). Those positional selectors may need adjusting if your Nautilus version uses a different sidebar order. Personal bookmarks and icon paths are not included.

The option is off by default; pass it again when reinstalling to keep these preferences. Reinstall without it to return to the standard theme. Material menus and higher-contrast table headers are part of the standard GTK4 theme.

Keep personal rules in ~/.config/gtk-4.0/custom.css (or the GTK3 equivalent). The installer imports an existing custom.css last and never overwrites it. It can be a symlink into your dotfiles, so bookmark icons and other personal rules survive theme updates. Existing inline customizations must be moved there before reinstalling. --uninstall restores the previous gtk.css, including its imports and optional rules.

GTK4 hot reload and system-update recovery

Arch Linux and CachyOS only. The GTK patch installer and pacman hooks do not work on other distributions. Regular CSS theme installation is separate.

Plain ./install.sh also offers to install hot reload and automatic pacman hooks after installing the theme on Arch/CachyOS. Answer y to build and install them, or press Enter to skip. This does not perform a system upgrade. Use --no-hook to skip the prompt. Noninteractive runs print the --hook command instead of prompting; dry runs only describe the offer.

If an older hot-reload setup blocks updates or Nautilus fails with undefined symbol: gtk_enum_list_item_get_value, update this repository and run:

git pull
./install.sh --update --hook

Run as your normal user. This backs up pacman.conf, removes only the gtk4 IgnorePkg hold, removes the old version-pinned companion, performs a full system upgrade, then rebuilds and installs the GTK source patch. Existing theme CSS, optional Nautilus styling and personal bookmarks remain intact.

For an already updated system, use ./install.sh --hook. Both commands install automatic pacman hooks: future GTK upgrades disable the old override, build and verify a matching patch, then enable hot reload again. If rebuilding fails, stock GTK remains active. Relaunch apps once after a GTK library update; later CSS edits reload live. --dry-run previews the installer steps.

The patch, recovery details, rollback instructions and separate Flatpak builds are in packages/gtk4-hot-reload.

Working on it

Edit the files in src/ (common.css is shared, gtk3.css and gtk4.css are per toolkit), then:

python3 scripts/build.py      # regenerate gtk-3.0/ and gtk-4.0/
python3 scripts/validate.py   # parse both CSS dialects, check assets and contrast
python3 scripts/test_install.py # isolated install, symlink and restore checks

To see it, run a nested compositor and point the screenshot scripts at its Wayland socket (never your real one):

python3 scripts/preview.py --display wayland-2     # gallery in every toolkit and mode
python3 scripts/demo_shots.py --display wayland-2  # GTK/libadwaita demo apps

Pictures and logs land in screenshots/.

Good to know

• CSS can't do spring physics, two-thumb sliders or value bubbles, so those are approximated or left to the toolkit.
• Plain GTK4 in light mode is only checked through the gallery, and GTK3 flatpaks can read the theme but I haven't seen one render.
• Apps with their own CSS or custom drawing may need a little extra work.

Thanks to adw-gtk3 and Materia for showing how to do this without breaking the toolkit, and to the Material 3 Expressive guidance for the design.