[Design / Themes] How to simplify theme management?

[dvoituron]

Introduction

We've received a number of questions concerning the management of Design Tokens, which allow you to customize the graphic style of components. We believe that this management is certainly very useful for in-depth customization of graphic elements (customization of typography, borders, various sizes, etc.), but that we often need a few simple functions:

• Switch between Light and Dark themes
• Choose the main color of components to match the UI needs of the company or software (e.g. green for Excel, orange for PowerPoint and blue for Word).

---

💡 Please feel free to give us your comments on this proposal: Does this work for you? Is other information missing, etc.?

---

Proposition / solution

We're trying to simplify this by creating:

• An HTML Web Component fluent-design-theme (name still subject to change) that will be accessible from the client side (for management "before" Blazor renders - for example, to avoid a flash between the Light and Dark themes).
• An "identical" Blazor component to manage colors and theme from C# code.

Attributes

• theme: Choose between Dark, Light or System theme
• app-name: Allows you to apply the main color of Microsoft applications (Access, Booking, Exchange, Excel, GroupMe, Office, OneDrive, OneNote, Outlook, Planner, PowerApps, PowerBI, PowerPoint, Project, Publisher, SharePoint, Skype, Stream, Sway, Teams, Visio, Windows, Word, Yamme, Word).
• color: Allows you to define a custom color for your project (HEX format). Example: #ff0000 for red.

By setting a custom color, the app-name attribute is automatically removed.

Example

[woha]

That is exactly what I was looking for and trying to achieve with BaseLayerLuminance.WithDefault (switching from light to dark or system settings).

The requirements are always as you describe:

• Switching light / dark mode
• Set the main color to meet company branding requirements

This would really be very much appreciated!

[fedemartino]

This is exactly the problem I was trying to solve. For what I can tell I could apply different themes to different components with this approach, right?

For example, I am now working on a project where the vertical nav bar uses a dark theme, but the rest of the site a light theme. In this case I would just use two different fluent-design-theme components, one for the nav bar and one for the rest of the site, correct?

[vnbaaij]

That probably won't work in your case. The design token's withDefault function sets a value that is then used in all cases. So if you set the baseLayerLuminance token to dark, it will always be dark everywhere.

But you can do it with the regular DesignTokens we already have on the Blazor site. The SetValueFor methods have a n
ElementReference parameter that allows you to set a token for a specific element (and its decendants). By using this, you can set different parts of your app to use different base layer luminance values.

If you need to get an ElementReference from a <Fluent...> component, we expose the Element parameter from the FluentComponentBase base class.

[fedemartino]

Yeah, I tried that, but kept getting the "flicker" problem. Ended up using a custom class for the nav bar with css.
BTW, thanks for taking the time to always reply to all comments! Much appreciated :)

[MeikTranel]

Generally in favor - some input:

