From 40e07aa08ebd63e9e84f09f1f096a44b2823061b Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Tue, 11 Aug 2026 03:22:24 -0400
Subject: [PATCH] =?UTF-8?q?docs(theme):=20correct=20the=20--rail-btn-inset?=
 =?UTF-8?q?=20comment=20=E2=80=94=20it=20reduces=20the=20duplication,=20it?=
 =?UTF-8?q?=20does=20not=20remove=20it?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The prior wording claimed the two rules 'cannot drift apart', which is only true
for the documented composition. 0.6rem still appears twice; the fallback confines
a stale copy to the undocumented modifier-alone path. Records why hoisting the
var to :root would be worse rather than better.
---
 .../src/ZB.MOM.WW.Theme/wwwroot/css/layout.css      | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/wwwroot/css/layout.css b/ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/wwwroot/css/layout.css
index 5283b09..2ab20e6 100644
--- a/ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/wwwroot/css/layout.css
+++ b/ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/wwwroot/css/layout.css
@@ -250,7 +250,18 @@
 
    calc() gets both right (measured 0px short for <a> and <button> alike). The
    inset is read from .rail-btn's own --rail-btn-inset rather than restated here,
-   so the two rules cannot drift apart if the rail inset ever changes.
+   so changing the rail inset there carries correctly into this width.
+
+   This REDUCES the duplication rather than removing it: 0.6rem still appears
+   twice — once as the declared value above, once as the fallback below — and
+   nothing keeps them in step. What changed is WHERE a stale copy can bite. The
+   documented `rail-btn rail-btn-block` composition resolves the var and follows
+   the real value; only the undocumented modifier-alone case can go stale. That
+   is the right place to leave it. The alternative — hoisting --rail-btn-inset to
+   a scope outliving the component (:root, .side-rail) — is worse: it makes a
+   component-private measurement look like a kit-wide token that apps may
+   reasonably override, and an app overriding it would silently resize a control
+   it never meant to touch.
 
    The 0.6rem fallback is NOT decoration. --rail-btn-inset is declared on
    .rail-btn, so it only resolves for the documented `rail-btn rail-btn-block`