docs: missing clear instructions/example on how to set design tokens application wide #2075

luissalgadofreire · 2024-05-19T19:58:57Z

luissalgadofreire
May 19, 2024

First of all, thank you for yet another great addition to the Blazor ecosystem. I am looking forward to use Fluent UI Blazor in my projects.

I looked at the following sources for clear instructions on how to set design tokens at application level, and also went through design-tokens-related issues in this github repo:

It is still not clear for me. I like the concept of design tokens, which - to my knowledge - are implemented as CSS Variables in the underlying Fluent UI Web Components solution. Being able to set all the design tokens gives us very considerable control of the application's style.

My particular question below.

Is it viable and recommended to simply:

add design tokens as CSS variables to the application's wwwroot/css/styles.css like:

:root {
    --foreground-color: #000000;
    --background-color: #FFFFFF;
    --accent-fill-rest: #0078D4;
    --accent-fill-hover: #106EBE;
    --accent-fill-active: #005A9E;
    --accent-fill-focus: #005A9E;
    --control-corner-radius: 50;
}

add a reference to that css file in index.html like in:

html
Copy code
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Blazor App</title>
    <link href="_content/MyApp/css/styles.css" rel="stylesheet" />
    <link href="css/app.css" rel="stylesheet" />
</head>
<body>
    <app>Loading...</app>
    <script src="_framework/blazor.webassembly.js"></script>
</body>
</html>

I tried it and in my experiment it worked but required the addition of !important after each design token variable, because Fluent UI Blazor automatically injects these in the consuming app; and apparently the only way to override this at application-level is to give our CSS variables greater priority via this not so best-practice workaround.

Is there any thing in how Fluent UI Blazor works that does not advise setting the CSS Variables as above?

If the above is not recommended, how exactly and where in a Blazor Wasm app, for example, should we set the values of Design Tokens for site-wide application? All the examples in the docs seem to focus on changes at component level. But how can we set them at application level in a direct straight forward way?

Answered by luissalgadofreire

May 20, 2024

For the sake of completion.

I am using a Razor Class Library (RCL) to share UI components between platforms (Blazor WebAssembly for Web, Blazor Hybrid for Native). The objective is for this RCL to serve as an internal UI Kit, in a way that abstracts consuming cross-platform apps from knowing other libraries but the RCL.

I was unsure of how to set application-wide defaults for the Design Tokens that rule the overall style of the Fluent UI Blazor Components.

After multiple surprisingly fast clarifications from @vnbaaij, I did the following.

In the Razor Class Library

Step 1 (specific to my use-case): I created my own component Button.razor, wrapping FluentButton:

@namespace MyRcl.Components

<

View full answer

vnbaaij · 2024-05-19T20:54:19Z

vnbaaij
May 19, 2024
Maintainer

Not all design tokens are 'just' CSS variables. The accent-fill-... variables, for example, are in the script created by what is called a recipe. They are calculated based on a base color you supply to the token and take things like contrast ratio into account. If you specify those manualyy, you'll need to take care of that yourself. You also indeed need to use the !important addition to overrule the script generated values.

The first code example at https://www.fluentui-blazor.net/DesignTokens#using-design-tokens-from-code explicitly mentions how you can use a token 'globally':

// 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);

To answer your questions:

No, it is not advised to do this. You set the tokens and then needed CSS variables will be created for you. If you do it yourself, you will run into things like needing the !important

You can look at the code for the demo site on how we use the tokens to set application wide tokens as well. See also #2070
Moving this as it is not an issue but more a discussion

10 replies

luissalgadofreire May 19, 2024
Author

Thanks.

My understanding of DesignTheme is that it focuses on Color themes. While that should be useful, I'm looking for something that can set any token.

In #427, the following code is shown, which does as you suggest, on OnAfterRenderAsync:

@code {
  [Inject] 
  public AccentBaseColor AccentBaseColor { get; set; } = default!;
  
  protected override Task OnAfterRenderAsync(bool firstRender)
  {
    if (firstRender)
    {
      AccentBaseColor.WithDefault("#FF0000".ToSwatch());
    }
  }
}

However, it is mentioned that that code had no effect on its own: "WithDefault does just that, setting a default value for a token. To apply a token, you need to select a Dom element where you want to set the token for."

I'm not sure I follow what would that entail, with respect to applying a token application wide. Do we still need that extra step, or is it enough to just set the default value?

luissalgadofreire May 19, 2024
Author

I can't seem to find examples of application wise use of WithDefault in the demo site code. Application-wide, I only see usage of FluentDesignTheme in App.razor.

<FluentDesignTheme StorageName="theme" />

<Router AppAssembly="@typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(DemoMainLayout)" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <LayoutView Layout="@typeof(DemoMainLayout)">
            <p role="alert">Sorry, there's nothing at this address.</p>
        </LayoutView>
    </NotFound>
</Router>

vnbaaij May 20, 2024
Maintainer

However, it is mentioned that that code had no effect on its own: "WithDefault does just that, setting a default value for a token. To apply a token, you need to select a Dom element where you want to set the token for."

I'm not sure I follow what would that entail, with respect to applying a token application wide. Do we still need that extra step, or is it enough to just set the default value?

It depends on which token you are setting. In a lot of cases the effect will be reflected immediately.

vnbaaij May 20, 2024
Maintainer

I can't seem to find examples of application wise use of WithDefault in the demo site code. Application-wide, I only see usage of FluentDesignTheme in App.razor.

