A̵t̵ ̵t̵h̵e̵ ̵m̵o̵m̵e̵n̵t̵,̵ ̵t̵h̵e̵ ̵p̵a̵c̵k̵a̵g̵e̵ ̵i̵s̵ ̵a̵v̵a̵i̵l̵a̵b̵l̵e̵ ̵o̵n̵ ̵N̵u̵G̵e̵t̵ ̵a̵s̵ ̵t̵h̵e̵ ̵f̵i̵r̵s̵t̵ ̵R̵e̵l̵e̵a̵s̵e̵ ̵C̵a̵n̵d̵i̵d̵a̵t̵e̵ ̵(̵R̵C̵1̵)̵ ̵v̵e̵r̵s̵i̵o̵n̵.̵ ̵T̵h̵i̵s̵ ̵m̵e̵a̵n̵s̵ ̵w̵e̵ ̵w̵i̵l̵l̵ ̵n̵o̵t̵ ̵b̵e̵ ̵a̵d̵d̵i̵n̵g̵ ̵a̵n̵y̵ ̵n̵e̵w̵ ̵f̵u̵n̵c̵t̵i̵o̵n̵a̵l̵i̵t̵y̵ ̵b̵e̵t̵w̵e̵e̵n̵ ̵n̵o̵w̵ ̵a̵n̵d̵ ̵t̵h̵e̵ ̵r̵e̵l̵e̵a̵s̵e̵ ̵o̵f̵ ̵t̵h̵e̵ ̵f̵i̵n̵a̵l̵ ̵v̵e̵r̵s̵i̵o̵n̵.̵ ̵W̵e̵’̵l̵l̵ ̵f̵o̵c̵u̵s̵ ̵o̵n̵ ̵f̵i̵n̵d̵i̵n̵g̵ ̵a̵n̵d̵ ̵f̵i̵x̵i̵n̵g̵ ̵b̵u̵g̵s̵.̵ ̵I̵t̵ ̵w̵o̵u̵l̵d̵ ̵b̵e̵ ̵g̵r̵e̵a̵t̵ ̵i̵f̵ ̵y̵o̵u̵ ̵c̵a̵n̵ ̵h̵e̵l̵p̵ ̵u̵s̵ ̵w̵i̵t̵h̵ ̵t̵h̵i̵s̵,̵ ̵t̵a̵k̵e̵ ̵t̵h̵e̵ ̵p̵a̵c̵k̵a̵g̵e̵ ̵f̵o̵r̵ ̵a̵ ̵s̵p̵i̵n̵ ̵i̵n̵ ̵y̵o̵u̵r̵ ̵o̵w̵n̵ ̵(̵t̵e̵s̵t̵)̵ ̵p̵r̵o̵j̵e̵c̵t̵s̵ ̵a̵n̵d̵ ̵r̵e̵p̵o̵r̵t̵ ̵a̵n̵y̵ ̵i̵s̵s̵u̵e̵s̵ ̵i̵n̵ ̵t̵h̵e̵ ̵G̵i̵t̵h̵u̵b̵ ̵r̵e̵p̵o̵s̵i̵t̵o̵r̵y̵.̵ ̵D̵e̵p̵e̵n̵d̵i̵n̵g̵ ̵o̵n̵ ̵w̵h̵a̵t̵ ̵i̵s̵ ̵f̵o̵u̵n̵d̵,̵ ̵w̵e̵ ̵m̵i̵g̵h̵t̵ ̵r̵e̵l̵e̵a̵s̵e̵ ̵a̵n̵o̵t̵h̵e̵r̵ ̵R̵C̵ ̵b̵e̵f̵o̵r̵e̵ ̵t̵h̵e̵ ̵f̵i̵n̵a̵l̵ ̵r̵e̵l̵e̵a̵s̵e̵.̵
Update: the final version of the 2.0 package is available on NuGet now!

We’ll present the changes in a condensed form first. Starting with what’s new for the library and then what’s new to the documentation and example site(s). After that, we’ll dive into the details. If you’re already using the library in your Blazor WASM or Server applications and you want to upgrade to this version, you’re going to need that detailed information. As with most major releases, this one comes with breaking changes as well…

Library changes

• Re-implemented the DataGrid (leveraging the ASP.NET Team’s QuickGrid)
• Re-implemented the Combobox, Listbox, and Select components
• Implemented a CSS baseline
• General component updates
• Updated the Accordion component
• Updated the Anchor component
• Updated the Button component
• Updated the Icon component
• Added a GlobalState service

Documentation and example changes

• Extended dark/light theme settings with an accent color selection
• Updated and enhanced the DemoSection component
• Improved the APIDocumentation component
• Added a sample data service
• Added an ‘Incubation lab’ section where we offer examples of site building components and potential new library components

Library changes

Let’s start with the changes we have made to the library itself.

DataGrid component

With regards to the implementation of the grid that was is in our package until now, we followed what was ‘prescribed’ by the fluent-data-grid. We wrapped the fluent-data-grid, fluent-data-grid-row and fluent-data-grid-cell and their attributes (parameters on the Blazor side) and by doing so styling and rendering is taken care of (by the web components). For adding capabilities to the grid, we copied over a lot of the principles and code from the BlazorFluentUI package. In that process, some things were renamed to better align with the Web Component internals (like ColumDefinition). The result was nice but a bit clunky in the way the columns were defined. Also, sorting, etc. seemed to be more of an afterthought. We have a solution for all these problems now by leveraging the strengths of the ASP.NET Team's QuickGrid implementation.

For the 2.0 version of the grid, we basically took this QuickGrid implementation, swapped out its rendering to use the <FluentDataGrid> components and renamed a lot of the parameters to keep in line with what we were already using on the Fluent UI side. By doing so, we completely broke every <FluentDataGrid> implementation out there. Please be aware of this when you upgrade. You can use the examples provided in the demo site to guide you in how to move to using the new implementation. Also, by doing this, you can now use all* of the great functionality being offered by the QuickGrid. Please take a look at the QuickGrid for Blazor site to see what else is possible.

*The only thing we did not copy over is the Theme parameter and functionality as the whole point of this library is to have a theme implemented already...

In its simplest form, the end result in code would go from this (which does not come with any sorting capabilities):

to this (with sorting capabilities baked in):

Quite an improvement, we think.

An example implementation:

Listbox, Select, and Combobox component updates

Earlier versions of these components did not really work well in cases where you wanted to do binding or set pre-selected values. There were also no good examples on how to use the components. And the examples that did exist, assumed that the data shown would come from separate options instead of being inferred from a programmatically supplied list. We have now re-implemented these three components from the ground up (sharing a common base implementation) and are here again making breaking changes! We’ve also made a lot of examples of the components’ usage available in the demo environment.

For the Combobox, you can now bind to the Value instead of to the text of an option. If you type a value instead of selecting an option from the list, the Value will reflect that.

For the Listbox and Select, you can bind to the Value but also to the (strongly typed!) SelectedItemor SelectedItems (multiple not working for Listbox yet because of an issue in the underlying web component).

Example of a multi-select implementation:

A CSS baseline

