Generate the GTK button stylesheet from button_style

Asked for after the previous entry declined to write GTK CSS. The objection
was to clobbering a file full of hand-written work, not to the feature, and
splitting ownership solves both.

srdwm owns srdwm-buttons.css, generated from
theme.decorations.title_bar.button_style and rewritten on every start and
config reload, and adds exactly one @import line to the user's gtk.css if it
is missing. Nothing else in that file is ever touched. The import goes first
because CSS only permits @import ahead of other rules, which also leaves the
user's own rules last and therefore able to override the generated style.

The generated CSS sets a background per button rather than un-hiding a child
image, for the reason the earlier hand-written attempt found by screenshot:
WhiteSur paints the control as the button's own background-image from a
compiled gresource, so clearing that background leaves a blank button rather
than revealing a glyph.

Verified end to end on a real GTK app, both directions, through the
generated file: traffic_lights gives Nemo coloured dots, traditional gives a
dash, a square and an X, each matching srdwm's own titlebar directly above
it. Also verified the import is added once and not duplicated, that
switching style rewrites only the generated file, and that a home without
GTK config directories has nothing written to it.

527 tests pass, clippy clean.

2 files changed, 57 insertions, 1 deletions

diff --git a/docs/DEFAULTS.md b/docs/DEFAULTS.md
index 217075b..014c6f5 100644
--- a/docs/DEFAULTS.md
+++ b/docs/DEFAULTS.md
@@ -1052,7 +1052,30 @@ 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.
 
-### Button style: a user CSS override
+### Button style: srdwm generates the CSS
+
+srdwm writes `~/.config/gtk-3.0/srdwm-buttons.css` (and the GTK 4 copy) from
+`theme.decorations.title_bar.button_style`, and rewrites it on every start
+and every config reload. It adds one line to your own `gtk.css`:
+
+```css
+@import url("srdwm-buttons.css");
+```
+
+That line is added once if missing and nothing else in the file is ever
+touched. The import sits first because CSS only allows `@import` before
+other rules - which also means your own rules come after it and win, so
+anything you write in `gtk.css` still overrides the generated style.
+
+Verified end to end on a real GTK app, both ways: with `button_style =
+"traffic_lights"` Nemo's own header draws coloured dots, and with
+`"traditional"` it draws a dash, a square and an X - in both cases matching
+srdwm's own titlebar directly above it.
+
+srdwm writes only its own file, and skips a GTK version whose config
+directory does not exist rather than creating one.
+
+### Doing it by hand instead
 
 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
diff --git a/docs/TODO.md b/docs/TODO.md
index 74eed81..18e551a 100644
--- a/docs/TODO.md
+++ b/docs/TODO.md
@@ -1,5 +1,38 @@
 # TODO / planned features - master checklist
 
+## srdwm now generates the GTK button stylesheet too (2026-08-28)
+
+The previous entry recorded a deliberate decision *not* to write GTK CSS,
+because the user's `gtk.css` holds hand-written work a compositor cannot
+safely rewrite. Asked to build it anyway, which is reasonable - the
+objection was to clobbering their file, not to the feature.
+
+The split solves both: srdwm owns `srdwm-buttons.css`, generated from
+`button_style` and rewritten on every start and reload, and adds exactly one
+`@import` line to `gtk.css` if it is missing. Nothing else in that file is
+ever touched. The import is first because CSS only permits `@import` ahead
+of other rules, which conveniently also leaves the user's own rules last and
+therefore winning.
+
+The generated CSS sets a background per button rather than un-hiding a child
+`image`, for the reason the previous attempt found the hard way: WhiteSur
+paints the control as the button's own `background-image` from a compiled
+gresource, so clearing the background leaves a blank button.
+
+Verified end to end on a real GTK app, both directions, through the
+generated file rather than a hand-written one: `traffic_lights` gives Nemo
+coloured dots, `traditional` gives it a dash, a square and an X, each time
+matching srdwm's own titlebar directly above. Also verified that the import
+is added once and not duplicated on a second run, that switching the style
+rewrites only the generated file, and that a home directory without GTK
+config directories has nothing written to it at all.
+
+Left in place: `gtk-traffic-lights.css`, the user's original hand-written
+override, kept as reference. `gtk.css` is now the import plus a comment
+saying what owns what.
+
+277 core tests, 527 total, clippy clean.
+
 ## 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.