Just use the example from the design token docs I mentioned before. You'll see the value be applied once you set it. Change some of the others from that example from SetValueFor to WithDefault. Just play and experiment.

luissalgadofreire May 20, 2024
Author

It worked. I added what I did below for the sake of completion.

Thanks for your time.

luissalgadofreire · 2024-05-20T09:42:12Z

luissalgadofreire
May 20, 2024
Author

For the sake of completion.

I am using a Razor Class Library (RCL) to share UI components between platforms (Blazor WebAssembly for Web, Blazor Hybrid for Native). The objective is for this RCL to serve as an internal UI Kit, in a way that abstracts consuming cross-platform apps from knowing other libraries but the RCL.

I was unsure of how to set application-wide defaults for the Design Tokens that rule the overall style of the Fluent UI Blazor Components.

After multiple surprisingly fast clarifications from @vnbaaij, I did the following.

In the Razor Class Library

Step 1 (specific to my use-case): I created my own component Button.razor, wrapping FluentButton:

@namespace MyRcl.Components

<FluentButton Disabled="@Disabled" @attributes="UnmatchedValues">
    @ChildContent
</FluentButton>

@code {
    [Parameter]
    [EditorRequired]
    public RenderFragment ChildContent { get; set; }

    [Parameter]
    public bool Disabled { get; set; }

    [Parameter(CaptureUnmatchedValues = true)]
    public Dictionary<string, object> UnmatchedValues { get; set; }

    // other parameters to be exposed
}

Step 2: I created razor component DesignTokens.razor with the following code:

@using Microsoft.FluentUI.AspNetCore.Components.DesignTokens
@namespace MyRcl.Components

<!-- Set the default theme using builtin FluentDesignToken machinery -->  
<!-- This is appropriate for the color theme, not for general control of tokens -->  
<!-- See: https://www.fluentui-blazor.net/DesignTheme -->  
<FluentDesignTheme StorageName="theme" />
<script src="_content/Microsoft.FluentUI.AspNetCore.Components/js/loading-theme.js" type="text/javascript"></script>
<loading-theme storage-name="theme"></loading-theme>

@code {
    [Inject]
    private ControlCornerRadius ControlCornerRadius { get; set; } = default!;

    protected override async Task OnAfterRenderAsync(bool firstRender) {
        if (firstRender) {
            // WithDefault() allows us to control any exposed design token, not just the color theme
            await ControlCornerRadius.WithDefault(50); // <-- setting the default design token value here
            // other tokens to be tested
        }
    }

}

Step 3 (specific to my use-case): To have the RCL inject Fluent UI Blazor Components in order to abstract the latter from consuming apps, I created a ServiceCollectionExtensions class with the following code:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.FluentUI.AspNetCore.Components;

namespace MyRcl.Components;

public static class ServiceCollectionExtensions {

  public static IServiceCollection AddMyUIComponents(this IServiceCollection services) {
    services.AddFluentUIComponents();

    return services;
  }

}

In the consuming Blazor WebAssembly app, as an example:

Step 4: I added the following line in the <head> section of the index.html:

<link rel="stylesheet" href="_content/Microsoft.FluentUI.AspNetCore.Components/css/reboot.css"/>

NOTE: one can abstract this by having the RCL directly supply reboot.css or equivalent. Just add it to the RCL's wwwroot/css folder and then, instead of pointing to the above path, point to your RCL's file.

Step 5 (specific to my use-case): I added the following line in Program.cs to inject the underlying components:

builder.Services.AddMyUIComponents();
// In normal circumstances, one will simply add `builder.Services.AddFluentUIComponents();`

Step 6: Finally, in App.razor, I added the DesignTokens component at the top so that it would set my design token default values and color theme in the consuming app:

<DesignTokens /> @* <-- add this *@

<MyApp Title="My UI Kit"
                 Assemblies="[typeof(App).Assembly]"
                 DefaultLayout="typeof(DefaultLayout)"
</MyApp>

NOTE: this will fail if step 5 is missed.

Conclusions

The button's border radius changed so ControlCornerRadius.WithDefault(50); worked.
The button's color style changed depending on the browser's light/dark mode, so FluentDesignTheme worked.
This solution allowed me to combine a more generic approach via <DesignToken>.WithDefault() with the builtin FluentDesignTheme.
The Fluent UI Blazor team is incredibly fast responding to our queries.

0 replies

docs: missing clear instructions/example on how to set design tokens application wide #2075

Uh oh!

Uh oh!

luissalgadofreire May 19, 2024

In the Razor Class Library

Replies: 2 comments · 10 replies

Uh oh!

vnbaaij May 19, 2024 Maintainer

Uh oh!

Uh oh!

luissalgadofreire May 19, 2024 Author

Uh oh!

luissalgadofreire May 19, 2024 Author

Uh oh!

vnbaaij May 20, 2024 Maintainer

Uh oh!

vnbaaij May 20, 2024 Maintainer

Uh oh!

luissalgadofreire May 20, 2024 Author

Uh oh!

Uh oh!

luissalgadofreire May 20, 2024 Author

In the Razor Class Library

In the consuming Blazor WebAssembly app, as an example:

Conclusions

luissalgadofreire
May 19, 2024

Replies: 2 comments 10 replies

vnbaaij
May 19, 2024
Maintainer

luissalgadofreire May 19, 2024
Author

luissalgadofreire May 19, 2024
Author

vnbaaij May 20, 2024
Maintainer

vnbaaij May 20, 2024
Maintainer

luissalgadofreire May 20, 2024
Author

luissalgadofreire
May 20, 2024
Author