• How much of the design here is just the regular upstream FAST theme provider tag?
• Please choose other names for color and app-name:
  • color describes the primary theme color from which the other design tokens are being derived, right? a plain color attribute is probably misleading here - something like PrimaryColor is probably in order
  • app-name is also misleading - it should better reflect that we're reusing a high level office app theme and that it doesn't have anything to do with naming your app or the like - i propose something "DeriveFromOfficeAppTheme" (i'm using derive as a verb because i assume the design idea was that certain design tokens can be changed while deriving the rest from the "excel" theme for example)

[fedemartino]

What if color and app-name are just merged into a single primary-color attribute and just parse the content to see if it's a named color or HEX value?

[MeikTranel]

that doesnt sound bad but i feel like that could be a hinderance when ideally offering idiomatic html components that would support hex as well as english color names.

[dvoituron]

The color must be defined using HEX code only (this is a requirement of the FAST components) as we need to extract the RGB values to adapt the colors in the Dark theme.

primary-color is probably a better name. But I find DeriveFromOfficeAppTheme too long and not all the above applications are included in the Office suite.

[MeikTranel]

@dvoituron agreed - my primary feedback was to make y'all consider the app-name confusion and i wanted to offer some alternatives along the way. DeriveFrom would work as well especially if that tag just maps to an entry in some backhanded dictionary of preset theme entries though that would give it a feel like theres somehow a way to register themes generally available.

Either way i think the naming as proposed lacks some clarity.

[kzu]

How about ThemeColor (for primary color) and ThemeName (from MS app names, potentially extensible some day?). These would match with color (HEX) and color name (i.e. blue, red).

[dvoituron]

This is exactly the problem I was trying to solve. For what I can tell I could apply different themes to different components with this approach, right?

For example, I am now working on a project where the vertical nav bar uses a dark theme, but the rest of the site a light theme. In this case I would just use two different fluent-design-theme components, one for the nav bar and one for the rest of the site, correct?

For now, the theme/color updates the default variables. So the entire website.

[fedemartino]

Still looks like a great solution for a high percentage of use cases

[SPWizard01]

The choice to use design tokens over all is a welcome thought, however when we compare what approach industry is using right now, it looks somewhat lacking or maybe I do not fully understand it.

As commented here: #942

The projects which I work on require specific colors (i.e. primary button, primary button hovered etc.), accent base color does not meet those needs.

When I think of Blazor I think of React but in .NET :)
If you compare to Fluent UI 8 React lib, its quite different, I cannot say whether its good or bad. But what I loved about it is that you get Microsoft product Look & Feel but still can override colors to your company needs:
https://developer.microsoft.com/en-us/fluentui#/controls/web/themeprovider
The above implementation was something I expected with this framework as well.
What I loved about Fluent UI 8 and React is that you can actually define looks of a component and its descendants.

The other great part is that you could export base theme and then reuse it for different project, this is something I would love to be able to do with this framework. I.e. save it as a separate NuGet package within the company repository and reuse it later.

The problem with Blazor Server at this point is flickering (probably does not happen on WASM)
Therefore I think there should be a way to define theme before the component actually render, and to use different theme or parts of it for different Route/Component.
We can do it today because its .NET in the end (generate some CSS and JS on your own) but its not part of UI framework unfortunately.

If we look into alternative frameworks you will see that they try to accomplish this (still not perfect but better) and you can actually avoid flickering for the most part (except for Dark/Light theme, but there are workarounds)

https://www.mudblazor.com/customization/overview#variables (the framework I ended up using and created my own theme with MS looks with company colors, then exported it as a NuGet package)
https://blazorise.com/docs/theming

What I personally don't like is that this framework locks you to use base accent color and if you want to override for a specific button you actually have to use CSS and cannot define it from code (or maybe you can but it does not look straight forward)
Something like here: #706

Blazor actually does a great job at "namespacing" CSS to that specific component:
https://learn.microsoft.com/en-us/aspnet/core/blazor/components/css-isolation?view=aspnetcore-8.0

However, maybe its jut me and others don't find it a problem at all.

Hope this gives some context.

[dvoituron]

Hello,
I totally agree with you and I think all these requests will be solved.

1. This new fluent-design-theme component is mainly present to help the majority of developers who need to choose a main color and mode (Dark/Light) for the all website or application. This component simplifies the process.
2. To customize the colors or mode (Dark/Light) of a part of a web site/app, the following fluent-design-system-provider component is the best way to go.
3. For detailed color customization of all elements, the fluent-design-system-provider component already exists (documented here).
4. We also intend (at a later date) to make it possible to export or import style settings via a process similar to React Theme Designer.

I'm currently working on this component, which should be released this week.
I'm also adding a documentation page to explain these usage details.

Example
From HTML/JavaScript

<fluent-design-theme mode="light" primary-color="word" />
<fluent-design-theme mode="dark" primary-color="#ff0000" />

From Blazor

<FluentDesignTheme @bind-Mode="@Mode" OfficeColor="Word" />
<FluentDesignTheme Mode="DesignThemeModes.Dark" PrimaryColor="#ff0000" />

Using FluentDesignSystemProvider

<FluentDesignSystemProvider AccentBaseColor="#217346">
   ...
</FluentDesignSystemProvider>

Design Tokens: FluentUI Blazor DesignTokens
Design variables: design-system-provider Definition - To be documented.

[dvoituron]

Example of the current development...

1. <FluentDesignTheme @bind-Mode="@Mode" OfficeColor="@OfficeColor" />
2. <FluentDesignSystemProvider AccentBaseColor="#FF0000" StrokeWidth="4" FillColor="#DBDBDB">...</FluentDesignSystemProvider>

