The FAST Frame Design System

The FAST Frame Design System is the Design System that comes with the @microsoft/fast-components package.

What's in the FAST Frame Design System?

Every piece of Design System data in the FAST Frame Design System exists in the FASTDesignSystem interface. The FASTDesignSystemProvider implements the FASTDesignSystem. These two resources are the best place to look for a catalog of what Design System data exists in FAST Frame, as well as which CSS custom properties exist and which HTML attributes / JavaScript properties are used to configure the Design System.

Each Design System property in the FASTDesignSystemProvider will list the HTML attribute on the <fast-design-system-provider> that controls the property, and also whether it creates a corresponding CSS custom property. For more information on how to set each Design System property see Setting Design System Properties, and for information on how to use Design System CSS custom properties see Using Design System CSS Custom Properties.

Using the FAST Frame Design System

To use the FAST Frame Design System, simply ensure the FASTDesignSystemProvider is defined and use the element in your view:

Example: Using the FASTDesignSystemProvider

import { FASTDesignSystemProvider } from "@microsoft/fast-components";
FASTDesignSystemProvider; // Prevent tree shaking
<fast-design-system-provider use-defaults>
Hello world
</fast-design-system-provider>
note

We recommend to add the <fast-design-system-provider> at the root of your view with the use-defaults attribute. This ensures that all Design System properties are initialized. For more info see the use-defaults

Type-ramp

The FAST type ramp is exposed by the FASTDesignSystemProvider as CSS Custom Properties. It organizes the ramp around a base font size and line-height, ascending and descending from the base. The CSS Custom Properties that can be used are:

LevelFont SizeLine Height
Minus 2 (smallest)--type-ramp-minus-2-font-size--type-ramp-minus-2-line-height
Minus 1--type-ramp-minus-1-font-size--type-ramp-minus-1-line-height
Base (body)--type-ramp-base-font-size--type-ramp-base-line-height
Plus 1--type-ramp-plus-1-font-size--type-ramp-plus-1-line-height
Plus 2--type-ramp-plus-2-font-size--type-ramp-plus-2-line-height
Plus 3--type-ramp-plus-3-font-size--type-ramp-plus-3-line-height
Plus 4--type-ramp-plus-4-font-size--type-ramp-plus-4-line-height
Plus 5--type-ramp-plus-5-font-size--type-ramp-plus-5-line-height
Plus 6 (largest)--type-ramp-plus-6-font-size--type-ramp-plus-6-line-height

Adaptive Color

FAST Frame implements an adaptive color system that provides some unique advantages:

  • Ensure text meets WCAG contrast requirements.
  • Easily swap from light mode to dark, or anywhere in-between.
  • Color theming through palette tinting.
  • Perceptually uniform UI across background colors.

To accomplish these goals, FAST Frame makes heavy use of algorithmic colors; named colors that are a product of the Design System in which they are calculated. In the documentation below, these algorithmic colors will be referred to as Recipes. Recipes operate on three primary inputs: Palettes, the background color, and offsets / deltas.

Palettes

Each color recipe operates on a palette. A palette is an array of hexadecimal colors ordered from light to dark by relative luminance. By default, FAST components leverage the neutralPalette and the accentPalette.

See accentPalette and neutralPalette for more details.

Generating and Replacing Palettes

@microsoft/fast-components exposes a convenient function to generate a color palette from an arbitrary source color, and this function is how the default neutralPalette and accentPalette are generated. You can generate a new palette by choosing a palette source color and invoking the palette generation function:

Replacing the neutral palette
import { parseColorHexRGB } from "@microsoft/fast-colors";
import { createColorPalette } from "@microsoft/fast-components";
const palette = createColorPalette(parseColorHexRGB("#28EBD7"));

The palette can then be applied to the FASTDesignSystemProvider to communicate to components the palette change:

// ...
const provider = document.querySelector("fast-design-system-provider");
provider.neutralPalette = palette;
Replacing the accent palette

The same approach can be taken for the accentPalette, but when doing so the accentPaletteBaseColor should also be replaced:

import { parseColorHexRGB } from "@microsoft/fast-colors";
import { createColorPalette } from "@microsoft/fast-components";
const accent = "#F27D07";
const palette = createColorPalette(parseColorHexRGB(accent));
const provider = document.querySelector("fast-design-system-provider");
provider.accentBaseColor = accent;
provider.accentPalette = palette;

