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.

2 files changed, 73 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`.
diff --git a/docs/TODO.md b/docs/TODO.md
index 29a8d9c..74eed81 100644
--- a/docs/TODO.md
+++ b/docs/TODO.md
@@ -1,5 +1,47 @@
 # TODO / planned features - master checklist
 
+## Firefox and Nemo's traffic lights: the compositor was never drawing them (2026-08-28)
+
+Reported as still using traffic lights after the button *side* was fixed.
+Traced to configuration the user already had, not to srdwm.
+
+**Nemo, and every other GTK app:** `~/.config/gtk-3.0/gtk.css` (and the GTK
+4 copy) contained a deliberate override, written on 2026-08-22, painting
+each titlebutton as a glossy macOS dot - `radial-gradient` fills in
+ff5f57/ffbd2e/28c840, with the glyph explicitly hidden by `opacity: 0`. Its
+own comment records why: at the time srdwm's own decoration drew traffic
+lights, and this was added so every window matched. srdwm's style has since
+been changed to `traditional`, and the stylesheet was still enforcing the
+old look.
+
+**Firefox:** already on the traditional variant - `userChrome.css` is
+byte-identical to `userChrome-traditional.css`, and
+`toolkit.legacyUserProfileCustomizations.stylesheets` is `true`. It needs a
+Firefox restart, nothing more.
+
+**What the fix needed that a first attempt got wrong.** Clearing the
+override's coloured backgrounds and un-hiding the child `image` produced
+*invisible* buttons, confirmed by screenshot: blank space where the dots had
+been. WhiteSur paints the control as the button's own `background-image`,
+from its compiled `gtk.gresource` rather than any editable CSS file, so
+there is no child image to reveal. The working version supplies the icon
+explicitly with `-gtk-icontheme("window-close-symbolic")` and friends.
+
+Verified by screenshot: Nemo's own header now draws a dash, a square and an
+X, monochrome, on the right, directly under srdwm's own titlebar drawing the
+same three in the same style.
+
+Left as a swappable pair, matching the convention the Firefox chrome
+directory already uses: `gtk-traditional.css` (now active as `gtk.css`) and
+`gtk-traffic-lights.css` (the previous look, preserved).
+
+**Deliberately not automated.** srdwm publishes the button *layout* itself,
+because that is a single well-defined desktop setting with an obvious
+mapping from `button_side`. It does not write GTK CSS: that file is the
+user's, it already contained hand-written work, and a compositor silently
+overwriting it would destroy customisation it cannot understand. The
+mechanism is documented in `DEFAULTS.md` instead.
+
 ## The real cause of "windows spawn as squares": window memory was poisoning itself (2026-08-28)
 
 Reported again after a restart that already had the placement fixes live, so