Document the GTK button-style override, and why srdwm does not write it

Firefox and Nemo were reported as still showing traffic lights after the
button side was fixed. Neither was srdwm's doing.

Nemo, and every GTK app: ~/.config/gtk-3.0/gtk.css contained a deliberate
override from 2026-08-22 painting each titlebutton as a glossy macOS dot,
with the glyph hidden by opacity: 0. Its own comment records that it was
added when srdwm's own decoration drew traffic lights, so that every window
matched. srdwm's style has since changed to traditional and the stylesheet
was still enforcing the old look.

Firefox was already on its traditional variant, byte-identical to
userChrome-traditional.css with the legacy stylesheet pref enabled. It needs
only a Firefox restart.

A first attempt at the GTK fix produced invisible buttons, confirmed by
screenshot: clearing the coloured backgrounds and un-hiding the child image
left blank space, because WhiteSur paints the control as the button's own
background-image from its compiled gresource and there is no child image to
reveal. The working version supplies the icon explicitly via
-gtk-icontheme(). Verified by screenshot: Nemo's header now draws a dash, a
square and an X directly under srdwm's own titlebar drawing the same three.

Kept as a swappable pair, gtk-traditional.css and gtk-traffic-lights.css,
matching the convention Firefox's chrome directory already uses.

srdwm publishes the button layout itself but deliberately does not write
this CSS: the file is the user's, already held hand-written work, and a
compositor silently overwriting it would destroy customisation it cannot
understand.

1 files changed, 31 insertions, 6 deletions

diff --git a/docs/DEFAULTS.md b/docs/DEFAULTS.md
index 1b8d869..217075b 100644
--- a/docs/DEFAULTS.md
+++ b/docs/DEFAULTS.md
@@ -1052,10 +1052,35 @@ setting: buttons moved from x=25/49/73 (left) to x=817/841/865 (right),
 landing in the same place and the same order as srdwm's own titlebar buttons
 directly above them.
 
-### What still cannot match
+### Button style: a user CSS override
+
+srdwm's `button_style` draws srdwm's own titlebar. A GTK app draws its own
+buttons from its GTK theme, and no compositor setting reaches those - but
+the theme is not the last word either. A user stylesheet at
+`~/.config/gtk-3.0/gtk.css` (and the GTK 4 equivalent) loads *after* the
+theme and can restyle the controls to match.
+
+One trap makes this harder than it looks. A theme may paint the control as
+the button's own `background-image` rather than as a child `image` widget.
+WhiteSur does, from its compiled `gtk.gresource`, so simply clearing the
+background leaves a button with nothing drawn in it at all - the coloured
+dots vanish and are replaced by blank space, not by glyphs. The icon has to
+be supplied explicitly:
+
+```css
+headerbar button.titlebutton.close {
+  background-image: -gtk-icontheme("window-close-symbolic");
+  background-repeat: no-repeat;
+  background-position: center;
+  background-size: 16px 16px;
+}
+```
+
+Keeping the alternatives as separate files and copying one over `gtk.css`
+makes switching a one-line operation, and is the same arrangement Firefox's
+own `chrome/` directory uses for `userChrome-traditional.css` versus
+`userChrome-traffic-lights.css`.
 
-The button *style*. srdwm's `button_style` draws srdwm's own titlebar; a
-GTK app draws its buttons with its GTK theme. Position and order can be made
-identical, as above; whether they are flat glyphs or coloured dots is the
-GTK theme's decision. On WhiteSur-Dark they are macOS-style dots by design.
-Changing that means changing the GTK theme.
+Firefox is a separate surface again: it draws its window buttons itself and
+takes them from `userChrome.css`, which needs
+`toolkit.legacyUserProfileCustomizations.stylesheets` set to `true`.