Creating a design system involves two steps:
- Determine what information the Design System should hold
- Creating a DesignSystemProvider to communicate the Design System
The Design System holds information dictated by a project's design guidelines, philosophies, and capabilities which may vary widely across projects. Therefore, this documentation will focus on creating and configuring a DesignSystemProvider and not data in the Design System.
Defining a DesignSystemProvider
As discussed in the overview, the DesignSystemProvider is an HTML element designed to communicate the Design System. To create a DesignSystemProvider element, we'll declare a new DesignSystemProvider element using the defineDesignSystemProvider decorator:
Loading the script with the above definition, you can now use the following HTML:
Extending an existing DesignSystemProvider
The same steps can be followed to extend an existing provider. Instead of extending the DesignSystemProvider, instead extend the existing provider.
Example: Extending FAST Frame's FASTDesignSystemProvider
Declaring the Design System
The above HTML at this point doesn't do much. Let's change that by exploring how to creates properties of the design system using
designSystemProperty(). Let's say that we want to add
font-size-large to our Design System:
The above declares the
fontSizeLarge property on the
MyDesignSystemProvider and decorates it as a property of the Design System. Let's take a closer look at the configuration object provided to the decorator.
attribute property is used to set the HTML attribute that should correspond to the decorated property. This property is optional and defaults to the name of the decorated property; it can also be set to
false to omit the HTML attribute association. In this case, the
attribute property is being used to spinal-case the property name for more conventional use in HTML:
Example: Setting the property from the HTML attribute
cssCustomProperty property is used to define the name of the CSS custom property to which the value is mapped. This allows easy use of the Design System value in CSS stylesheets. This property is optional and defaults to the attribute name of the decorated property; it can also be set to
false to omit the CSS custom property association. In this case, the
cssCustomProperty property is being used to spinal-case the property name.
default property naturally defines the default value for the Design System property. This is the value that gets used when an app author applies the
use-defaults attribute (see
Notice the the default value is assigned as a property of the config and not directly to the property itself; the property is declared but never assigned a value. This is important because each instance of a provider inherits unset properties from a parent provider (if it exists); if each provider set each property explicitly to the default then there would be no inheritance.
designSystemProperty() also supports a
Example: Using a nullableNumberConverter
use-defaults boolean attribute exists for all DesignSystemProviders and exposes a mechanism to apply the default values to an element while still allowing nested design system elements to intentionally override specific values. For details on how to set default values, see Declaring Design System Properties.
In general, a DesignSystemProvider element with the
use-defaults attribute should exist as an ancestor to all rendered UI; this will ensure that all the values enumerated in the Design System are defined.
Thats it! Once you've configured all the Design System properties you can use your Design System Provider in your page. See Using the Design System for more information on how to use the Design System values provided by your DesignSystemProvider.