From d603a2f66e153d49fac014702216ec714f9901bd Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 11 Aug 2026 03:02:17 -0400 Subject: [PATCH] docs(playbook): cache-bypass on the live gate + trim-don't-delete on upstreamed blocks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two lessons from the Theme 0.4.0 rollout across five apps. Live gate: after a kit-CSS change a normal reload can serve the cached previous layout.css while the server serves the new one. .btn then computes at Bootstrap's 16px — the exact signature of a failed upstreaming — so the natural response is to restore the local rule just deleted, entrenching the duplication the change removed. Hard-reload before trusting any computed-style probe. Upstreaming: the kit ships sizing only, so trim the local .btn rather than deleting it. mxgw's block also carried border-radius/font-weight/white-space, which a wholesale delete would have dropped silently; three of five apps' blocks were pure sizing and safe to delete outright, and the difference is invisible without diffing. Also records why a retained border-radius must stay a literal. Marks the .btn block as upstreamed in 0.4.0 rather than a candidate. --- admin_ui_cleanup.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/admin_ui_cleanup.md b/admin_ui_cleanup.md index 782e5c1..b4187d1 100644 --- a/admin_ui_cleanup.md +++ b/admin_ui_cleanup.md @@ -236,10 +236,20 @@ foundation branch merges — all branches build independently and compose at mer .btn-group-sm > .btn, .btn-sm { --bs-btn-font-size: .78rem; --bs-btn-padding-y: .25rem; --bs-btn-padding-x: .6rem; } ``` - This normalizes every unsized button app-wide without touching call sites. **Upstreaming - candidate**: this block is now duplicated in ignitionoee `app.css` and OtOpcUa `site.css`; when a - `ZB.MOM.WW.Theme` release ships a `.btn` rule, delete the local copies (both files carry a header - comment saying exactly this). + This normalizes every unsized button app-wide without touching call sites. **Upstreamed in + `ZB.MOM.WW.Theme` 0.4.0** — the kit now ships this block in `layout.css`, after all five apps had + independently written it. On bump to 0.4.0+ it arrives automatically, so remove the local copy in + the same change or the rule is declared twice. + + **Trim the local block, don't delete it wholesale.** The upstreamed rule covers *sizing* only — + the four `--bs-btn-*` variables and the `.btn-group-sm > .btn, .btn-sm` rule. A local `.btn` may + also carry app-specific *shape* declarations that predate the sweep and that the kit does not + ship; mxgw's carried `border-radius: 5px; font-weight: 500; white-space: nowrap`, and a wholesale + delete would have silently dropped all three. Diff your block against the kit's before removing + anything: three of the five apps' blocks were pure sizing and safe to delete outright, one was + not, and the difference is invisible unless you look. Note also that a retained `border-radius` + should stay a **literal** rather than becoming `--bs-btn-border-radius` — `.btn-sm` redefines + that variable, so the switch would shrink small buttons to Bootstrap's small radius. 3. **Phantom tokens → a real class**, not a token alias. OtOpcUa's pattern: `.notice-alert { color: var(--bad); background: var(--bad-bg); border-color: var(--bad-border); }` then migrate the inline `style="border-color:var(--alert)"` hacks to the class in the page @@ -344,7 +354,15 @@ dies at setup and never enqueues. That is a rig capability ceiling — don't man don't claim the sites you couldn't reach. Rebuild/redeploy the app's dev rig (**all** instances behind the load balancer — round-robin serves -you the stale one otherwise), then walk: +you the stale one otherwise), then **hard-reload** and walk the checks below. + +**The cache bypass is not optional, and skipping it inverts the result.** After a kit-CSS change +(a `ZB.MOM.WW.Theme` bump, a new rule in `layout.css`), a normal reload can serve the *previous* +version of `layout.css` from cache while the server is serving the new one correctly. The symptom +is precisely the signature of a failed change — HistorianGateway saw `.btn` computing at +Bootstrap's 16px, exactly what an unreached override looks like — so the natural next move is to +"fix" it by restoring the local rule you just deleted, entrenching the duplication the change +removed. Hard-reload first; only then trust a computed-style probe. 1. Computed-style probes (one `javascript` eval): a `.btn`'s `font-size` vs body; the phantom-token replacement class resolving to real colors; the scoped bundle present in `document.styleSheets`.