If you've ever tried to build consistent, custom markup structures for a website or an app, you might have looked at web components. As they're standards compliant and supported by all the main evergreen browsers, web components allow you to define reusable and encapsulated HTML tags.
FAST gives you a collection of packages that include web components to define a set of reusable, stylable, and flexible HTML components. These components can encapsulate an entire user experience design language like Microsoft's Fluent design or Google's Material design. The other packages include an intelligent color system and a design system provider.
This tutorial will introduce you to FAST web components. You'll add the components to an existing website and see the impact of changing the design system's properties. You'll see how to completely alter the design language of a website within seconds, by making a few minor changes.
In this tutorial, you'll be editing an existing HTML static website. If you'd like to follow the step-by-step guide, you'll need some tools. Start with a code editor like Visual Studio Code. You'll also need a local development server. A simple way to set one up is to use the Live Server extension for VS Code.
Imagine you work for a company that has an existing website. Your company's design department has been asked to rebrand the company and needs to apply this new look and feel to the website. The current website has been built with classic HTML and CSS for styling. You'd like to take this opportunity to switch to web components and have recently discovered FAST as an option.
To start this tutorial, you'll clone your company's existing website. Exploring the code, you'll see it's a simple static website with this folder structure:
The web page itself is simple and has menu, hero, gallery, contact, and footer sections.
Using FAST on a website
FAST takes a component-based approach. You're in control and can choose to use only some parts of it, or wholesale as a suite of tools. In this example, you'll be adding FAST as a whole. It will include the web components and a design system that you can use out-of-the-box.
There are only four things you need to do to start using FAST on your website:
- Add the design system provider to the section you'd like to use FAST inside.
- Add the custom FAST web components you'd like to use.
- Adjust the design system's properties to match your company's branding.
Later in this tutorial, we'll discuss some features of the design system provider. We'll then look in more detail at some of the specific web components you can use.
Setting up your development environment
This guide is assuming you are using Visual Studio Code and have already installed the Live Server extension. On your computer open a terminal and navigate to where you'd like to download the tutorial files. Download the zipped source code from here, or view the source in our GitHub repository.
In VS Code, open the CompanyPage folder. Right-click on the index.html file and select
Open with Live Server. You should see a new browser window open on localhost. Have a look at the current webpage.
Add the Web Component and color modules
The first step is to add the Web Component module. You can use the current published pre-bundled script that contains all the APIs you need, by importing it from the unpkg.com.
Before the end
Save your changes, and the browser should automatically reload. You'll see nothing has changed on the website.
Enable FAST web components
The second step is to add the Design System Provider that contains the design properties and web components on the page. At line 13, under the
<body> tag, add this HTML tag:
Then close this tag at line 180, just before the closing
Adding these tags enables you to use the imported design system provider and its web components. You can now start to replace the standard HTML controls or add some new FAST components. For your company's website, you'll be replacing all the buttons, links, and text buttons.
When you saved these changes, you might not have noticed much of an impact on the website. The background went a little darker, and the text brightened slightly. This is because the design system provider you added includes an implementation of the FAST design language. This is a dark theme, with magenta accents.
You can access these colors using CSS variables, for the background
var(--background-color), with the main color of the page being
var(--neutral-foreground-rest). To learn more about how colors palettes are supported, see the documentation.
An advantage of using a FAST design system is that the color pallete is calculated. It has built-in support to create enough contrast between elements based on the WCAG specification.
Add FAST web components
Taking each section of your website in turn, you'll replace the existing HTML controls with FAST web components. In the menu, you'll replace the search controls.
Replace the HTML on line 33 with this code:
Save your changes and you'll instantly see that the controls have been replaced. The
<fast-text-field> uses the accents from the FAST design language. The previous CSS won't apply to the new controls, so you need to add some tweaks to the css\style.css file.
At the bottom of the file, add these lines of code:
Next you'll fix the hero section. Here you're going to replace the call to action link. On line 48, replace the line with this code:
Replace all the buttons in the summary section, lines 64, 75, and 84, with this code:
Save your changes and view the updated webpage. You'll see the two different appearances in the design system. The
"accent" appearance on the Browse gallery button uses a filled magenta color. Compare this to the View details » button that's using the
"outline" appearance. There is also a third appearance included in the design system, the default
"neutral" style. You can see this on the Submit button in the menu.
All of the colors are based around color recipes that inherit from one of FAST's two palettes. These are the
neutralPalette and the
accentPalette. You can see all the available color recipes in the documentation.
If you refresh your browser, you might notice the new web components flash. This is because the browser doesn't know how to display the web components until they have been defined. To stop the flash of unstyled content, add this CSS at line 9 in the header of the page:
Replace all the
<hr class="featurette-divider"> with the
<fast-divider class="featurette-divider" />
The last section that needs changing is the footer. Here you'll replace all the controls with web components. Replace all the HTML that is defined in the
<footer class="container"> tag, starting at line 136. Use this new footer code:
Again, there are some style issues that need to be fixed. Add this CSS at the bottom of css\style.css.
Web components are made up of custom elements, Shadow DOM, and HTML templates. The CSS for the message text-area inside the
<fast-text-area> web components is set using the
::part in the Shadow tree to set the width. You only need to do this for some controls like the
<fast-text-area> because it combines a label and a textarea control. For most of the simpler FAST web components you can target the styles at the control itself.
Change the design system dynamically
Another strength of using FAST alongside the color pallete is the codified design properties. You can access and change a number of properties.
|Defines the background color of the node. This is used by color recipes and should represent the color the UI is rendering on for a given node tree.|
|Defines the base luminance used in layer recipes.|
|A multiplier to control the density of UI elements.|
|The core sizing unit that all sizes are derived from.|
|The number of design units used for component height at the base density.|
|The number of design units used for horizontal spacing at the base density.|
|The corner radius of controls.|
|The width of the outline on controls.|
|Opacity of disabled controls.|
You've been asked to demonstrate how these properties affect the look and feel of the website. You decide to add a new FAST Web Component, the
<fast-card>, to contain a number of components to surface the underlying design system.
At line 52, under the
<a> tag in index.html, add this HTML:
Some additional CSS is needed to make the panel usable. At the bottom of the CSS, add this code:
designSystemProvider properties are being connected to the individual web components. Save your changes and reload the website.
cornerRadius slider and see all the FAST components change. Try the
baseLayerLuminance slider to see the whole page adapting to a lighter or darker theme. You might notice that this breaks the call to action in the header. This is because the hero text is statically defined in the CSS. You need to use the design system's CSS variables.
In the CSS file, at line 38, change the declaration for
.hero-text to this:
The hero text panel will now reflect the changes to the corner radius, background, and foreground colors. There is another CSS problem on the page. In the gallery section, there are subtitles defined with a
.text-muted class. This class also needs to change, depending on the background color. Change the class at line 466 to:
The next fix is around how the call to action and contact buttons are no longer larger than other buttons on the site. FAST has defined a typography ramp system that allows you to scale text relatively. You're going to increase the font size and line-height by adding this CSS declaration:
To allow the other text to also use the type ramp, change the CSS declarations for
Save your changes and alter the
baseLayerLuminance slider again. See how the hero and muted text adjust to the different values. Also, note the updated sizes of the calls to action.
The FAST adaptive color system
Earlier in this tutorial you saw how adding an accented appearance to a FAST button filled it with the loaded design system's chosen highlight color. In the design properties panel you can choose to change the accent color. The code that supports this is:
FAST allows you to change the palette. The change will then be propagated to all the controls that are using that color palette. Try changing the color and see how all the controls that use the
accentPalette are updated. For more information see the Algorithmic Colors (Recipes) section in the documentation.
FAST and the flexibility of the design system
So far in this tutorial, you've updated a statically designed website to use FAST's modern responsive design system. FAST separates the base web components from their flexible design system. Through this example, you've been using the default FAST web components. The out-of-the-box design system provided is based on a dark user experience.
To demonstrate how the separation of this design system from its components works, you're going to switch to the FAST implementation of Microsoft's Fluent design system.
Change line 247 to:
And the import statement at line 253 to:
Finally, using search and replace within the HTML and CSS files, replace all instances of "fast-" with "fluent-".
Fluent is based around a lighter user experience, using blue accents. There's also a different corner radius to controls and a smaller height multiplier.
As you can see, it's possible to encapsulate your company's entire design philosophy as a FAST design system provider, and deploy it across all your websites and apps. However, the flexibility is still there. You can still change the base luminance to a darker or black theme. You could adjust all the design properties to make the design system provider match the appearance of the default FAST design system.
There's a completed sample webpage located in FastPage\index.html if you'd like to view all of the above changes already made to the example.