Crossing Fluent UI Blazor 4 → 5

The portal's Blazor front end renders the framework's controls through Fluent UI Blazor (Microsoft.FluentUI.AspNetCore.Components and .Icons, pinned in src/Directory.Packages.Plugins.props — core carries no GUI technology, policy core-carries-no-gui-technology). Version 5 is not an upgrade of version 4: it is a rewrite on the Fluent 2 web components, with its own component names, enums, dialog and theme systems and CSS tokens. This page is the record of the crossing, in the shape of core's Dependency Major Upgrades ledger, and the reference for what the platform now carries itself.

It is also a step in the direction The design system sets: away from Fluent's look, onto the platform's --mw-* tokens. Nothing here reverses that direction; where v5 removed a component the portal relied on, the replacement is the documented v5 one, or a platform piece that already existed.

Ledger entry

Microsoft.FluentUI.AspNetCore.Components 4.14.4 → 5.0.1 (and .Icons 4.14.4 → 5.0.1)

The mappings applied

The migration guide's tables, applied as written; the left column is v4, the right what the portal renders now.

SiteSettingsPanel (a v4 demo panel nothing referenced) was deleted rather than ported; Settings → Appearance (AppearanceView) is the live surface for the same choices.

What the platform now carries itself

• The theme store (MeshWeaver.Blazor/Components/ThemeStore.razor + ThemeSync.razor.js). It keeps v4's storage key and shape, so a choice made before the upgrade survives it, and the pre-paint script in App.razor and themeHandler are unchanged. Every store on the page hears the others (one window event), so the top-bar switch re-themes the editors and diagrams that read the cascaded ThemeMode. ThemeSync wraps it in ChromeErrorBoundary, exactly as it wrapped FluentDesignTheme (MeshWeaver.Plugins#1868, MeshWeaver#1108) — ChromeErrorBoundaryTest still proves both negative controls and the containment.
• The accent presets (AccentPresets), v4's OfficeColor table, which the design-token stylesheet and the pre-paint script resolve stored names through.
• The wire translations — MwAppearanceExtensions.ToButtonAppearance, BadgeLooks, InputAppearances, LabelTypography, LinkTargets. A control model's appearance or typography travels as a NAME (v4's member names); the views translate it explicitly, so a model authored before the upgrade renders the same.

The CSS tokens

Three blocks keep every rendered colour on the platform tokens (/_mw/design-tokens.css, Memex.Portal.Gui/Theme):

1. core's DesignTokens.FluentAliases — v4's colour names onto --mw-* (unchanged);
2. FluentV5TokenAliases — v5's Fluent 2 names onto --mw-*, applied like core's block (!important, on the root and on every element with an inline custom property), so v5's own theme script cannot win over the visitor's accent;
3. FluentV4TokenRemainder — the 32 v4 names nothing else defines any more: shape and type-ramp tokens at v4's own default values, the remaining colours on --mw-*. They are DEFINED rather than rewritten because in-mesh C# and authored content read them and no compiler sees those reads.

Suites

Run as the xUnit v3 executables (bin/Release/<tfm>/<Project>), each built -c Release -warnaserror. The 64 first-pass failures were the crossing's real findings, not flakes: most were the null-Id refusal; then the untyped FluentRadio, the <fluent-field> wrapper the dialog full-width rule missed, a module-level listener registry in the new theme JS (ComponentJsIsInstanceScopedGuard), and a static renderer without v5's LibraryConfiguration / IJSRuntime; the rest asserted v4 markup (<fluent-anchor, rel="noopener noreferrer", the message bar's intent-* class, fluent-toolbar, the card's class, [appearance="accent"]) and now assert the v5 markup that carries the same property.

CI: the platform image still ships Fluent 4

A local build restores v5 and is green; CI is not, because the shared lane compiles the repository INSIDE the pinned platform image (build-project --bind-to-image, image memex-portal-ai), and that image ships Microsoft.FluentUI.AspNetCore.Components 4.14.4. The global workspace build fails MeshWeaver.Blazor with RZ10012/RZ9996 (FluentSpinner, FluentText, TitleTemplate, …) — v5 names compiled against the v4 assembly.

The lane's superseded-image-assemblies input is not a bridge for this as it stands, measured against core's lane and tester (node-repo-module-pack.yml, tools/MeshWeaver.PluginTester):

1. It is refused as stale before anything compiles. SupersededEntryStaleness (MeshWeaver#3223) refuses an entry when the image's copy defines none of the fully-qualified type names this repository's source declares. The input exists for a type that MOVED out of an image assembly into this repository's source; no file here declares a Microsoft.FluentUI.AspNetCore.Components.* type, so the overlap is empty and the tester throws --superseded-image-assembly '…': STALE.
2. Nothing would supply v5 in its place. The container build has no NuGet restore: beyond the image it binds only the module-libraries shelf (src/MeshWeaver.ModuleLibraries), which carries no Fluent package. Dropping v4 from the reference set alone would turn every Fluent use into CS0246.

So the crossing lands when the image the lane binds carries Fluent 5 — or the lane grows a declared, version-scoped "this repository rides a newer package than the image" entry (with the package on the shelf), which is a change to core's lane and tester, not to this repository.

What was not verified

No browser was driven. Every visual statement on this page is a statement about markup and CSS, not about pixels. In particular, unverified in a running portal:

• the Fluent 2 web components' look against the --mw-* aliases (radii, shadows, focus rings), in light and dark, for each accent;
• the ::part(…) overrides in standard-page-layout.css, PortalLayoutBase.razor.css and the views' scoped CSS: they were written against v4's shadow parts, and v5's web components expose different ones, so some are now inert;
• FluentLayoutItem as the portal header (it was FluentHeader), the profile popover's placement, the drawer the notification centre opens, the top-bar menus opening from their triggers, and the inline mobile menu;
• icon colour: v4 drew an uncoloured FluentIcon in the accent, v5 in currentColor;
• the Playwright suite (src/MeshWeaver.Portal.E2E.Test, e2e/), whose selectors name v4 element tags in places.