Background color

This is the contextual color that the recipe uses to determine what color it is rendering on. The foreground, outline, and divider recipes will use this color to ensure that the color created is accessible and meets contrast requirements. In fill recipes, it is sometimes used as the starting location in the appropriate palette to begin resolution.

See backgroundColor for more details.

Offsets / Deltas

If you look at the properties of the FASTDesignSystem, you'll notice a number of "Delta" properties. These are used by color recipes to shift the colors derived from recipes by index of the palette. You can adjust these values to fine-tune each individual color recipe.

Color recipes

Color recipes are algorithmic colors generated relative to a context. Recipes can be thought of and used as named colors, however they are more than simple variables; they are generated values where the value of the Recipe will change depending on the context in which it is generated. The primary inputs to any color recipe are Palettes, the background color, and offsets / deltas, which come from the nearest ancestor <fast-design-system-provider>.

We created the Color Explorer as a visualization tool to help see what each of the following color recipes does.

Using Color Recipes

First, ensure the UI element has a FASTDesignSystemProvider ancestor element - this element will resolve the recipe for a component within it that declares a dependency on the recipe.

<fast-design-system-provider use-defaults>
<my-element>I use a color recipe!</my-element>
</fast-design-system-provider>

Next - declare the recipe as a dependent behavior of a FAST Component's stylesheet. Then use the recipe as a CSS Custom Property in the stylesheet:

import { css } from "@microsoft/fast-element";
import { neutralFillRestBehavior } from "@microsoft/fast-components";
const styles = css`
:host {
background: ${neutralFillRestBehavior.var};
}
`.withBehaviors(
neutralFillRestBehavior
);

Then, define a FAST element and use the element in your page!

note

For more information on what this is doing, see CSS Custom Property Behaviors

Neutral recipes
Layer recipes

Layer recipes represent the UI layers and surfaces that individual UI elements are contained within. They are applied to primary regions such as toolbars, sidebars, canvas regions, fly-outs, dialogs, and cards.

Behavior NameCSS Custom PropertyDescription
neutralLayerFloatingBehavior--neutral-layer-floatingUsed as the background for floating layers, including context menus and fly-outs.
neutralLayerCardBehavior--neutral-layer-cardUsed as the background color for cards. Pair with neutralLayerCardContainer for the container background.
neutralLayerCardContainerBehavior--neutral-layer-card-containerUsed as the background color for card containers. Pair with neutralLayerCard for the card backgrounds.
neutralLayerL1Behavior--neutral-layer-l1Used as the background color for the primary content layer (L1).
neutralLayerL1AltBehavior--neutral-layer-l1-altAlternate color for L1 surfaces.
neutralLayerL2Behavior--neutral-layer-l2Used as the background for the top command surface, logically below L1.
neutralLayerL3Behavior--neutral-layer-l3Used as the background for secondary command surfaces, logically below L2.
neutralLayerL4Behavior--neutral-layer-l4Used as the background for the lowest command surface or title bar, logically below L3.
Text

Neutral text recipes address most cases of text used in a UI, from interactive element text, headings, and body text.

Behavior NameCSS Custom PropertyDescription
neutralForegroundRestBehavior--neutral-foreground-restPrimary page text color when the text is in a rest state.
neutralForegroundHoverBehavior--neutral-foreground-hoverPrimary page text color when the text is in a hover state.
neutralForegroundActiveBehavior--neutral-foreground-activePrimary page text color when the text is in a active (pressed) state.
neutralForegroundHintBehavior--neutral-foreground-hintSecondary hinting text to be used with non-large text to meet a 4.5:1 contrast ratioBehavior to the background.
neutralForegroundHintLargeBehavior--neutral-foreground-hint-largeSecondary hinting text to be used with large text to meet a 3:1 contrast ratio to the background.
Fills (backgrounds)

Neutral fills are indented to be used as fill colors (background) to UI elements to distinguish them from the background.