[kzu]

Would this work as-is in an InteractiveServer mode too?

[dvoituron]

We pushed this PR #1093 to include these features.

[schaveyt]

I would very much like to use the component library but the mean for styling is still very confusing. I have scoured the demo and this repo and still can find just a basic list of all the css variables I can play with to see what color are what when changing the base color

I have resorted to making something silly like this...

[schaveyt]

This project needs a page like what the Radzen team has whipped up
https://blazor.radzen.com/colors

[vnbaaij]

You seem to have a workable solution by creating that page/example mentioned above. We accept PR's so why not create one to help others as well?

[schaveyt]

Tell me were I can find all those cas variables and their purpose and I'd be happy to.

[vnbaaij]

All the C# constants are defined in https://github.com/microsoft/fluentui-blazor/blob/dev/src/Extensions/DesignToken.Generator/DesignTokenConstants.cs. You should be able to deduct the CSS variable names from that list.

[pmeems]

I really like FluentUI for Blazor and I've been pushing it to my team to use it as well.
The only thing we're struggling with is the theming.
I can't get it to work as I want.

I use the default settings and have only set the accent color. I use FluentDesignSystemProvider in my Routes.razor:

<FluentDesignSystemProvider AccentBaseColor="#cc3300">
    <Router AppAssembly="@typeof(Program).Assembly" AdditionalAssemblies="new[] { typeof(Client._Imports).Assembly }">
        <Found Context="routeData">
            <RouteView RouteData="@routeData" DefaultLayout="@typeof(Layout.MainLayout)" />
            <FocusOnNavigate RouteData="@routeData" Selector="h1" />
        </Found>
    </Router>
</FluentDesignSystemProvider>

I also use --accent-fill-rest in my CSS to set the background for my header and footer.
This works great.

But when I want to add to option for dark-mode strange things happen.
In my MainLayout.razor I add this line <FluentDesignTheme Mode="DesignThemeModes.Dark" CustomColor="#cc3300" />.
But now my accent color turns from dark orange to a light salmon yellow. But I pass the orange as CustomColor.

Eventually I want the mode set to System. Currently this means that the light version and dark version are using different company colors and thus I can't use it.

If this could be made simpler or better documentation with examples could be added, would be a lifesaver.

[dvoituron]

I understand your frustration, but we depend on FluentUI components that use this styling mechanism:
https://learn.microsoft.com/en-us/fluent-ui/web-components/design-system/design-tokens

You'll read this note where the Adaptive Color System is explained.

This example uses color because it's an easy concept to describe, but we generally discourage the use of fixed colors as they don't benefit from the adaptive color system with support for light and dark mode and other adjustments.

