Merge pull request #142 from microsoft/design-tokens

(feature) Design tokens

Author: vnbaaij

README.md

@@ -38,7 +38,6 @@ To add the script from CDN use the following markup:
 The markup above always references the latest release of the components. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:
 
 ```html
-
 <script type="module" src="https://cdn.jsdelivr.net/npm/@fluentui/web-components@2.0.2/dist/web-components.min.js"></script>
 ```
 
@@ -60,7 +59,7 @@ Copy this to your `wwwroot/script` folder and reference it with a script tag as
 
 > :notebook: **Note**
 >
-> If you are setting up Fluent UI Web Components on a Blazor Server project, you will need to escape the `@` character by repeating it in the source link. For more information check out the [Razor Pages syntax documentation](/aspnet/core/mvc/views/razor).
+> If you are setting up Fluent UI Web Components on a Blazor Server project, you will need to escape the `@` character by repeating it in the source link. For more information check out the [Razor Pages syntax documentation](https://docs.microsoft.com/aspnet/core/mvc/views/razor).
 
 In your Program.cs file you need to add the following:
 ```csharp
@@ -93,33 +92,133 @@ Here's a small example of a `FluentCard` with a `FluentButton` that uses the Flu
 ```
 > :bulb: **Tip**
 > 
-> You can add `@using Microsoft.Fast.Components.FluentUI` to namespace collection in `_Imports.razor`, so that you can avoid repeating it in every single razor page.
+> You can add `@using Microsoft.Fast.Components.FluentUI` to the namespace collection in `_Imports.razor`, so that you can avoid repeating it in every single razor page.
 
 
 ### Configuring the Design System
 
-The Fluent UI Web Components are built on FAST's Adaptive UI technology, which enables design customization and personalization, while automatically maintaining accessibility. This is accomplished through setting various "design tokens". The easiest way to accomplish this in Blazor is to wrap the entire UI in a `FluentDesignSystemProvider`. This special element has a number of properties you can set to configure the tokens to your desired settings. Here's an example of changing the "accent base color" and switching the system into dark mode (in the file `app.razor`):
+The Fluent UI Web Components are built on FAST's Adaptive UI technology, which enables design customization and personalization, while automatically maintaining accessibility. This is accomplished through setting various "Design Tokens". As of version 1.4 you can use all of the (160) individual Design Tokens, both from code as in a declarative way in your `.razor` pages. See https://docs.microsoft.com/en-us/fluent-ui/web-components/design-system/design-tokens for more information on how Design Tokens work
+
+#### Option 1: Using Design Tokens from C# code
+
+Given the following `.razor` page fragment:
+```html
+<FluentButton @ref="ref1" Appearance="Appearance.Filled">A button</FluentButton>
+<FluentButton @ref="ref2" Appearance="Appearance.Filled">Another button</FluentButton>
+<FluentButton @ref="ref3" Appearance="Appearance.Filled">And one more</FluentButton>
+<FluentButton @ref="ref4" Appearance="Appearance.Filled" @onclick=OnClick>Last button</FluentButton>
+
+```
+You can use Design Tokens to manipulate the styles from C# code as follows:
+
+```csharp
+[Inject]
+private BaseLayerLuminance BaseLayerLuminance { get; set; } = default!;
+
+[Inject]
+private AccentBaseColor AccentBaseColor { get; set; } = default!;
+
+[Inject]
+private BodyFont BodyFont { get; set; } = default!;
+
+[Inject]
+private StrokeWidth StrokeWidth { get; set; } = default!;
+
+[Inject]
+private ControlCornerRadius ControlCornerRadius { get; set; } = default!;
+
+private FluentAnchor? ref1;
+private FluentButton? ref2;
+private FluentAnchor? 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(ref2!.Element, "#185ABD".ToColor());
+
+		//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);
+
+		StateHasChanged();
+	}
+
+}
+
+public async Task OnClick()
+{
+	//Remove the wide border
+	await StrokeWidth.DeleteValueFor(ref4!.Element);
+}
+```
+As can be seen in the code above (with the `ref4.Element`), it is posible to apply multiple tokens to the same component. 
+
+For Design Tokens that work with a color value, it is needed to add the `ToColor()` extension method on the string value. This converts the string into a RGB value that the Design Token can operate with. Internally we are using the `System.Drawing.Color` struct for this and this means you can use all the available methods, operators, etc from that namespace in your code too.
+
+> :notebook: **Note**
+> 
+> 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 directely. It looks like this:
+
+```html
+<BaseLayerLuminance Value="(float?)0.15">
+	<FluentCard BackReference="@context">
+		<div class="contents">
+			Dark
+			<FluentButton Appearance="Appearance.Accent">Accent</FluentButton>
+			<FluentButton Appearance="Appearance.Stealth">Stealth</FluentButton>
+			<FluentButton Appearance="Appearance.Outline">Outline</FluentButton>
+			<FluentButton Appearance="Appearance.Lightweight">Lightweight</FluentButton>
+		</div>
+	</FluentCard>
+</BaseLayerLuminance>
+```
+
+To make this work, a link needs to be created between the Design Token component and its child components. This is done with the `BackReference="@context"` construct. 
+
+> :notebook: **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.
+
+
+#### Option 3: Using the `<FluentDesignSystemProvider>`
+The third way to customize the design in Blazor is to wrap the entire block you want to manipulate in a `<FluentDesignSystemProvider>`. This special element has a number of properties you can set to configure a subset of the tokens. **Not all tokens are available/supported** and we recommend this to only be used as a fall-back mechanism. The preferred mehod of working with the desgn tokens is to manipulate them from code as described in option 1. 
+
+Here's an example of changing the "accent base color" and switching the system into dark mode (in the file `app.razor`):
 
 ```html
 <FluentDesignSystemProvider AccentBaseColor="#464EB8" BaseLayerLuminance="0">
-    <Router AppAssembly="@typeof(App).Assembly">
-        <Found Context="routeData">
-            <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
-        </Found>
-        <NotFound>
-            <PageTitle>Not found</PageTitle>
-            <LayoutView Layout="@typeof(MainLayout)">
-                <p role="alert">Sorry, there's nothing at this address.</p>
-            </LayoutView>
-        </NotFound>
-    </Router>
+	<Router AppAssembly="@typeof(App).Assembly">
+		<Found Context="routeData">
+			<RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
+		</Found>
+		<NotFound>
+			<PageTitle>Not found</PageTitle>
+			<LayoutView Layout="@typeof(MainLayout)">
+				<p role="alert">Sorry, there's nothing at this address.</p>
+			</LayoutView>
+		</NotFound>
+	</Router>
 </FluentDesignSystemProvider>
 ```
 
 > :notebook: **Note**
 > 
-> Provider token attributes can be changed on-th-fly like any other Blazor component attribute.
+> FluentDesignSystemProvider token attributes can be changed on-the-fly like any other Blazor component attribute.
 
+#### Colors for integration with specific Microsoft products
 If you are attempting to configure the components for integration into a specific Microsoft product, the following table provides `AccentBaseColor` values you can use:
 
 Product | AccentBaseColor
@@ -135,6 +234,7 @@ Product | AccentBaseColor
 
 For a list of all available token attributes, [see here](https://github.com/microsoft/fast-blazor/blob/main/src/Microsoft.Fast.Components.FluentUI/Components/FluentDesignSystemProvider.razor#L69). More examples for other components can be found in the `examples` folder [of this repository](https://github.com/microsoft/fast-blazor).
 
+
 ##  Web components / Blazor components mapping, implementation status and remarks
 Web component | Blazor component | Status | Remarks
 ----------------- | -------------- | ------ | -------

examples/FluentUI.Demo.Client/FluentUI.Demo.Client.csproj

@@ -7,8 +7,8 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="6.0.3" />
-    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="6.0.3" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="6.0.4" />
+    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer" Version="6.0.4" PrivateAssets="all" />
   </ItemGroup>
 
   <ItemGroup>

examples/FluentUI.Demo.Client/wwwroot/appsettings.json

@@ -0,0 +1,3 @@
+{
+  "_FluentWebComponentsScriptSource": "https://cdn.jsdelivr.net/npm/@fluentui/web-components/dist/web-components.js"
+}

examples/FluentUI.Demo.Client/wwwroot/css/site.css

@@ -77,6 +77,7 @@
     background-color: var(--fill-color);
     color: var(--neutral-foreground-rest);
     padding-inline-start: calc(var(--design-unit) * 6px);
+    padding-inline-end: calc(var(--design-unit) * 6px);
 }
 
 
@@ -90,6 +91,7 @@
     position: fixed;
     width: 100%;
     z-index: 1000;
+    margin: 20px 0;
 }
 
     #blazor-error-ui .dismiss {

examples/FluentUI.Demo.Server/appsettings.json

@@ -5,5 +5,6 @@
       "Microsoft.AspNetCore": "Warning"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "*",
+  "FluentWebComponentsScriptSource": "https://cdn.jsdelivr.net/npm/@fluentui/web-components/dist/web-components.min.js"
 }

examples/FluentUI.Demo.Server/wwwroot/css/site.css

@@ -76,6 +76,7 @@
     background-color: var(--fill-color);
     color: var(--neutral-foreground-rest);
     padding-inline-start: calc(var(--design-unit) * 6px);
+    padding-inline-end: calc(var(--design-unit) * 6px);
 }
 
 
@@ -89,6 +90,7 @@
     position: fixed;
     width: 100%;
     z-index: 1000;
+    margin: 20px 0;
 }
 
     #blazor-error-ui .dismiss {

examples/FluentUI.Demo.Shared/FluentUI.Demo.Shared.csproj

@@ -12,7 +12,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="6.0.3" />
+    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="6.0.4" />
   </ItemGroup>
 
   <ItemGroup>