Behavior NameCSS Custom PropertyDescription
neutralFillRestBehavior--neutral-fill-restUsed to visually differentiate the UI element from it's background context at rest.
neutralFillHoverBehavior--neutral-fill-hoverUsed as the fill of a neutralFill element when hovered.
neutralFillActiveBehavior--neutral-fill-activeUsed as the fill of a neutralFill element when active.
neutralFillSelectedBehavior--neutral-fill-selectedUsed as the fill of a neutralFill element when selected.
neutralFillStealthRestBehavior--neutral-fill-stealth-restUsed when a UI element's fill is visually differentiated when being interacted with by the user.
neutralFillStealthHoverBehavior--neutral-fill-stealth-hoverUsed as the fill of a neutralFillStealth element when hovered.
neutralFillStealthActiveBehavior--neutral-fill-stealth-activeUsed as the fill of a neutralFillStealth element when active.
neutralFillStealthSelectedBehavior--neutral-fill-stealth-selectedUsed as the fill of a neutralFillStealth element when selected.
Outlines and dividers

Neutral outlines are used to construct outline controls and dividers.

Behavior NameCSS Custom PropertyDescription
neutralOutlineRestBehavior--neutral-outline-restUsed as a rest outline color for outline controls.
neutralOutlineHoverBehavior--neutral-outline-hoverUsed as the outline of a neutralOutline control when hovered.
neutralOutlineActiveBehavior--neutral-outline-activeUsed as the outline of a neutralOutline control when active.
neutralDividerRestBehavior--neutral-divider-restUsed as the color for divider elements.
Toggles

Toggle elements such as checkboxes and switches use a specific set of recipes.

Behavior NameCSS Custom PropertyDescription
neutralForegroundToggleBehavior--neutral-foreground-toggleUsed as the foreground of toggle elements with non-large text to meet a 4.5:1 contrast ratio to the background.
neutralForegroundToggleLargeBehavior--neutral-foreground-toggle-largeUsed as the foreground of toggle elements with large text to meet a 3:1 contrast ratio to the background.
neutralFillToggleRestBehavior--neutral-foreground-restUsed as fill of a toggle element like checkbox.
neutralFillToggleHoverBehavior--neutral-foreground-hoverUsed as the fill of a neutralFillToggle element when hovered.
neutralFillToggleActiveBehavior--neutral-foreground-activeUsed as the fill of a neutralFillToggle element when active.
Inputs

Text input elements also have a set of recipes specifically tailored.

Behavior NameCSS Custom PropertyDescription
neutralFillInputRestBehavior--neutral-fill-input-restUsed as the fill of the text input at rest.
neutralFillInputHoverBehavior--neutral-fill-input-hoverUsed as the fill of the text input when hovered.
neutralFillInputActiveBehavior--neutral-fill-input-activeUsed as the fill of the text input when active.
neutralFillInputSelectedBehavior--neutral-fill-input-selectedUsed as the fill of the text input when selected.
Document focus
Behavior NameCSS Custom PropertyDescription
neutralFocusBehavior--neutral-focusThe color of the focus indicator when the element has document focus.
neutralFocusInnerAccentBehavior--neutral-focus-inner-accentThe color of the inner focus-indicator when an accent fill element has document focus.
Accent recipes

Accent recipes use the accent palette and are intended to bring attention or otherwise distinguish the element on the page.

Behavior NameCSS Custom PropertyDescription
accentFillRestBehavior--accent-fill-restUsed as the fill of an accent element at rest.
accentFillHoverBehavior--accent-fill-hoverUsed as the fill of an accent fill element when hovered.
accentFillActiveBehavior--accent-fill-activeUsed as the fill of an accent fill element when active.
accentFillSelectedBehavior--accent-fill-selectedUsed as the fill of an accent fill element when selected.
accentFillLargeRestBehavior--accent-fill-large-restUsed as the fill of an accent element at rest that uses large text.
accentFillLargeHoverBehavior--accent-fill-large-hoverUsed as the fill of an accent fill large element when hovered.
accentFillLargeActiveBehavior--accent-fill-large-activeUsed as the fill of an accent fill large element when active.
accentFillLargeSelectedBehavior--accent-fill-large-selectedUsed as the fill of an accent fill large element when selected.
accentForegroundCutBehavior--accent-foreground-cutUsed as foreground color of text used over accent fill fill.
accentForegroundCutLargeBehavior--accent-foreground-cut-largeUsed as foreground color of text used over accent fill large fill.