The orange color changes are due to the application of this adaptive color system and we have no way of handling this in our library :-(

[wolfgangschneider]

Maybe jump in too late.

For my understanding, this component is based on fluent ui web component and this project is related to Fast, right ?

What I do not understand is why the "fast color explorer" https://color.fast.design/ calculate other colours from AccentBaseColor as this library. On Fast, the accentFillRest is (with background 0 ) the same as the Accent Base Color, on this library not. I also looks that the accentFillHover is darker as the accentFillRest on fast, on this library its lighter.

Can someone tell me why?

PS: there i a second Fast demo on https://www.fast.design/ where you can set Mode , Neutral Color Accent color, Border radius Stroke width and density. In my opinion the new FluentDesignTheme component should provide this properties

[vnbaaij]

For my understanding, this component is based on fluent ui web component and this project is related to Fast, right ?
Yes

What I do not understand is why the "fast color explorer" https://color.fast.design/ calculate other colours from AccentBaseColor as this library. On Fast, the accentFillRest is (with background 0 ) the same as the Accent Base Color, on this library not. I also looks that the accentFillHover is darker as the accentFillRest on fast, on this library its lighter.

Can someone tell me why?

Because that color site is using an older version of the adaptive color picker Denis was talking about, The most current and up-to-date color eplorer can be found here: https://fluent-components.azurewebsites.net/?path=/docs/design-system-color-explorer--page

PS: there i a second Fast demo on https://www.fast.design/ where you can set Mode , Neutral Color Accent color, Border radius Stroke width and density. In my opinion the new FluentDesignTheme component should provide this properties.

Border radius, stoke width and density can all be manipulated with our Design Token implementation. These offer advanced options which we do not want to make broadly and easily available. We don't do that because we do not want to make it easy to break out of the Fluent Design System. Isn't that a bit opinionated? Yes, but as it is our library, we can do that.
Besides, what is shown in the link is not showing a Fluent Design. Fast uses the same underlying technology stack but has its own design system.

[Skintkingle]

Quick question as we've noticed FluentDesignSystemProvider seems to have disappeared from the docs, this discussion is the closest to talking about what it does as it seems to get right now. Is the FluentDesignSystemProvider being deprecated or are the docs just having a refresh point 3 docs link?
Is it still safe to keep using FluentDesignSystemProvider for our requirements (themeing an entire section and all Elements within that section). We tried to use SetValueFor on the DesignTokens on a container div and it only seemed to apply directly, not to any descendents. As mentioned in a passing comment here

[Skintkingle]

Thanks for taking the time to respond so promptly, by the way!

2 things,
I don't see a SetDefaultFor member. I'm looking at AccentBaseColor on version 4.9.3 as an example.
second thing, if SetDefaultFor should exist, it would be great to have it in the docs in this section

If SetDefaultFor is meant to be exposed publically, it doesn't appear to be. Would you like me to raise that as an issue? Similarly for the docs update would you like me to raise that, too?

[vnbaaij]

Sorry, brainfart...meant SetValueFor

[Skintkingle]

Hmm, okay, let me have a play with that and I'll raise an issue if it doesn't seem to be working properly. My initial foray into that method definitely seemed like it didn't apply to all descendents of the container it was applied to.

[vnbaaij]

I had an example of the AccentBaseColor but it is not working atm. In the rendered source I see it gets assigned an [object Object]. Investigating...

[vnbaaij]

Ok, got it working again. See below code on how I set AccentBaseColor and NeutralBaseColor on the containing div. You can als use ref2!.Element in the AccentBaseColor.SetValueFor to set it for button 2 only (same for button 3 with ref3 in the NeutralBaseColor.SetValueFor, hover over the button to see the effect)

@using Microsoft.FluentUI.AspNetCore.Components.DesignTokens
@inject BaseLayerLuminance BaseLayerLuminance
@inject NeutralBaseColor NeutralBaseColor
@inject AccentBaseColor AccentBaseColor
@inject BodyFont BodyFont
@inject StrokeWidth StrokeWidth
@inject ControlCornerRadius ControlCornerRadius

<div @ref="ref0">
    <FluentButton @ref="ref1">A button</FluentButton>
    <FluentButton @ref="ref2" Appearance="Appearance.Accent">Another button</FluentButton>
    <FluentButton @ref="ref3">And one more</FluentButton>
    <FluentButton @ref="ref4" @onclick=OnClick>Last button</FluentButton>
</div>

@code {
    private ElementReference ref0;
    private FluentButton? ref1;
    private FluentButton? ref2;
    private FluentButton? ref3;
    private FluentButton? ref4;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            //Set to dark mode
            await BaseLayerLuminance.SetValueFor(ref1!.Element, (float)0.15);

            //Set to Excel color
            await AccentBaseColor.SetValueFor(ref0!, "#217346".ToSwatch());

            await NeutralBaseColor.SetValueFor(ref0!, "#7719aa".ToSwatch());
            //Set the font
            await BodyFont.SetValueFor(ref3!.Element, "Comic Sans MS");



            //Set 'border' width for ref4
            await StrokeWidth.SetValueFor(ref4!.Element, 7);
            //And change conrner radius as well
            await ControlCornerRadius.SetValueFor(ref4!.Element, 15);

            // If you would like to change the BaseLayerLuminance  value for the whole site, you can use the WithDefault method
            //await BaseLayerLuminance.WithDefault((float)0.15);

            StateHasChanged();
        }
    }

    public async Task OnClick()
    {
        //Remove the wide border
        await StrokeWidth.DeleteValueFor(ref4!.Element);
    }
}