Implement Microsoft.Aspnet.FluentUI Design tokens

[goodtocode]

Dark mode exposes flaws in implementation of Microsoft.Aspnet.FluentUI design tokens. Copilot's recommendations are:
✅ 1. Current version & official guidance (as of Feb 2026)
The currently published Fluent UI Blazor package is:

Microsoft.FluentUI.AspNetCore.Components — version 4.11.4
(released Feb 12, 2025)
✔ Designed for .NET 8 / .NET 9 / .NET 10
✔ Supersedes the older FAST/Fluent UI packages (Microsoft.Fast.Components.FluentUI) [nuget.org]

Official documentation & demos:

Design Theme & theming guidance
https://fluentui-blazor.azurewebsites.net/DesignTheme [fluentui-b...bsites.net]
Design Tokens & adaptive color system (general Fluent UI guidance)
https://learn.microsoft.com/en-us/fluent-ui/web-components/getting-started/styling [learn.microsoft.com]
GitHub Q&A on dark‑mode overrides
microsoft/fluentui-blazor#3378 — describes why certain colors shift in dark mode because of the adaptive color system and how to override them safely. [github.com]

✅ 2. Why your UI looks inconsistent in dark mode
Your screenshot shows:

A bright blue header bar on dark mode
Sidebar buttons and panels not matching Fluent defaults
Foreground/background contrast inconsistencies

These are symptoms of not fully applying the Fluent design tokens & design‑theme pipeline.
Fluent UI Blazor uses:
✔ Adaptive Color System (automatic light/dark recalculation)
Color tokens (accent, neutral, foreground, etc.) dynamically recompute when switching luminance.
This can override fixed CSS colors unless properly configured. [github.com]
✔ Design Tokens
Tokens such as neutral-foreground-rest, neutral-fill-layer-rest, etc., define the entire app's palette.
These must be applied via to avoid mismatches.
[learn.microsoft.com]
✔ Proper host‑level CSS
Fluent UI requires base CSS to align body background/foreground to token values.
Missing these leads to mismatched backgrounds like the screenshot.
[fluentui-b...bsites.net]

✅ 3. Correct way to implement dark mode in Fluent UI Blazor (official)
Step 1 — Add at the top of your app
Place this in App.razor or your MainLayout:
Plain Textrazor isn’t fully supported. Syntax highlighting is based on Plain Text. ... Show more lines
This automatically manages:

Light/dark mode switching
Applying design tokens globally
Syncing with system/browser theme
Preventing mismatched colors across components
[fluentui-b...bsites.net]

Step 2 — Add required base CSS (critical for dark-mode consistency)
In wwwroot/css/app.css:
CSSbody { margin: 0; padding: 0; height: 100vh; font-family: var(--body-font); font-size: var(--type-ramp-base-font-size); line-height: var(--type-ramp-base-line-height); font-weight: var(--font-weight); color: var(--neutral-foreground-rest); background: var(--neutral-fill-layer-rest);}Show more lines
This ensures that the page background and page text come from Fluent tokens instead of default browser styling.
If missing, you will get a white or gray layout even in dark mode.
[fluentui-b...bsites.net]

Step 3 — Avoid the “flash” problem on startup (important in dark mode)
In index.html (server prerendering) or _Host.cshtml:
HTML<script src="_content/Microsoft.FluentUI.AspNetCore.Components/js/loading-theme.js"></script>Show more lines
This prevents the page flashing white before dark mode loads.
[fluentui-b...bsites.net]

Step 4 — Use Fluent tokens instead of raw CSS colors
Your header bar looks hard-coded in blue.
Instead, set:
Plain Textrazor isn’t fully supported. Syntax highlighting is based on Plain Text.<FluentDesignTheme @bind-Mode="@mode" @bind-OfficeColor="@OfficeColor" StorageName="theme" />Show more lines
Using OfficeColor auto‑adjusts accents for dark mode.
[fluentui-b...bsites.net]
To manually override accent behavior in dark mode (advanced), see GitHub discussion #3378.
[github.com]

✅ 4. Which conventions you are likely violating (based on screenshot)
❌ Using fixed colors in CSS
Instead of tokens like --neutral-layer-* or --accent-*.
❌ Missing body-level CSS token bindings
Leading to a white/blue header even in dark mode.
❌ Not wrapping top-level layout with
Resulting in UI shell components not inheriting token values.
❌ Possibly using Fluent UI components outside the token context
E.g., sidebar buttons use wrong neutral colors.
❌ Missing theme pre‑loader to avoid white flash
Your screenshot background suggests default browser colors loaded first.

✅ 5. Where to find the correct implementation patterns
A) Fluent UI Blazor Design Theme docs (primary source):
https://fluentui-blazor.azurewebsites.net/DesignTheme
Covers:

Theme switching
Dark/light mode
Primary color / OfficeColor
Preloading theme to prevent flashes
Required CSS and placement
[fluentui-b...bsites.net]

B) Design Tokens & Adaptive Color System (Microsoft Learn):
https://learn.microsoft.com/en-us/fluent-ui/web-components/getting-started/styling
Covers:

Neutral & accent color recipes
Luminance controls
What to not override directly
[learn.microsoft.com]

C) GitHub guidance for dark mode overrides:
microsoft/fluentui-blazor#3378
Explains:

Why colors change automatically
How to override deltas properly