Web
Version: 5.0.1Enable Unifi Styled Themes
Documentation for setting up a project with Unifi Web can be found on the Get Started page.
Web Theming
All variables within Unifi Web components are set with the !default flag, meaning they are able to be overridden in your custom build. The Sass variables are separated into two categories, tokens and variables.
Tokens
Tokens can be described as the smallest repeatable pattern in a design system. Within Unifi that will cover theme colors, font weights, and a font family. Overriding tokens is as simple as configuring a module. For example, changing the primary and secondary theme colors can be done by updating your _theme-tokens.scss to the following:
Intelligent contrast functions will automatically select black or white for text colors on applicable components, and also set appropriately contrasted state colors, such as a button background on hover. If you need to customize the contrast color, you can update $u-theme-on-primary and $u-theme-on-secondary.
There are also tokens for background ($u-theme-background) that applies to html, body, and surface ($u-theme-surface) that applies as background-color for Paper and Paper-based components.
A full list of color tokens can be found within your project by looking in your node_modules folder at @nelnet/unifi-components-web/src/sass/tokens.scss. Typography tokens are documented on the typography demo page.
Variables
The rest of your Sass variables can be configured in your _theme-variables.scss file. Refer to Web Component demo pages to view variables available for each component type. Typography variables are one type you may find yourself wanting to customize. All Typography variants can be updated via the following format. Because typography variables are defined as maps, additional styles can be added. Note that any CSS rules are valid, but must be provided as a comma-separated list v. semicolon line-endings.
Web Styling
Refer to Web Component demo pages to view available classes to compose components.
Theme Classes
Use the following classes to theme areas of your application without the need to write additional custom style rules.
| CSS Class | Description |
|---|---|
u-theme--primary | Sets the text color to the theme primary color |
u-theme--secondary | Sets the text color to the theme secondary color |
u-theme--background | Sets the background color to the theme background color |
u-theme--surface | Sets the surface color to the theme surface color |
u-theme--on-primary | Sets the text color to the theme on-primary color |
u-theme--on-secondary | Sets the text color to the theme on-secondary color |
u-theme--on-surface | Sets the text color to the theme on-surface color |
u-theme--primary-background | Sets the background color to the theme primary color |
u-theme--secondary-background | Sets the background color to the theme secondary color |
u-theme--text-<TEXT_STYLE>-on-light | Sets text to a suitable color for TEXT_STYLE on top of light background. Please see Text styles section. |
u-theme--text-<TEXT_STYLE>-on-dark | Sets text to a suitable color for TEXT_STYLE on top of dark background. Please see Text styles section. |
Text Styles
The text styles used in the color system:
| Text style | Description |
|---|---|
primary | Used for most text (e.g., text-primary-on-light) |
secondary | Used for text which is lower in the visual hierarchy (e.g., text-secondary-on-light) |
hint | Used for text hints, such as those in text fields and labels (e.g., text-hint-on-light) |
disabled | Used for text in disabled components and content (e.g., text-disabled-on-light) |
icon | Used for icons (e.g., text-icon-on-light) |
Sass Utility Functions
The following utilities can be used as helpers within your own stylesheets.
u-theme-prop($property, $style, $important, $edgeOptOut)
Applies a theme color or a custom color to a CSS property, optionally with !important. This mixin will output the entire CSS style rule. To access just the computed value of a theme variable, use the u-theme-prop-value function.
u-theme-prop Properties
The properties below can be used as the $style argument for the u-theme-prop mixin. Literal color values (e.g., rgba(0, 0, 0, .75)) may also be used instead.
| Property Name | Description |
|---|---|
primary | The theme primary color |
secondary | The theme secondary color |
background | The theme background color |
surface | The theme surface color |
text-<TEXT_STYLE>-on-light | TEXT_STYLE on top of a light background. Please see Text styles section. |
text-<TEXT_STYLE>-on-dark | TEXT_STYLE on top of a dark background. Please see Text styles section. |
on-primary | A text/iconography color that is usable on top of primary color |
on-secondary | A text/iconography color that is usable on top of secondary color |
on-surface | A text/iconography color that is usable on top of surface color |
u-theme-prop-value($style)
If $style is a color (a literal color value, currentColor, or a CSS custom property), it is returned verbatim. Otherwise, $style is treated as a theme property name, and the corresponding value from $u-theme-property-values is returned. If this also fails, an error is thrown.
This is mainly useful in situations where u-theme-prop cannot be used directly (e.g., box-shadow).
Unlike the u-theme-prop mixin, this function only returns the raw color value of the specified theme property.
u-theme-accessible-ink-color($fill-color, $text-style: primary)
Returns an accessible ink (text) color that has sufficient contrast against the given fill color.
Params:
$fill-color: Supports the same values asu-theme-prop-value$text-style: Value must be one of primary, secondary, hint, disabled, icon (see$u-theme-text-colors)
u-theme-luminance($color)
Calculates the luminance value (0 - 1) of a given color.
u-theme-contrast($back, $front)
Calculates the contrast ratio between two colors.
u-theme-text-emphasis($emphasis)
Returns opacity value for given emphasis.
Params:
$emphasis: Type of emphasis such as high, medium & disabled.