nordisk/nornir

Theming everywhere (C8) + the facett-UI migration plan (D3)

Design + guide for the app-wide facett palette across every viz pane, and the plan to re-home the generic viz widgets into the upstream facett crate. Closes THE_BIG_PLAN C8 ("viz uses the facett themable/color schema everywhere") and D3 ("ALL generic viz UI migrated into facett; viz consumes facett themes"). Laws honoured: #1 inject-assert tests · #2 this doc · #3 facett components/theme · #4 screenshot proof · #6 "see what the user sees" as data.

TL;DR

• One app-wide facett palette (UrdrThreadsApp.palette), picked from a 🎨 top-bar combo, applied to egui Visuals, and broadcast to every pane. Switching it re-skins the whole viz at once — status colours, accents, zebra/hover/selection, gridlines, typography — and the change is observable headlessly in state_json["palette"] and each pane's own palette key.
• Every pane routes its colours through the vendored facett palette (src/viz/facett_theme.rs) + its semantic ramps — no more hard-coded Color32::from_rgb(...) chrome.
• The generic, non-nornir widgets (status chips, badges, sparklines, zebra rows, health pill, dep-graph node style) are factored into src/viz/facett_ui.rs, a clean palette-driven module the viz owns now and re-homes into facett when the egui versions align (the egui-skew blocker below).

Why a vendored palette, not a facett dependency (the egui-version blocker)

nornir's viz is pinned to egui 0.33 — the highest version egui-snarl 0.9 (the Funnel node-graph) supports, so the whole viz unifies on one egui (see Cargo.toml's egui block). The upstream facett crate is on egui 0.34. egui's Color32 / Painter / Ui / Visuals types are version-specific and do not interoperate, so a direct dep:facett-grid / dep:facett-table would link two egui versions into one binary — a hard build/ABI break.

This is the exact skew the L5 agent hit, which is why facett_theme.rs is a verbatim vendored copy of facett_core::theme::Theme (same names, same colours, same ALL order) rather than an import. C8/D3 follow that precedent.

Migration plan (when the move becomes a re-home, not a rewrite)

Tracking dep: egui-snarl 0.34 support (or de-snarl the Funnel). Until then this doc + the module headers are the "facett-bound when egui aligns" marker.

Architecture — one palette, broadcast to all

                 🎨 top-bar picker  ──┐         viz.click { "palette": "…" }
                                      ▼                    │ (robot / MCP parity)
                          UrdrThreadsApp.set_palette(Theme) ◄┘
                                      │
              ┌───────────────────────┼───────────────────────────┐
              ▼                       ▼                            ▼
   ctx.set_visuals(theme.visuals())   broadcast_palette()    state_json["palette"]
   (re-skins egui widgets)            pane.set_palette(t) ×N  (+ each pane's own
                                      (test, release, live,    "palette" key — LAW 6)
                                       knowledge, warehouse,
                                       mcp, callgraph, funnel,
                                       security, search, gates,
                                       bench, timetravel, dep_view, leaderboard)

• set_palette (pub, on UrdrThreadsApp): idempotent; on change it stores the palette, marks the egui Visuals stale, calls broadcast_palette, and emits a ui.palette trace event.
• broadcast_palette: pushes the palette into every pane's theme: Theme field via that pane's own set_palette. Each pane reads self.theme at the top of draw and paints with it.
• egui Visuals: Theme::visuals() themes the standard widgets (panels, buttons, selection, hyperlinks) to match the custom-painted surfaces; applied once per change (not every frame) via the palette_applied latch.

The semantic ramp (what panes call instead of raw rgb)

All in src/viz/facett_theme.rs on Theme (+ module consts):

Rule of thumb: verdict colours (pass/fail/warn) are the canonical GREEN/RED/AMBER consts — a green test is green in every palette. Chrome colours (background, gridlines, zebra, hover, selection, accents, dim text) come from the active Theme so a switch re-skins the surface.

facett_ui — the generic widgets (D3)

src/viz/facett_ui.rs — non-nornir-specific, palette-driven, facett-bound:

• status_chip(theme, status) -> (label, colour) — generic verdict chip.
• status_dot(ui, theme, colour, label, n) — summary-strip dot.
• zebra_row / hover_row — alternating + hover row bands.
• health_pill(painter, theme, score, …) — 0–100 pill on the health ramp.
• sparkline(painter, theme, series, rect) — themed trend line.
• graph_node(painter, theme, rect, label, stroke, selected) — the shared dep-graph / time-travel / release-lit node style.

These are the components that should live in facett (korp / Njord / any egui surface want them). They don't yet, for the egui-skew reason above; the module header documents the re-home. New panes should paint via these, not re-roll.

C8 follow-up — the last hand-rolled colours (2026-06-13)

The first C8 pass themed most panes but left a few hard-coded Color32::from_rgb islands. This follow-up routed them all through the palette:

