docs(gtk): record the derived-tint rule and its ceiling

The README said derived tints were left alone, which was true for an hour and
is now wrong for twelve of them. Records which widget each paints, what it
became, and why shade() keeps the relationship rather than the upstream value.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 33 insertions, 2 deletions

diff --git a/templates/gtk/README.md b/templates/gtk/README.md
index adfc092..2af1a38 100644
--- a/templates/gtk/README.md
+++ b/templates/gtk/README.md
@@ -33,11 +33,42 @@ Neutral greys and upstream's derived tints: `#3e4152`, `#2e3143`, the
 Material swatch constants, which ship with every build and are not theme
 colour. Same rule as the Kvantum SVG: shading is not palette.
 
-Two derived values are mapped anyway, because they are semantic rather than
-shading: `17, 17, 27` (Latte crust, used as text on the accent) becomes
+Two decimal-triple values are mapped anyway, because they are semantic rather
+than shading: `17, 17, 27` (Latte crust, used as text on the accent) becomes
 `bg_deep`, and `182, 106, 119` (a darkened red on the close button) becomes
 `critical`.
 
+## Derived tints
+
+Twelve hexes are shades upstream computed from a palette colour rather than
+taking one, and each paints exactly one widget surface. Leaving them literal,
+which is the right rule for the neutral greys, left twelve Macchiato-tinted
+spots on every other scheme, including the window close, minimise and maximise
+hover fills. They are substituted as `@ROLE_PCT@`, where the percentage is that
+shade's brightness relative to its base, measured off the Macchiato theme these
+came from.
+
+| Was | Paints | Now |
+| --- | --- | --- |
+| `#a0a8f6` | infobar hover | `accent` at 93% |
+| `#bfc5f8` | selected progress bar (GTK3 only) | `accent` at 103% |
+| `#d3d7fb` | selection-mode titlebar backdrop (GTK3 only) | `accent` at 109% |
+| `#e5e8fd` | check and radio, checked and hovered | `accent` at 118% |
+| `#eea2ae` / `#ea7183` / `#e55267` | infobar, window close active | `critical` at 110/92/79% |
+| `#eedbb5` / `#eaca89` / `#e5bd6b` | infobar, window minimise active | `warning` at 105/94/86% |
+| `#b8e0ad` / `#80ca68` | infobar, window maximise active | `success` at 109/81% |
+
+`shade()` scales each channel and clamps at 255, so it keeps the relationship
+rather than reproducing the upstream value exactly. It is closest on the accent
+family and crudest on the reds, where upstream darkened toward saturation and a
+flat channel scale darkens toward grey. That is a deliberate ceiling: these are
+low-traffic surfaces, and a per-tint hand-tuned value for nine schemes would be
+108 numbers to maintain.
+
+`#e5e8fd` is read as the accent pushed near-white rather than as `fg`, which it
+is numerically closer to, because it backs a checked-and-hovered check box
+whose glow is already an accent tint.
+
 ## Assets
 
 67 SVGs, carrying only three palette colours: `bg`, `bg_alt` and the accent,