We’ve received quite some feedback from users that they would like to have more tools and components available that help them with layout of sites and applications. Although we sympathize with the idea, it does not really align well with the goal of this library: to provide a Blazor wrapper for the Fluent UI Web Components. That being said, we thought about how to accommodate this wish while staying in line with the goal set. We think we’ve come up with a good middle ground. More on that later..

So why are we bringing this up here? We want to make sure the components look as good as possible in every browser, site, and application, wherever the layout is defined. To help you in achieving this, we’ve added a CSS baseline named Reboot to the library which you can build upon. The CSS we provide is based on Bootstrap's Reboot solution (which in turn is based on Normalize). Using the baseline is completely optional and it is entirely possible to build a site without using Reboot. If you want to use Reboot, like the demo site, you'll need to include it in your index.html or _Layout.cshtml file like this:

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

If you choose not to use it, please do add the variables.css file (which is otherwise imported through the reboot.css file) to your index.html or _Layout.cshtml file like this:

<link href="_content/Microsoft.Fast.Components.FluentUI/css/variables.css" rel="stylesheet" />

This file contains a number of CSS variables that are required to be defined for some of the components to work correctly.

See the Reboot page in the demo site for more information.

General component updates

We’ve added two parameters to the <FluentUIComponentBase> component to make them available to every component in the library. The added parameters are:

• Class; This enables you to add (optional) CSS class names. If given, these will be included in the class attribute of the component.
• Style; This enables you to add (optional) in-line styles. If given, these will be included in the style attribute of the component.

Utility CssBuilder and StyleBuilder (based on EdCharbeneau/BlazorComponentUtilities) implementations have been added to make it easier to compose values for these parameters. Examples of using this can be found in the source code.

We removed the ChildContent parameter from the base class and moved it down to the components themselves. This is done to make it possible to have components without any child content and/or have components with multiple content sections.

Accordion component updates

With earlier versions of the library, we added event handling code to several components. Due to some missing code in the underlying web components, event handling had not been added to the <FluentAccordion> component yet. This code has now been added and this allows you to detect the last changed accordion item. The example in the demo site has been enhanced to showcase this behavior.

Anchor component updates

One of the things that do not play nice in most SPA application frameworks are hyperlinks with bookmarks. This is due to the way the router mechanism works in these frameworks. Blazor is no exception here, so the <FluentAnchor> component could not be used to jump to a specific spot on a page earlier. With this version, a fix has been implemented that enables these jumps to work as expected. This is being used heavily in the new table of contents component that is now shown on every content page in the demo site. The fix also takes into account any text fragments in a link with a bookmark.

Button component updates

We’ve added a ButtonType enumeration to the library and are using this now in the <FluentButton> component to denote the type of button (it was a string parameter before). The default value for the type is Button. (The other available options are Submit and Reset)

Icon component updates

There are a number of breaking changes for the <FluentIcon> component. Upgrading to version 2 of the library means you will need to review all used icons carefully. The changes are:

• We’ve updated <FluentIcon> to support more colors. A Color enum has been added for this. The UseAccentColor parameter has been removed for this.
• It is now possible to use a custom color for rendering an icon. A CustomColor parameter has been added for this (and can only be used when the Color parameter has been set to Color.Custom)
• The Filled parameter has been replaced with an IconVariant enum (with possible values of IconVariant.Filled or IconVariant.Regular (default))

To prevent icons from being requested and downloaded on each and every <FluentIcon> call, a caching mechanism has been added. This leverages the standard Cache Web API which is supported by every modern browser. Icons downloaded to the cache have a (non configurable) validity of 7 days. After that period, an icon will be re-downloaded from the server.

Example of rendering icons with a specific color:

There have also been a couple of releases of the underlying Fluent UI System Icons library since our last version shipped. We have merged these releases into version 2 now. The latest update we’ve synced up with is 1.1.187.

GlobalState Service

A GlobalState class has been added to the library which is added to the Services container automatically. At the moment the service contains two properties that you can use within your own code. These are Luminance and Dir, and give you access to the state of the current theme (light or dark) and the direction of the content (left to right or right to left). Both properties also come with a Set... method that raises a notification that you can subscribe to in your code. An example of this can be found in the CounterBadge component (see below).

Documentation and example site changes

With this version, we continued to enhance the documentation and examples in the demo sites. The Web Assembly version of the site is always available at https://aka.ms/fluentui-blazor. If you clone or download the repository, you can choose to run either the Web Assembly or Server version of the site locally. In the sections below, we’ll describe the enhancements we made to these sites in more detail.

Updates and enhancements to the DemoSection component

A key component (no pun intended) to the demo site is the DemoSection component. Is has been greatly enhanced and now displays example, source and other related files (.cs, .css, .js), if any, in a tabbed fashion. This way examples are no longer stretched out to long listings of source code. Another new functionality of the component is that it now presents download options for all the files that make up the example. This way we hope to make it easier to re-use the examples in your own projects. Just remember to replace the namespace we use in the examples with your own project's namespace.

As a last change, the code highlighting part of the DemoSection has now been made theme-aware.

Improved APIDocumentation component

The information on all of the component’s parameters is being generated from the XML documentation (which gathers all source code comments). We built an APIDocumentation component to display this information. This component has now been enhanced to get descriptions from a components' base class. Also, the documentation generation for generic components has been greatly improved.

Add Color (‘theme’) selection to the site

Finally, as a last visual change to the demo, we added a color selection to choose a different accent color to use. This works in tandem with the Light/Dark switch and shows how Design Tokens can be used to influence how components are being rendered.

The colors in the selection list come from an enumeration (called OfficeColor) that has been added to the library (and not just to the demo environment). The enumeration contains the RGB hex color codes for 17 different Office applications.

Incubation Lab

To show the art of the possible, test out new things, and address the ask around tools and components that can help with the layout of sites and applications, we’ve added an ‘Incubation Lab’ section to the demo environment. By leveraging the download options described earlier, we hope to make it easy for you to test and use these components in your own environments.

The components we showcase in the Lab are not part of the official library and are not included in the NuGet package. We only support these specific components on a best effort base through our GitHub repository.

Layout components

The following components have been added to aid developers in building layouts for sites and applications:

• Header
• Footer
• BodyContent
• Layout
• MainLayout
• Spacer
• Stack

Using (most of) them together can yield something like this:

Please see the demo site for more documentation and usage examples.

Other components

We’ve added some components that we think could be useful. They showcase how to wrap or build upon existing components, combine components with custom code and/or JavaScript, or just how to create something completely new. We hope you will help us test-drive these components, both in the demo environment but also in your own projects, and provide us with feedback.

• NavMenu, NavMenuGroup, and NavMenuLink
  These components show how to wrap the existing <FluentTree> and <FluentTreeItem> components to build a (collapsible) navigation menu. See the left side of the image above for an example
• CounterBadge
  The CounterBadge component is used to display a notification count on top of another component:

• PresenceBadge
  The PresenceBadge component is used to display a status indicator such as available, away, or busy.

• MenuButton
  The MenuButton component shows how easy it is to combine two other Fluent components (<FluentButton> and <FluentMenu>) in a new component with its own specific funtionality