• bench_live.rs (the 📡 live-telemetry panel embedded in the Bench tab) now carries its own theme field + set_palette (propagated by ops_tabs::BenchState::set_palette). Its status tallies use the canonical GREEN/RED (+ palette dim for neutral), the cores-busy/N ramp uses theme.health_color (low load = green headroom, pegged = red — inverted load), and the CPU sparkline uses theme.point. Exposes its own palette key under state_json["bench"]["live"]["palette"].
• leaderboard_tab.rs — draw_matrix_grid now takes a &Theme: failed cell = RED, winner = AMBER, and the score-heat cell uses theme.heat(score) (cool edge → hot accent) instead of a fixed green ramp. The dead chip_for helper (unused, hard-coded) was removed.
• test_tab.rs — the two skip-grey literals now call theme.status_fill("skip").
• funnel_view.rs — the legacy non-themed NodeStat::color() was removed (it was dead — the snarl viewer only ever calls color_themed(&theme)).

Computed-ramp exceptions (deliberately left)

A few colours are computed ramps, not flat chrome, and stay as math: callgraph.rs heat(deg) (glacier→cyan by node degree), fog_blend (depth extinction toward a fog tint), and the per-node perspective brightness. These are ramp internals; the visible chrome around them is themed. (Their Color32 literals are the ramp endpoints + #[cfg(test)] inputs, not surface chrome.)

CLI / robot parity (LAW: never GUI-only)

The palette is drivable headlessly, matching every other viz control:

• control channel: VizCommand { palette: Option<String> } → $NORNIR_VIZ_CMD (consume-once). apply_command switches the palette and logs it; an unknown name is a no-op (logged, never a panic).
• MCP: viz.click { "palette": "cyberpunk-neon" } (alongside tab / workspace), validated against the 7 palette names, returns the fresh state_json so the robot loop observes the re-skin.
• introspection: state_json["palette"] (active) + ["palettes"] (the picker list) + each pane's nested palette (proves the broadcast landed).
• initial theme (launch parity): the nornir-ui binary picks the opening palette from --theme <name> or $NORNIR_VIZ_THEME (the env wins, same precedence style as NORNIR_WORKSPACE), resolved via Theme::resolve_initial(env, flag) and applied with set_palette before the first frame — so a headless / scripted launch opens already re-skinned, no GUI click. An unknown name at either source falls through to default (a logged note, never an error). The seven choices match the picker / MCP list.

Tests (LAW #1 inject-assert, LAW #6 data, LAW #4 screenshot)

• src/viz/facett_theme.rs units — status_color verdict mapping, chrome helpers differ across palettes (heat/gridline/selection move), health ramp.
• src/viz/facett_ui.rs unit — chip vocabulary is case-insensitive and its unknown-verdict colour shifts with the palette.
• tests/viz_test_pane.rs::palette_switch_reskins_every_pane — switch the app palette; assert state_json["palette"] and every pane's own palette key flipped (proves the panes consume the broadcast, not a private default), and that the ramps actually differ. key flipped — the list now includes bench and asserts the nested bench.live.palette flips too (the live-telemetry panel consumes the broadcast), plus that the bench/leaderboard heat + point ramps differ between palettes (the de-hard-coding actually re-skins, not just renames).
• tests/viz_test_pane.rs::palette_drivable_via_control_command — a VizCommand { palette } re-skins the app (reaches the Test pane); unknown name is ignored.
• tests/viz_test_pane.rs::palette_selectable_headless_via_env_or_flag — the binary's launch path: Theme::resolve_initial(env, flag) → set_palette lands app-wide AND in the panes (incl. bench.live); no choice → default.
• src/viz/facett_theme.rs::resolve_initial_honours_env_then_flag_then_default — env-beats-flag precedence, normalisation, unknown-falls-through-to-default.
• src/viz/control.rs roundtrip — the palette field survives write→take.
• screenshot proof — the existing wgpu snapshots (viz_*.png) re-render with the themed panes (default palette) unchanged — the default palette's GREEN/RED/AMBER + heat/health ramps match the prior literals, so no PNG churn.

Files

• src/viz/facett_theme.rs — vendored palette + semantic/chrome ramps.

• src/viz/facett_ui.rs — generic palette-driven widgets (D3).

• src/viz/app.rs — palette field, picker, set_palette/broadcast_palette, visuals, state_json["palette"], themed timeline + side panel + action trail.

• every src/viz/*_tab.rs / pane — theme field + set_palette + routed colours

  • state_json["palette"].

• src/viz/bench_live.rs — theme field + set_palette + themed tallies / cores-busy health ramp / CPU sparkline + nested palette in state_json.

• src/viz/leaderboard_tab.rs — themed draw_matrix_grid (heat-ramp cells).

• src/viz/funnel_view.rs — dead NodeStat::color() removed (only color_themed).

• src/viz/control.rs + src/bin/nornir-mcp.rs — palette over the robot channel.

• src/bin/urdr-threads.rs — --theme flag + $NORNIR_VIZ_THEME env (launch parity), resolved via Theme::resolve_initial and applied pre-first-frame.