docs(theme): correct the --rail-btn-inset comment — it reduces the duplication, it does not remove it

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.
This commit is contained in:
Joseph Doherty
2026-08-11 03:22:24 -04:00
parent 9dd288b3ad
commit 40e07aa08e
@@ -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`