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, 42 insertions, 0 deletions

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