• Table of Contents
  The TableOfContents component uses an existing component (<FluentAccordion>) together with some custom code and JavaScript interop. The JavaScript scans the article-section of a page for all h2, h3 and h4 headings and the custom code presents them as a table of contents with clickable links to those headings in an accordion component.

Next steps

As describe earlier, we have made the RC1 version of the package available on NuGet. Please try it out in your own projects and let us know what you think. Also, please report any issues you find in the GitHub repository. Let’s work together to make this a great new major version!

What’s new in the Microsoft Fluent UI library for Blazor version 2.0 was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.

We’ve updated the project to not only compile with the latest version of .NET 6 but also with the new .NET 7 (generally available as of today!). If you would examine the NuGet package, you’ll see that as of this version there are two DLL’s available:

Depending on the Framework version you choose when creating a new project, the correct version of the Fluent UI library will automatically be chosen when you add this package to your project.

There is unfortunately no good way yet to use version specific code in .razor files (like you can in C# with #if preprocessor directives). This means we are not using any of the specific new Blazor functionality like @bind:after at the moment. We are working with the ASP.NET team to see how a better experience can be offered for this moving forward.

Icon updates

We’ve updated the Fluent UI System Icons to the latest available version (1.1.186). A lot of new icons have been added and updated since the 1.5.3 release of our library.

To make it easier to use the FluentIcon component in your own application, you can now get a ready-to-paste component declaration from the demo environment. It works like this:

• Go to https://aka.ms/fluentui-blazor/Icon
• Type a search term, select a size and select whether you want filled and/or regular variants and click on ‘Search’. For example:

• In the results, click on the icon card you want to get a component declaration for which you can paste in you own .razor file. You will get a notification of the copy action:

• Now, where you want to use this icon, paste from the clipboard. In this example it will insert <FluentIcon Name="@FluentIcons.Washer" Size="IconSize.Size32" Filled=true />. Of course, you can edit/change this to your specific needs after pasting.

We hope this makes it a bit easier to choose from the set of over 12.5k available icons. Oh, and if you clone this repository and would like to know how you can update to later releases of the Fluent UI System Icons yourself, we’ve added instructions on how to do that in the ‘Update Icons.md’ file which you can find in the root of the repository

AOT compilation fix

Having all these icons available in an easy-to-use format, means you need to have some sort of structure in your code that is read and exposed to the developers at run time. This is done by a source generator which spits out a huge List. This however did not play nice with AOT compilation (see Ahead Of Time in the docs). The dotnet publish command would just error out.
Investigation led us to this List as being the culprit of the error. In this release the structure has been changed to use a fixed-size array and with that we could successfully use AOT compilation again.

Other changes

Since our last minor release (1.5.0), we’ve done some bug fixing. We also made some other more noteworthy changes. Most notably, a lot of work has been put into the demo site and the component documentation. To sum these up:

• The design has been tuned to work better on mobile and tablet devices (with a special layout for Surface Duo devices!).
• We added (a lot) more comments to the source code and use this information for displaying the API documentation. With this change that documentation will now always stay up-to-date automatically.
• We added highlight functionality to the code samples and added a copy button to make it easier to re-use a sample in your own project.
• We checked each and every component and enumeration against the FAST and Fluent UI Web Components to make sure all parameters and enums are available and correct.
• We split out every example to a separate file and added more structure to the Pages folder by moving each sample page to its own folder.

Looking ahead

While working on this release, we’ve also been working hard on other things. More specifically, version 2 of this library. Why a new major version you might ask. That’s because we are making some big (and breaking) changes. To name a few:

• Integrating the ASP.NET Team’s QuickGrid. Almost all of its functionality will be available in a Fluent UI design (breaking current FluentGrid implementations).
• Completely redo FluentCombobox, FluentListbox and FluentSelect as current implementations do not work well (breaking current implementations of these components).

More will be documented in an upcoming post. We do not have a firm timeline on V2 yet. If you want to try it out right now, a first beta package is available on NuGet. We will release updates to this regularly and make it generally available once we believe it is ready. We can certainly use your help in testing out all the new functionality and reporting issues on where we have not done it completely right yet. Thanks in advance!

What’s new in the Microsoft Fluent UI library for Blazor version 1.6 was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.

Design tokens in FAST

Designers solve many different problems across various categories of experiences. Many of us on FAST have found over the years working on numerous component frameworks that no matter how much time and planning is put into defining a system of guidance and components, there will inevitably be scenarios that challenge it. If the system is too limiting, consuming teams will go with whatever makes sense for the constraints involved at the time, often ignoring the system entirely, or building in such a way that when the system changes, they are left behind.

Design systems implemented primarily through design tokens don’t go far enough in conveying the reasons behind — and relationship between — individual tokens. They are typically a big graph of manually-derived values with a very specific way they are expected to be used. We sought to build a framework for design decisions that describes the design intent, with hooks that allow for scaling to any unique needs of each problem being solved. Individual decisions can be remixed to create new but cohesive experiences. Reducing friction in the system speeds up product development. Designing the system for flexibility keeps the product more aligned with the system intent, with specific and apparent “earned” variations.

Another goal of this system is to evolve the conversation and expectations of design. Many expressions of the design decisions open possibilities to better support individual humans using your product, not limiting the experience to a one-size-fits-some visual design. It’s a new frame of reference compared to traditional design, but the possibilities and advantages become apparent once you’re familiar with the foundation.

Adaptive UI and recipes

FAST introduced an industry-first design token concept called Adaptive UI. Adaptive design tokens, backed by a “recipe”, produce a variable result by calling a function (the “algorithm”) with input parameters, which may be other design tokens. This structure is not much different than the typical chain or aliasing of plain design tokens.

A straightforward example of the need for an adaptive recipe is for the color of “hint” (or “secondary”, “placeholder”, or “metadata”) text. Due to accessibility requirements, text color must always meet 4.5:1 contrast relative to its container’s fill color.

There are many different possible background colors, including main app surfaces, layering, flyouts or dialogs, cards, and banners. There are also gradients and images, and of course both light and dark mode.

The recipe in this example, or the way you would describe the need or decision, is simply to find a color that meets contrast. The recipe is not “grey-40” or some fixed color palette reference that works for only one scenario. Manually picking colors is not a scalable approach for guaranteed accessibility (among other factors). Limiting allowable background colors is not a realistic or scalable approach for design.

Here’s a sample “Person card” component with “hint” text applied to the second line, illustrated in different possible realistic containers:

To solve this in Adaptive UI, the “neutral-foreground-hint-recipe” relies on the “contrastSwatch” algorithm, which simply returns a color meeting the specified contrast. This recipe specifies the desired palette (neutral), the reference color (the container’s fill color), and the minimum contrast value (4.5). It’s wrapped by the “neutral-foreground-hint” token, which is applied to UI elements in the component styles. A component can now be implemented without knowing the context of where it can be safely used, and the design intent (contrast requirement) will always be correct.

Without Adaptive UI, one common attempt to solve this is with color pairs, like “banner-background” and “hint-on-banner-background”. The reason this doesn’t scale well is that any new use case requires a new color pair, and any components that are composed of “hint” text now need to be aware of the context in which they are used (in a banner, dialog, etc.). The various placements of the “Person card” above illustrate how this model breaks. We would need at least four different color pairs. Also, the component would need to know where it’s being placed, or the page author would need to know which design tokens the component is using to override them individually.

With this example we can see how adaptive recipes address the issue of breaking something downstream by changing a design token value — we don’t need to tweak the “foreground-hint” token to get it to work for a particular placement because the recipe determines the correct value based on context.

Let’s track how FAST addresses the original concerns around using design tokens from the first post:

Recipes can describe any design behavior

Of course, we didn’t build Adaptive UI only for 4.5:1 text contrast. Color is a good example because it’s easy to visualize and advanced use cases can’t be solved with CSS functions, but the model scales to any other design values you might need — relational type ramps, adjustable density through padding and spacing, animation, focus indication, elevation treatment, strokes, shape, and whatever else you can imagine within the scope of web design.

Recipes can be built around the context of a group or set of tokens and values. Consider a type ramp. Often the tokens will be indexed like “font-size-1”, “font-size-2”, “font-size-3” or using t-shirt sizes like “typescale.small.size”, “typescale.medium.size”, and “typescale.large.size”. The values for each token were chosen with intention. There is a size which should be used for body text, and other sizes relate to the body text for a cohesive heading and caption design. In the tokens above, the body size is probably “2” or “medium”, but that’s not conveyed through the naming convention, which can lead to not knowing how to use them. One way to handle this is by aliasing the base type ramp sizes to usage, like “caption”, “body”, “heading”, etc. This is a start, but it would be even better if the underlying ramp conveyed the intent.

When it comes to text, it’s important that your content is clearly readable for your customers. It’s probably also desirable that the treatment is consistent across your experience. People all have different visual needs, but unfortunately sites and apps don’t apply font sizes consistently. A modular scale is a great way to relate font sizes to each other and it also helps solve this problem. If you aren’t familiar with this model, it’s probably what you’re approximating by eye anyway.

A modular scale requires some basic math, which can be implemented as a recipe. One input is a “base” type size token that represents the size of the body text. Another input represents the “scale” of the relationship between sizes on the ramp. The output are adaptive tokens that calculate individual sizes relative to the base, like “-1”, “+1”, or “+2”. Your site can maintain the design intent by keeping the “scale” constant but address your customer’s visual or accessibility needs by allowing them to adjust the “base” size for readability.

If your eyes get tired after a long day of staring at a monitor, what if you could increase the font size slightly in the evening hours while maintaining the overall relationship?

With an adaptive type ramp we can move on to more prominent issues than whether a 13, 14, or 15px font size is best for readability.

I think a model like this conveys the intent a lot more with a solid foundation in naming the ramp.

Hierarchical overrides

One of the key features of Adaptive UI is the ability to set the value of a design token for any component within the document hierarchy.

Let’s look at the density system for an example of nesting and overriding token values.

Here we have a marketing site where the design intent is to give the main content some room to breathe. We’ve increased the “density” by “+2”, which has increased the padding within the components and the spacing between them.

We also have a sign in form, but the design intent is for that to be secondary and follow the default “base” density of “0”. These are the same components — same Button and Text field — which can intelligently size themselves by adaptive density. But the density is not inherent to the sign in form, as it might be if we had built the Button and Text fields with t-shirt sizes like “small”, “medium”, and “large”. What if we want to use that same sign in form on a dedicated page? Here’s the same form with only a single design token value changed.

To further this example, perhaps there is a footer that is more compact and uses a “density” like “-1” or “-2”. Again, the same components would be smaller and closer together using the default system. This system works with relative or absolute values. That is, the sign in form could be fixed to use the “base” density, or it could be specified to use relative “-2” density compared to its container.

Implementing relative values like this using CSS functions would be messy because there is no way to get the parent value. You’d have to build it with fixed levels and wouldn’t be able to recompose your components.

For a longer discussion on type ramp sizes and density and the relationship between display scaling or zooming, see my planning for the density system.

I hid another scenario in here, which is that the buttons and fields have a subtle drop shadow. This comes from the “elevation-recipe”, which takes a parameter for the “size” of the elevation and creates a blurred box-shadow. Recipes are just design tokens and have the same features. Here is what we can do if we override the “elevation-recipe” itself and provide a new implementation.

The box shadow is now horizontally offset with no blur. Because we changed the recipe instead of the direct token value, we automatically get the same scale of elevation treatment in both appearances — the plain input fields have a smaller elevation “size” than the buttons.

This model of overriding values can be done for any token in any of the adaptive systems you use or create.

Recipes can support light and dark theming as we saw with “hint” text, or more advanced theming like custom elevation shadows.

Declaring design decisions

There’s another scenario in the previous example, which is the accent color used on the buttons. In the marketing site the default brand color used for the CTAs is green. On the sign in form the accent color has been overridden to blue.

One of the issues I mentioned in the first post is the loss of underlying decisions. In that example we look at different colors of buttons and how the application of rest and hover state is inconsistent. One possible model using Adaptive UI is similar to the “hint” text color example at the start of this post, but in this case for a set of related colors, using the “contrastAndDeltaSwatchSet” algorithm.

The design decision is that buttons darken on hover. This is captured in the value for the “accent-fill-hover-delta” token, “2”, meaning 2 steps darker on the “accent-palette” (it’s helpful to visualize a palette going from white to black, left to right). The decision for the “rest” color is to have contrast of at least 5.5:1, and I’ve added here that the “active” state is lighter than “rest” with a value of “-2”.

The “accent-palette” recipe gets the “accent-base-color” token as a parameter, so we can simply change that single token and the other decisions flow automatically as expected. Regardless of the accent color, the hover and press states use the same design decisions, but with colors derived using the specified base color.

So we can finally answer that question about colors for an orange button:

Just to note, a palette in Adaptive UI is not built for human pattern recognition because the recipes are applying their rules rather than a human needing simplicity and consistency — that is, knowing there are always 10 colors and colors up to “40” are contrast-safe against white, etc. I’ve simplified the palette here to align it more with the initial concern, but under the default settings there are many more colors. In fact, what’s most important, since some recipes use deltas or offsets to pick stateful colors, is the contrast between each color on the palette. If you want your red and green buttons to feel the same when you hover or press them, you need consistent contrast between the swatches. Someday I’ll write a whole post about color palettes.

Now we can check off using underlying design decisions to produce token values.

Notification of changes

The “adaptive” part of the recipes also allows for the output to change in real time according to any input you can imagine — for example, weather, time of day, favorite color, unique accessibility needs, unread email count, or stock market performance. The design token infrastructure is built on an observable pattern, so recipes receive notification when a dependent token changes.

Extending the “hint” text contrast example from earlier, we used the value of “4.5” for standard AA contrast requirements. What if we wanted to support the “prefers increased contrast” preference and a WCAG AAA rating with “7:1” contrast? With the color recipe we can simply use a “foreground-hint-contrast” token and change the value from “4.5” to “7” when someone enables that option, everywhere that recipe is used will update to the new color automatically.

Hopefully it’s becoming apparent how solving the next wave of key design and accessibility problems requires algorithms and effort, and how we’ll never get there with traditional design definitions, even as we start using design tokens.

In part 3 (coming soon) we’ll look at ways to solve some of the remaining concerns with an idea I’ve been calling “modular styling”, some design-to-code tooling, and improvements using the JSON tokens format.

Evolution of design tokens and component styling, part 2 was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.

Directives are a great way to increase your efficiency when composing templates. But just because they are available, it does not mean they should be used in every scenario. Misusing these can have performance implications and clutter your codebase. In this post, let’s take a closer look at the when directive and compare different conditional cases.

If you are not familiar with FAST directives, take a look here: Using Directives | FAST.

According to the documentation, the when directive enables you to conditionally render blocks of HTML. In other words, it is another way of writing if (condition) { //do something } .

Good use case

This is an example of using if (condition) { //do something } to render our happyTemplate based on the value of the happy property :

With the when directive, we can achieve the same condition check and reduce the if (condition) { //do something } to just one line of code:

Doesn’t this small refactor make you happy?

The when directive is great for the replacement of a single if (condition) { //do something }. The value provided here is making the block of code less verbose.

How about performance? Let’s run some benchmarks comparing these two implementations.

NOTE: All benchmarks are run with fast-benchmarks, and the sample size for each benchmark is 50 with auto-sampling turned on. For a little more context, when we compare 2 versions, a minimum of 100 samples will be run in total. With auto-sampling set at 1 minute, samples will keep increasing until it hits the 1-minute mark.

local version — represents if (condition) { //do something }
master version — represents when directive

To summarize the results:

1. The blue boxes indicate that between the 2 implementations, there was no statistical performance difference in javascript execution time and memory consumption.
2. The green boxes show that if (condition) { //do something } bundle size turns out to be more than — 129.86kb compared to the 129.80kb — when directive

These results show that using the when directive here provides better readability and slightly improved bundle size. This is primarily the purpose of the when directive.

Here’s another way you might think to refactor the previous if (condition) { //do something } without the when directive by using the && operator :

This is also a valid and aesthetically pleasing implementation. Let’s run a benchmark to compare this with the when directive implementation :

local version — represents &&
master version — represents when directive

To summarize the results:

1. The blue boxes indicate that between the 2 implementations, there was no statistical performance difference in javascript execution time and memory consumption.
2. The green boxes show that if (condition) { //do something } bundle size turns out to be more than — 129.82kb compared to the 129.80kb — when directive

Surprise, surprise! when directive is still the winner here in terms of bundle size. When you want to render a template based on a single condition, this nifty when directive is your go-to.

Given these results, the guidance here is to use the when directive to reduce overall bundle size (every byte counts!).

Bad use case 1

While the when directive comes in handy in the previous scenarios; it does not provide optimizations in every scenario.

For example, just as you would not do something like this in your code:

You should not do this with the when directive:

Let’s expand both these implementations and see how they look in the bigger picture, starting with the when directive:

While there are no errors in this implementation, I hope you can see that this can quickly become unmanageable if more conditions are added. Additionally, by separating the two lines of when directive code, it may make it seem like the 2 conditions are not related. This is just an if...else statement, so we should write it as one.

Here’s one way to refactor this with the ternary operator, and eliminating the when directive.

This is arguably more readable than the previous when directive example. Here are the benchmark results between the when_long_example.ts and if_long_example.ts:

NOTE: For this particular benchmark, the click event handler on the button is triggered 10x for each sample taken to switch between templates.

local version — represents ternary operator
master version — represents when directive

To summarize the results:

1. The blue boxes indicate that between the 2 implementations, there was no statistical performance difference in javascript execution time and memory consumption.
2. The green boxes show that ternary operator bundle size turns out to be less than — 130.82kb compared to the 130.88kb — when directive

Given these results, the guidance here is to use the ternary operator to reduce overall bundle size (every byte counts!).

Up to this point, you should get the idea that when directive is valuable as a replacement for if (condition) { //do something }. Outside of this scenario, it is not recommended when working with conditionals or dynamic templates.

Bad use case 2

Let’s look at some more examples to illustrate common misusage of the when directive. Here’s how you might use the when directive to handle templates that change depending on a series of conditions:

If you aren’t careful, you could easily make the error of displaying multiple templates at the same time with the when directive(I made this mistake while drawing up this example).

Let’s summarize what we’re trying to achieve and think about a more effective implementation. Depending on what the emotionalLevel value is, we want to render the corresponding template:

0–1 depressed
2–3 sad
4–5 indifferent
6–8 happy
9–10 ecstatic

With a switch statement you can define the numbers in a specific range, but with the when directive you’d have to be more explicit. Check out the example below using the switch statement:

This implementation is less error-prone and gives better context on how the emotionLevel relates to each of the templates.

Let’s do a quick sanity check with a benchmark run:

NOTE: For this particular benchmark, the click event handler on the button is being triggered 10x for each sample taken to switch between templates. The emotionLevel is incremented from 0–10.

local version — represents switch statement
master version — represents when directive

To summarize the results:

1. The blue boxes indicate that between the 2 implementations:
   A. There was no statistical performance difference in javascript execution time.
   B. Memory consumption was faster with the switch statement compared to the when directive
2. The green boxes show that switch statement bundle size turns out to be less than — 130.94kb compared to the 131.01kb — when directive

Given these results, the guidance here is to use the switch statement to reduce overall bundle size (every byte counts!) AND memory optimization.

The fun does not have to stop here, you can keep thinking of cleaner ways to refactor your code where it makes sense. For example, if you prefer your template to be less cluttered, you can move the switch statement into its own method and use a map to find the template that matches the condition.

This would undoubtedly result in more code, and running a benchmark confirms that bundle size increases. See below:

NOTE: For this particular benchmark, the click event handler on the button is being triggered 10x for each sample taken to switch between templates. The emotionLevel is incremented from 0–10.

local version — represents map
master version — represents when directive

To summarize the results:

1. The blue boxes indicate that between the 2 implementations:
   A. There was no statistical performance difference in javascript execution time.
   B. Memory consumption was faster with the map solution compared to the when directive
2. The green boxes show that map bundle size turns out to be more than — 131.25kb compared to the 131.01kb — when directive

Given these results, the guidance here is to still use the switch statement in the template over the map and when directive solutions if you want both the benefit of smaller bundle size and memory optimization.

While this may not be the most optimized implementation for this particular scenario, if your switch statements become longer, the results could quickly shift to favor the map solution. It’s important to be able to adapt to different scenarios.

In summary, when you are simply working with a single if statement in your template, you should be using the when directive. On the other hand, when you have more complex conditional situations, it is better to omit the use of the when directive !

Performance results can fluctuate depending on how complex your conditionals or templates become. If you keep this in mind, you can continue to improve the codebase you are working on.

When to use when? was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.

Design tokens in the industry

Defined generally, “design tokens” are quickly becoming the industry-wide method to organize and build design values into interface components. Unfortunately, there are currently many implementations, tools, and formats in use across different authors or technologies, but with the release of the W3C Design Tokens Community Group Draft Report, we can hopefully start to converge on at least a few key aspects.

This is a community group, and the output is more of a recommendation than an official platform spec. This article will refer to this as the “format”, “recommendation”, or “recommended format”.

Benefits

Here are a few of the positive impacts of design tokens in general, and their increasing coherence through industry alignment.

Centralize definitions

At the most basic level, design tokens exist to externalize design values to a central location that can be referenced broadly. Because they’re central, they can be modified for a given use case and will apply consistently. For example, a component framework can be implemented to reference a “brand-color” token instead of hard-coding the same color everywhere.

Now we can simply change the value associated with the token, and the components follow.

Note the arrows all point to the left, which is an important distinction we’ll look at in “Design to code” in part 3. This flow indicates each specific use is referencing a known and expected less-specific definition.

Intended for interop

Centralized definition is what CSS preprocessors like SASS or LESS brought us, but the intent of design tokens is to be agnostic to the technology to increase interoperability. That is, the same token definitions could be used across Android, iOS, XAML, or various web frameworks. To achieve this, the recommendation defines JSON as the definition format.

Translatable

A common format is important, but the chosen JSON format is not natively rendered by presentation technologies. The way to handle this is through translation tooling, of which there are several options. Amazon’s Style Dictionary is very flexible, regularly maintained, and has many references across the industry. Salesforce’s Theo and Diez haven’t been updated in a couple of years, though they may still be viable for some uses. There’s also Specify, which is marketed as a “Design data platform” service, which seems promising but less open than other solutions. AdobeXD has also defined a Design System Package format. All these tools fit somewhere between the design definition and implementation.

Note that all tools may not support the recommended format at this time.

Current concerns

Even with the options available today, there are many gaps to fill and misuses to resolve.

No standard for naming

Following the many implementations, formats, and tools mentioned above, there is also no standard around the structure or naming of design tokens. This means that even as a common format gains support, there are no agreements in sight that will enable interoperability across design systems or component frameworks.

For example, here are the tokens for two popular design systems representing the brand color:

• Google Material Design 3: md.sys.color.primary (md=Material Design, sys=System)
• Salesforce Lightning: colorBrand or brand-primary (they have two sets?)

Given that there is often a need to mix and match component libraries, having no consistent way to apply design values poses some challenges. For example, consider combining two complicated components like a calendar from one library and a shopping cart from another. You would need to configure each component’s specific design tokens to coordinate the brand color, among any other attributes you might want to unify.

For a simpler case, there’s really no reason for many component frameworks to build yet another Button, but they will if that’s the only way to apply their design tokens.

No standard for applying tokens

There are also no standards for how to apply tokens to components. For example, every component framework I can think of has a brand-colored Button, but there’s no universal way to connect the “brand-color” token (or whatever it’s called) to the Button’s fill.

The work happening under Open UI could provide some necessary portion of a solution to this. This project seeks to define a base anatomy for common components. For example, a Button has “content” and “root” parts. The “root” represents the main visual container of the Button, which is where the fill color is applied for this component. A reasonable representation of addressing this is “button.root.fill”.

The “Design to code” proposal in part 3 seeks to bridge design token definitions with UI implementations in a way that any components which support declarative anatomy can take advantage of declarative styling.

Not tracking the underlying decisions

The point of a design “system” is that many individual decisions come together for a cohesive outcome. Design tokens work well for defining specific values, but the underlying decision that produces a specific value is lost or not applied consistently. A great example of this is often seen in color choices for interactive components like Buttons or between light and dark modes.

Looking back to the brand color Button scenario, here are the “brand” rest and hover colors Salesforce defines as tokens:

These colors are “blue-50” and “blue-30” respectively.

Here are the rest and hover colors for a “success” Button:

These colors are “green-70” and “green-50”. The colors are still offset two spaces on the palette, but lighter, such that the success button requires flipping the text to meet contrast. Without context, this feels like an odd choice and there doesn’t seem to be a clear rule as to the selection of the “success” colors relative to “brand”.

Let’s look at one more example, for Salesforce’s “destructive” button:

Here they are “red-40” and “red-30”. No consistent pattern between where the colors sit on the palette or how much space is between them.

If a designer needed an orange button for a warning, what rule should they use to select the colors from the palette? There’s no way to know because the decisions that went into these examples aren’t described in the flow of the token references.

Potential to make individual changes that break downstream

This gap builds upon the previous point about not tracking underlying decisions.

Every major design token implementation relies on aliasing or referencing “base” or “global” tokens to increase specificity of use. For example, the “background-success” color used for the rest state of the button above references “green-70”, which is assigned the actual fixed color value.

A designer needs to style a “success” slider and uses “background-success” for the fill. They realize that for a slider to be accessible it must meet 3:1 contrast with the container. The app background color of #f3f3f3 requires “green-50” to meet contrast so they change “background-success” from “green-70” to “green-50”.

Because the Button also references “background-success”, it now uses “green-50” for both the rest and hover state, which is unexpected, and worse yet the Button foreground color is no longer accessible. Because the “success” Button wasn’t used in this part of the experience, the designer didn’t notice it was broken.

There may be additional layers of aliases, which introduces more potential for unexpected changes.

Obviously, designers need to be very careful when changing underlying tokens, but this is a common pain point and tradeoff. Either you update the value to “fix” the system, or you deviate and create yet another intermediate token, which must then be tracked, understood, and used correctly.

No inherent support for theming

Customers are expecting more from the visual design of their experiences. At a minimum, they expect dark mode in addition to the historically default light mode. Many also rely upon accessibility features, including the ability to request increased contrast or reduced motion. These features are not commonly supported across the web currently, but the fact that they are built into the web platform means it’s time for experiences built for browsers to catch up.

Most design token systems don’t have a concept to support theming other than to completely override all token values. This is feasible for building a dark mode, but is a manual process which must be kept in sync with the base set of tokens or the light mode tokens it overrides. All colors must also meet contrast requirements. This approach is time-consuming, error-prone, and doesn’t scale to support true customization and personalization.

Using t-shirt sizes to express options

Design tokens that represent a ramp of choices, like for spacing, border radius, and font size, are often expressed using t-shirt sizes like small, medium, and large. While the sequence is well known, it can break down in actual use and inevitable extension or modification in the future. For example, here are Material Design’s latest shape tokens:

One issue is the size token names impart meaning that doesn’t exist. For instance, “medium” happens to be in the middle, but it’s not the most commonly used, and by default applies only to a Card. Compare that to Lightning design where “medium” is only 4px and used as the default for many controls like Button and Text Inputs.

Another issue arises when additional sizes are needed. Ideally in a true “system” we can avoid this, but a token structure needs to support design without getting in the way. We can add on, like “extra-extra-large” or in between like “small-medium”, but this can get messy quickly.

Leads to copies of complicated CSS

Styling components is complicated. There are many CSS attributes that must be applied, and CSS is finicky enough that if this isn’t done consistently you will get different results.

Consider a Button. It will at least have attributes for the “content” font and color, and the “root” background color. It will likely be stateful, so multiply this by “rest”, “hover”, “active”, “focus”, and “disabled”. It may also have a border with color, thickness, radius, and a dash pattern. It could have a drop shadow for elevation, some animation timing, some layout settings, it may be selected, and the list goes on.

Consider just one portion of that example, applying a background color for rest, hover, and active states. That’s three CSS selectors and three tokens, one for each. Then you go to test it and realize that even a Button in “disabled” state is responding to the “hover” state. That selector needs to apply only when the component is enabled. Then you realize the hover state isn’t responding correctly on a touch device. That selector also needs a media query.

Now you have to repeat that for every other component that may respond to hover and active states, may be disabled, may be used with touch, etc. And that’s only one example. Tokens are good for providing the values, but they’re not enough to make sure they are applied correctly and consistently.

Make sure to follow FAST for part 2 and part 3 (coming soon) that look at what we can do to solve this in a creative and flexible way.

Evolution of design tokens and component styling, part 1 was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.

• New component: <FluentSearch>
• New component: <FluentCalendar>
• New and updated icons

And some more ‘under the hood’ changes:

• Added an example showing inheriting to bind to theoninput event
• Changed enum names to match Web Components names
• Used FluentIcon instead of SVGs in example pages
• Added support for more event handling
• Added support for more bindings
• Other changes

New component: <FluentSearch>

A new addition to the Fluent UI Web Components is the FluentSearchcomponent (example here). Of course we’ve brought this over to the Blazor component set as well. It looks like this:

New component: <FluentCalendar>

Another addition to the Web Components is the FluentCalendar component (example here). It has been added to the Blazor set and will, in the future, be used as part of a date picker component. It looks like this:

Note: At the moment there is still a bug in the display of the calendar when the week has a start day other than Sunday (as can be seen above). This will be fixed in a later update.

The changes and additions described below are a bit more low-level and more for developers than for end-users of the library.

New and updated icons

The <FluentIcon> component uses the Fluent UI System Icons collection. We have updated and imported all the icons from version 1.1.176.

Example of inheriting to bind to oninput event

All the Input related components, like FluentTextField, FluentTextArea and FluentNumberField are set up to do binding on the onchange event. In most situations this is fine but sometimes you might need a binding to occur within an oninput event. This is possible by inheriting the component in question and changing/adding some of the parameters in the .razor file. An example of this is now provided in the FluentNumberFieldOnInput.razor file in the examples/FluentUI.Demo.Shared/Shared/ folder.

Change enum names to match Web Components

There have been some massive improvements to the FAST documentation. This makes a lot of information much more discoverable. Because of this we wanted to make some changes on the Blazor side as well so we have re-implemented most of the enum types. Initially we added these with very generic names like Direction and Orientation. Based on these new docs, we concluded that these should have names much more related to the components they are being used in (i.e. FlipperDirection and TabsOrientation). We have updated all the enumerations concerned and marked all the old ones as obsolete. These 'wrong' enums will be removed in a later version of the library.

Use FluentIcon instead of SVGs in example pages

A lot of the examples in the demo sites were still using plain inline SVGs when showing an icon. These have all been changed to use the (recently introduced) <FluentIcon> component.

Support for more event handling

The new docs also showed that there are events available on components which we were not yet handling on the Blazor side. Examples of these are change events on the Accordion and Tabs components. The complete list of Blazor components with new event handling are:

All of the ...EventArgs above, besides the HorizontalScrollEventArgs, are coded in a way that they contain the actual affected component as a parameter. This means you can call any method or work with any parameter the component supports in the event handling code.

Here’s an example of this kind of event handling:

More examples of event handling can be found in the Pages folder under examples/FluentUI.Demo.Shared/ folder

Support for more bindings

We have also added support for some more bindings:

• <FluentTabs> : Bind the ActiveId parameter to the id of the active tab
• <FluentTreeView> : Bind the CurrentSelected parameter to the currently selected tree item
• <FluentCalendar> : Bind the SelectedDates parameter to the List<DateOnly> of selected dates
• <FluentAccordion>* : Bind the ActiveId parameter to the id of the active accordion item

*= not fully implemented yet. We are waiting for the necessary changes in the underlying web components implementation.

Here’s an example of a binding with the FluentCalendar component:

More examples of the bindings can be found in the Pages folder under examples/FluentUI.Demo.Shared/ folder.

Other changes

Some other (smaller) changes we have made to the library are:

• Added Disabled and Text parameters to <FluentTab>
• Added Heading parameter to <FluentAccordionItem>
• AddedTextparameter to <FluentTreeItem>
• Fixed working the ActiveIndicator parameter on <FluentTabs>
• Added DisabledSelectable parameter to <FluentCalendar> (defaults to true)
• Added OutOfMonthSelectable parameter to <FluentCalendar> (defaults to true)

What’s next?

We are already thinking about what we could add, change and update in the next couple of releases. Please chime in with your own ideas on our GitHub Discussions or Discord channel. For sure, a (major) new release will arrive after we have updated our Blazor wrappers to the upcoming Fluent UI Web Components v3 release (no firm dates yet). We are also hard at work on improving the documentation. We are going through each and every component and if we find things like parameters or events that are present in the Web Components or underlying FAST Foundation but missing on the Blazor side, we will add them of course. This will most likely be done with minor version releases like 1.5.1, 1.5.2, etc. We will continue to keep you up to date as these versions ship.

What’s new in the Microsoft Fluent UI library for Blazor version 1.5 was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.

The discussion covered so much content that it needed to be split into two episodes:

• Part 1: Episode 14 — Web Components with Chris Holt and Rob Eisenberg
• Part 2: Episode 15 — Web Components with Chris Holt and Rob Eisenberg

We hope you enjoy listening to the conversation 😃

FAST Web Components on 20minJS was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.

One of the most ubiquitous array operations is iteration. The repeat directive in @microsoft/fast-element makes the process of iterating and rendering lists a seamless experience. If you are unfamiliar with this, take a quick read here: Using Directives | FAST.

While the repeat directive already provides robust out-of-the-box performance optimizations, you can take this further by understanding how and when to use the repeat options parameter. In this article, we are going to take a look at the recycle property.

What does recycle do?

By default, recycle is set to true. This setting means that the repeat directive will reuse views instead of creating new ones from the template whenever possible.

Here’s a basic example of using repeat in a template:

Let’s say this is our initial friends list: [“London", “Austin", “Chris"] .

Running the above code will iterate through the friends list and list each friend by name. Under the hood, a new view will be created for each item. Simple enough.

Now, I’ve decided I want some new friends, so I replace the friends list with: [“Fernando", “Satoshi", “Mi"].

You can see that structurally, nothing much has changed: the template stays the same, and the friends list is still an Array with three items.

The only thing that changed here is the data, which is where the beauty of recycling views comes in. repeat will find the existing view from the template and replace only the data: "London" will be replaced with "Fernando", and so on.

Benchmark results between {recycle: true} and {recycle: false}

Let’s run some benchmarks to compare what happens when recycle is turned off. For context, the following benchmarks are run with fast-benchmarks with a sample size of 30.

.reverse()

• 1000 items in array [itemCount]
• .reverse() is run 100 times for each run [loopCount]

In basic templates like the example above, it is more performant to recycle views — different variations of itemCount and loopCount report similar results.

Well, that’s convenient! Why would you ever want to turn off the recycle option? That leads us to the next topic.

When to turn off the recycle option?

When your data starts becoming more complex, there is a threshold of when recycling views becomes more cumbersome than creating new views from scratch.

Here is an example of a template that uses some nested repeat directives:

Benchmark results between {recycle: true} and {recycle: false} with a nested template

Things start to get interesting when comparing results between {recycle:true} and {recycle: false}.

.splice()

• 50 items in array [itemCount]
• .splice(i, deleteCount = 10, …generateData(addCount=10)) is run 5 times for each run [loopCount]

Wait, the version with recycle turned on no longer shows that it is faster than recycle turned off. Take a look at the following screenshot:

The memory consumption is more performant when recycle is turned off in a nested template. This outcome makes sense logically. If you think about it, it will probably take more memory to locate a nested item and switch out the data than simply creating a new one. This situation is where the value of turning off the recycle property comes into play.

How to turn off the recycle option?

Turning off the recycle property is as easy as setting the options at the end of your repeat block.

Let us reiterate our findings from the benchmarks we ran; when we have a template with nested repeat directives, it is more performant to set the recycle option to false.

Here’s an example of how you can set that on the template with nested repeat directives:

Make sure you define {recycle: false} within the repeat block, right after you define your template.

Here’s the same example with the template extracted from the repeat block:

Understanding how to use the features of the repeat options will help you think in a data-driven way and give you significant performance gains.

Learn more about repeat and other directives in our documentation on Using Directives | FAST.

Optimize list rendering with repeat’s view recycling feature was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.

In short, the two big end-user additions (besides some bug fixes) are:

• Fluent UI System Icons support
• Design Token support

And repository and code changes:

• Add missing xml comments
• Add FocusAsync methods to FluentInputBase

Fluent UI System Icons support

The Fluent UI System Icons are a (still growing) collection of familiar, friendly, and modern icons from Microsoft. Currently, more than 2020 distinct icons are available in various sizes of filled and outlined versions. The collections consist of well over 11k icons in SVG format. All of them have been added to the library in an easy-to-use way by adding the <FluentIcon> component. Just putting this in your .razor page:

Will give you this:

A couple of things to unwrap here on the parameters used:

• Name is a string. All names have been added as constants to make it easier to select an icon. IntelliSense will help you find the right one. It is also using the new .NET 6 EditorRequired feature. If you don’t pass a value for the Name, Visual Studio will point that out to you in design time and raise a compile error when building.
• Size is using an enum that holds all the possible valid sizes. Note that not all sizes are available for all icons. If you get an error at run-time, supply a different size or remove the parameter to fall back to the default size (IconSize.Size24).
• Filled is a bool to choose a filled (true) or a regular/outlined (false) version of an icon.

Other parameters (not shown in the example above) for this component are:

• UseAccentColor (bool). This parameter defaults to true and determines if the accent color is used for the fill or the outline when rendering the icon. When setting this to false, the icon will be rendered in black.
• NeutralCultureName (string). Some icons offer alternative versions for specific languages. By supplying the two-letter neutral language code, you can indicate that you would like to use that specific version of an icon. The component will fall back to rendering the original version if there is no language-specific version.
• Slot (string). With the slot parameter you can indicate where an icon needs to be rendered in the context of another component. For example, when combining a <FluentButton>with a <FluentIcon>, you can use the slot to put the icon in front of the button text:

Note that while the icon is positioned after the “Search” text in the markup, it will render before the button text because the slot=start. Here’s what it looks like:

The temporary demo site has a page to search through all the available icons and sizes.

In earlier and other libraries, icons are often included using fonts. This method has the disadvantage that the whole font needs to be downloaded even if you only use one icon. Instead, we stepped away from using that method in this library and opted for taking the SVG route. Because the icons are SVG files stored in the wwwroot folder in an RCL (Razor Class Library), they are treated like static files on the server. They don’t get downloaded until requested, and only the icons you are actually using will be downloaded.

Design Token support

The Fluent UI Web Components are built on FAST’s Adaptive UI technology, enabling design customization and personalization while automatically maintaining accessibility. This is accomplished through setting various “Design Tokens”. In previous versions of this library, the only way to manipulate the design tokens was through using the <FluentDesignSystemProvider> component. This Blazor component (and its underlying Web Component) exposed over 60 variables that could be used to change things like typography, color, sizes, UI spacing, etc. FAST was extended a while ago and now has a much more granular way of working with individual design tokens instead of just a design system provider model. See https://docs.microsoft.com/en-us/fluent-ui/web-components/design-system/design-tokens for more information on how Design Tokens work.

In total, there are now over 160 distinct tokens defined in the Adaptive UI model, and as of version 1.4 of this library, you can use all these in Blazor as well! The implementation has been in the works for multiple months, and we think the result is quite flexible. It allows for usage both from C# code as well as declaratively in your .razor pages. The two ways of working with design tokens are described below (taken from the repository readme):

Option 1: Using Design Tokens from C# code

Given the following .razor page fragment:

You can use Design Tokens to manipulate the styles from C# code as follows:

As seen in the code above (with the ref4.Element), it is possible to apply multiple tokens to the same component.

For Design Tokens that work with a color value, you must call the ToSwatch() extension method on a string value or use one of the Swatch constructors. This ensures the color uses a format that Design Tokens can handle. A Swatch has a lot of commonalities with the System.Drawing.Color struct. Instead of the values of the components being between 0 and 255, in a Swatch they are expressed as a value between 0 and 1.

⚠️ IMPORTANT

The Design Tokens are manipulated through JavaScript interop working with an ElementReference. There is no JavaScript element until after the component is rendered. This means you can only work with the Design Tokens from code after the component has been rendered in OnAfterRenderAsync and not in any earlier lifecycle methods.

Option 2: Using Design Tokens as components

The Design Tokens can also be used as components in a .razor page directly. It looks like this:

To make this work, a link must be created between the Design Token component and its child components. This is done with the BackReference="@Context" construct.

ℹ️ NOTE

Only one Design Token component at a time can be used this way. If you need to set more tokens, use the code approach as described in Option 1 above.

Besides these two new options, the original <FluentDesignSystemProvider> component is still there and can be used as always. There are no plans to remove this anytime soon.

XML Comments

All components and all component parameters now have XML comments. This means that tools that support this, like Visual Studio IntelliSense, will show you information about methods and parameters when editing your razor pages and code, making it a bit easier to discover and understand functionality:

Add FocusAsync to FluentInputBase

It was not possible before to programmatically set focus to an <input> deriving component like the <FluentTextField> or <FluentNumberField>. The base class <FluentInputBase> has now been extended to expose this method.

Wrapping Up

We’re excited to bring these powerful new design token and icon capabilities to Blazor developers and can’t wait to see what you’ll build with them. As FAST and the Fluent UI Web Components evolve, we’ll continue to work hard to bring you more components, features, and improvements like these.

What’s new in the Microsoft Fluent UI library for Blazor versions 1.3 and 1.4 was originally published in FAST on Medium, where people are continuing the conversation by highlighting and responding to this story.