From f0f607ea469246fd4f43c50c18c5c018fc035912 Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Mon, 10 Aug 2026 17:09:00 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20admin=5Fui=5Fcleanup.md=20=E2=80=94=20r?=
 =?UTF-8?q?eusable=20admin-UI=20sweep=20playbook=20(from=20the=20ignitiono?=
 =?UTF-8?q?ee=20router=20+=20OtOpcUa=20AdminUI=20rounds)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 admin_ui_cleanup.md | 187 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 187 insertions(+)
 create mode 100644 admin_ui_cleanup.md

diff --git a/admin_ui_cleanup.md b/admin_ui_cleanup.md
new file mode 100644
index 0000000..9e95f1a
--- /dev/null
+++ b/admin_ui_cleanup.md
@@ -0,0 +1,187 @@
+# Admin-UI cleanup playbook (`ZB.MOM.WW.Theme` + Bootstrap Blazor apps)
+
+A reusable sweep recipe for the family's Blazor Server admin UIs, distilled from two completed
+rounds:
+
+- **ignitionoee router** — `../ignitionoee/docs/plans/2026-08-05-router-ui-sweeps.md` (+ its
+  render-validation companion plan)
+- **OtOpcUa AdminUI** — `../OtOpcUa/docs/plans/2026-08-10-adminui-ui-sweeps.md`
+
+Both apps sit on **ZB.MOM.WW.Theme 0.3.1 + self-hosted Bootstrap 5.3**, and both sweeps found the
+same *classes* of defect with different instances. Run the discovery phase before assuming which
+instances your app has — the router had ghost layout classes and the OtOpcUa AdminUI had none, but
+OtOpcUa had a dead scoped-CSS bundle the router didn't. **Neither app has bUnit; the final gate is
+always a live browser pass.**
+
+---
+
+## 1. Discovery — four parallel read-only scans
+
+Run these as parallel read-only agents (or by hand) and write the inventories down with `file:line`
+before changing anything. The inventories become the per-batch fix briefs.
+
+### 1a. Foundation / CSS audit
+
+The theme ships less than pages assume. Check, in order:
+
+1. **Shipped-vs-used class matrix.** Extract every CSS class used in `*.razor` markup and check each
+   against (a) the theme package's `staticwebassets/css/*.css`
+   (`~/.nuget/packages/zb.mom.ww.theme/<ver>/`), (b) Bootstrap, (c) the app's own stylesheet, (d)
+   page `<style>` blocks. Anything defined nowhere is a **silent no-op** — the browser ignores it
+   without any error. (Router: 13 ghost classes from the mockups' theme.css that 0.3.1 never
+   shipped. OtOpcUa: zero — it was authored against what ships.)
+2. **Is the scoped-CSS bundle linked?** If any `*.razor.css` exists, the build emits
+   `<App>.bundle.scp.css` — but nothing links it automatically when the head is hand-authored.
+   Compare the `<link>` list in `App.razor` against `obj/…/scopedcss/bundle/`. OtOpcUa's
+   `ContextMenu.razor.css` built, served 200, and was referenced by **nothing** — every context menu
+   rendered in-flow (no `position:fixed`, no backdrop) for the component's whole life.
+3. **Phantom CSS custom properties.** Grep every `var(--…)` in markup/inline styles against the
+   tokens actually defined in the theme + app CSS. An undefined token makes the declaration invalid
+   *at computed-value time* — silently dropped, no console error. A fallback argument
+   (`var(--x, #fff)`) hides the defect. (OtOpcUa: `var(--alert)` ×13 — the theme's red family is
+   `--bad*` — so intended red error tints stayed amber; `var(--surface-2)` likewise dead.)
+4. **Button sizing.** Theme 0.3.1 ships **no `.btn` rule**, so Bootstrap's hard-coded
+   `--bs-btn-font-size: 1rem` applies against the theme's 0.9rem body. Count how many buttons carry
+   `btn-sm` vs full-size; modal feet and shared form shells are where full-size accumulates.
+5. **Dark scheme: don't chase it.** Theme 0.3.1 is light-only (no `prefers-color-scheme` /
+   `data-bs-theme` anywhere). Fix any comment claiming otherwise.
+
+### 1b. Button inventory
+
+Quick tells: `grep -rn "btn-group" Components/` returning **zero** means nothing is grouped
+(both apps' idiom was `d-flex gap-2`); also grep for `&middot;` separators between actions,
+`btn-link p-0` on things that *do* rather than *navigate*, `py-0`/inline `width:` sizing hacks.
+
+Inventory, with file:line:
+
+- **Adjacent related buttons** that should be one `btn-group`: page-head action pairs, modal/panel
+  feet (Save/Cancel, Cancel/Confirm), pagers, browse-toolbar pairs, inline confirm pairs.
+- **Row actions styled as links** (`<a href="#">` or `btn-link` text-links) → real
+  `btn btn-sm btn-outline-secondary`, destructive → `btn-outline-danger`, grouped when ≥2 in a cell.
+  **Distinguish navigation from action**: a link that routes somewhere stays a link; a link that
+  mutates state becomes a button. Both directions can coexist in one row (OtOpcUa's UnsTree: keep
+  `⚙ settings`/`Open` as links, convert `+ Area`/`Edit`/`Delete` to buttons).
+- **Arm→confirm flows** (click Delete → Confirm/Cancel appears): list them; the fix is restyle-only
+  and must not collapse the two-step.
+- **Size mismatches** within one visual group (`btn-sm` beside full-size).
+
+### 1c. Prose inventory (DELETE / KEEP / RELOCATE rubric — binding)
+
+- **DELETE**: unconditional documentation blocks — always-rendered banners explaining how a feature
+  works, config-mode walkthroughs, "how X is decided" sections, column-meaning tables. These belong
+  in `docs/`, not on the page. Verify each fact is already docs-covered (grep for distinctive
+  phrases); if it is, plain delete.
+- **RELOCATE-then-delete**: facts stated **nowhere else**. Land them in the right doc file *first*,
+  then delete the page copy — same ordering both sweeps used (foundation/doc task before page
+  batches).
+- **KEEP**: state banners (empty/error/truncation/live status), form hints (`form-text`, field
+  hints — they render only in form context), visual-encoding **legends** that are the only decoder
+  of a chip/graphic, workflow cross-links, expander-gated notes.
+- **Hunt stale claims while you're in there** — both sweeps found prose that was actively *wrong*,
+  not just verbose: milestone labels for shipped features ("F8/F9 pending", "(F3)", "arriving in
+  Batch 2/3"), architecture claims superseded by later phases, dead hyperlinks to repo paths the
+  app doesn't serve, and **config keys that don't exist** (prose said `Authentication:Ldap`, the
+  code's `SectionName` said `Security:Ldap` — always verify cited key names against the options
+  class). Wrong facts outrank style: fix or delete them even if you skip everything else.
+
+### 1d. Tree tables — check the data shape before porting the component
+
+The router built a generic `TreeTable` + `TreeVisibility` (depth-ordered flat `ITreeRow` list,
+forward-scan visibility — reference implementation in
+`../ignitionoee/router/src/ZB.MOM.Oee.Ui/Components/Shared/TreeTable.razor` + `ViewModels/TreeRows.cs`)
+and adopted it on two pages. OtOpcUa **rejected it entirely** after the scan. The rubric:
+
+- **Candidates**: tables flattening real hierarchy through hacks — a repeated `"SITE / AREA / LINE"`
+  path-prefix column, hand-rolled `rowspan` grouping, indent-by-padding rows, faked full-width
+  group-header rows.
+- **Not candidates**: rank-ordered lists and fact/audit logs (a tree destroys load-bearing
+  ordering), tables already grouped per parent (one table per group), rows that are all roots.
+- **Nav/picker trees are a different animal.** Lazy-loading navigation trees with context menus or
+  selection (OtOpcUa has four) don't fit the flat-list TreeTable model (no columns, lazy expansion)
+  — leave them alone. Duplicated expander scaffolding across nav trees is not, by itself, reason to
+  unify in a repo with no component test harness.
+
+If no adoption justifies the component, don't port it — an unused component is an orphan.
+
+---
+
+## 2. How to fix
+
+### Foundation first (one task, own files, everything else references it by name)
+
+CSS class names aren't compile-checked, so batch agents can reference foundation classes before the
+foundation branch merges — all branches build independently and compose at merge.
+
+1. **App stylesheet** loaded **after** `<ThemeHead />` so it wins the cascade (create one if the app
+   lacks it; the router created `app.css`, OtOpcUa extended `site.css`).
+2. **Button sizing as Bootstrap CSS-variable overrides** — never redefine box properties wholesale
+   (`btn-group` seam/radius machinery depends on them). The block both apps now carry:
+
+   ```css
+   .btn { --bs-btn-font-size: .85rem; --bs-btn-padding-y: .35rem; --bs-btn-padding-x: .8rem; --bs-btn-line-height: 1.4; }
+   .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).
+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
+   batches. Mirror how the theme's own variant classes (e.g. `.chip-alert`) use the tokens.
+4. **Link the scoped bundle** if 1a-2 found it dead:
+   `<link rel="stylesheet" href="_content/<AppNamespace>/<AppNamespace>.bundle.scp.css"/>` — verify
+   the exact asset name from the build output, not by guessing.
+5. **Shared class for repeated inline sizing** (e.g. `.tree-twist { flex: 0 0 18px; width: 18px; }`
+   replacing four trees' `style="width:18px"` expanders).
+6. **Relocate the orphaned prose facts into docs** (from 1c) in this same task, so page deletions
+   never race the relocation.
+
+### Button conventions (page batches)
+
+- `<div class="btn-group" role="group">` (`btn-group btn-group-sm` when members are small); fold
+  per-button `btn-sm` into the group class; drop `ms-2`/`me-1` spacers between members.
+- Mixed `<a class="btn">` + `<button>` members are valid Bootstrap — group them (keep `download`
+  etc. attributes verbatim).
+- A group whose conditional member doesn't render is fine — keep `@if` inside the group.
+- Deliberately separated members stay **outside** the group (the `ms-auto` Delete in a form foot);
+  inputs interleaved in a run split it into two groups (never put a `form-control` inside).
+- Destructive actions → `btn-outline-danger`; the armed/confirm state may go solid `btn-danger`.
+- **Preserve behavior byte-for-byte**: every `@onclick`, `disabled`, binding, `AuthorizeView` gate,
+  and arm→confirm flow unchanged — wrappers, classes, and prose only. Grep the diff for
+  `@onclick|disabled=|href=|type="submit"` appearing identically on both sides.
+- Respect existing "buttons-not-anchors" comments (Blazor's `blazor.web.js` navigation interceptor
+  is why some tree labels are buttons) — never convert those to links.
+
+### Execution pattern (what actually worked, twice)
+
+- Discovery scans → plan doc with the full inventories → **one foundation agent + N page-batch
+  agents on disjoint file sets**, all parallel; shared components (form shells, collection editors)
+  are the biggest lever — one file can fix a dozen forms.
+- Briefs must carry exact `file:line` inventories **and** the instruction *"verify by reading
+  before editing; refuse items the markup contradicts."* Both sweeps had agents correctly refuse
+  brief items (buttons in mutually exclusive `@if` branches can't be grouped; toolbars the
+  inventory over-counted).
+- Merge foundation first, then batches; run the **full build + test suite on the merged tree** even
+  if every branch was green in isolation (parallel branches compose only at the full build).
+- Verification greps on the merged tree: zero remaining phantom-token usages, zero remaining
+  `&middot;` action separators / inline `width:` hacks, `btn-group` count roughly matching the
+  inventory, the bundle link present.
+
+### Live browser gate (mandatory — these apps have no bUnit)
+
+Rebuild/redeploy the app's dev rig (**all** instances behind the load balancer — round-robin serves
+you the stale one otherwise), then walk:
+
+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`.
+2. Every page leads with data — no unconditional documentation above the fold.
+3. Seamed `btn-group`s where the inventory says; destructive members red.
+4. One arm→confirm flow per style: arm → confirm UI appears → **Cancel** (never complete a real
+   write on shared rigs); verify disarm.
+5. Anything the scoped bundle resurrected (context menus float at the cursor, backdrops cover).
+6. Legends/hints/empty states from the KEEP list still render.
+
+Record PASS/FAIL per check in the plan or a recipe doc; CSS-only fixes may land in-session, anything
+structural gets recorded instead.