Design Tokens

in beta

Image of the styled tab with developer provided values. Then there is an icon of a link that touches the styled tab and some code, and the code is where the design tokens are registered. This document goes into detail about example code, and how that affects the style tab.

By providing your own design tokens, you can define a consistent set of design values that are available to your users in the Builder Visual Editor.

In this way you can:

Maintain brand consistency. By providing predefined design tokens, you ensure that your app's design stays consistent and adheres to your brand guidelines.
Streamline content creation. Users can quickly select from a curated set of design options, rather than having to manually input values or make design decisions.
Centralize design updates. When you update your design tokens in code via CSS variables, those changes are reflected across your app, making it easy to manage and evolve your design system.

The image below compares the default Style tab in the Visual Editor (on the left) with a customized Style tab using design tokens (right).

Image of a default style tab as it is in Builder usually and a customized style tab with design tokens showing in the visual editor. One note points out in the default style tab while another points out where the design tokens are showing up. There's also a note that says, customize your style tab with any CSS overrides.

You have flexibility in how you configure and use design tokens:

Customizable values. You can define design tokens for various CSS properties, such as colors, spacing, typography, and other CSS properties. Choose which properties are most important to standardize for your app.
Integration with CSS variables. Use CSS variables to define your token values, allowing for efficient updates and theming across your application.
Granular control. Decide which CSS properties users can edit and whether they can input custom values or only select from your predefined tokens.

This document explores how to register design tokens in your code and the various options available for fine-tuning behavior in the Visual Editor.

Registering design tokens

To register design tokens with Builder, use the register() function from the Builder SDK and provide your designTokens definition in the editor.settings object.

Here's an example of specifying design tokens in code for use in the Builder Visual Editor:

For maintainability, we recommend using CSS variables as token values whenever possible.

The image below shows how the above example code renders in the Visual Editor. Notice that the colors, spacing, and font family specified in the code are now available in the Style tab.

Image of the style tab with the typography, color, and spacing settings from the above example code applied.

The most commonly used properties you can assign tokens to are colors, and spacing but you can also define tokens for any other CSS properties such as backgroundImage, borderRadius, and boxShadow, to name a few.

Design tokens are defined as an array of objects, where each object has two properties:

name: the display name in the Visual Editor
value: the CSS value, such as a CSS variable (recommended)

Changes to design token values are not retroactive unless you use CSS variables

If you update the value property in your code to a new value, existing usages of the token will keep the old value.

To set values that can be updated retroactively, read the CSS variables for dynamic design tokens section later in this document.

Property: `colors`

Affects all color-related properties in the Visual Editor, such as font color, background color, and border color.

Example:

Color properties

name: the display name of the color token in the Visual Editor.
value: the CSS color value, which can be a hex code, RGB, RGBA, or a CSS variable.

This screenshot shows the background and typography sections because they both have a color option. Any color values that are set in code show up here. There's also a note that says color values display for all color settings. Here they are in the background and typography sections.

Property: `spacing`

Affects all spacing-related properties in the Visual Editor, such as margin, padding, and sizing.

Example:

Spacing properties

name: the display name of the spacing token in the Visual Editor.
value: the CSS spacing value, which can be in pixels, ems, rems, or percentages.

Picture of Margin and Padding section with the Spacing settings showing up in the Visual Editor. The note says "Spacing tokens show up anywhere spacing options apply, such as Margin & Padding." Under margin, there is a select with the options of large, small and tiny, as specified in the code.

CSS variables for dynamic design tokens

When defining design tokens, considering how you want to update and maintain those tokens in the future is key. By using CSS variables to define your design tokens, you can update the token values in your code and have those changes automatically reflect across all content using those tokens.

To use CSS variables for your design tokens, you first need to define the variables in your CSS code. For example:

:root {
  --primary-color: rgb(12, 34, 56);
  --spacing-large: 20px;
}

Best practice: always set default values

When using CSS variables, always set a default value as the second argument in (var(--name, default-value)), so Builder's Visual Editor can pick up a value, such as the color preview swatch.

Using CSS variables with `designTokens`

To use CSS variables in the designTokens object, reference the CSS variables using the var() function.

In this example, the Primary color token is defined using the --primary-color CSS variable, and the Large spacing token is defined using the --spacing-large CSS variable.

Updating design tokens with CSS variables

To update the values of your design tokens, that are using CSS variables, update the corresponding CSS variables in your code. For example, if you want to change the primary color from red to pink, update the --primary-color variable in your CSS:

:root {
  --primary-color: pink;
  /* ... */
}

By updating the CSS variable value, all content using the Primary color token automatically update to pink without requiring any manual changes in Builder.

Using CSS variables for your design tokens provides flexibility and maintainability, so you can update and theme your design system across your application.

Hiding CSS properties

To prevent a CSS property from displaying in the Visual Editor, supply false for that CSS property. The code snippet below hides the font family select:

designTokens: {
  fontFamily: false
}

The above setting would cause Builder to hide the font family select. In the left screenshot below, the font family select is hidden because fontFamily is set to false. On the right, fontFamily has properties configured in the designTokens object so they display in the Visual Editor.

Image with a comparison of using font family false which hides the font select under the typography section of the style tab in the Visual Editor. That means that no one can change the font because they can't get to a select for it. This compares to another image on the right, which is the typography section with two options for font selection that are showing. These show because it is specified in the font family property of the design tokens object. When you specify fonts, users can choose the fonts that you have specified.

Overriding CSS properties

You can override any CSS property by specifying that CSS property in camel case. This section covers a number of examples, but this technique is applicable to a wide range of CSS properties.

You can use this same technique with any of the CSS options in the Style tab.

Examples include:

border
boxShadow
fontSize
fontFamily

letterSpacing
maxWidth
fontWeight
textShadow

When configuring any CSS properties, provide a name and value, just as with any design token. Some examples follow.

Example: `border`

Affects the box shadow selection in the Visual Editor's style settings.

Example:

Properties

name: the display name of the border token in the editor.
value: the CSS border value, which can include the border width, style, and color. It can also use CSS variables.

In this example, one border token is defined:

Success with a value of 1px solid var(--green), representing a 1px solid border with a color defined by the CSS variable --green.

Screenshot of the border section in the style tab. In the select there are two options that have been provided as token values in the code. One is success, and the other is needs attention. There is a note that says here, the border settings from the code are available in the border section.

Example: `boxShadow`

Affects the box shadow selection in the Visual Editor's style settings.

Example:

Properties

name: The display name of the box shadow token in the editor.
value: The CSS box shadow value, which can include the horizontal offset, vertical offset, blur radius, spread radius, and color. It can also use CSS variables.

In this example, two box shadow tokens are defined:

Small with a value of 0 0 5px rgba(0, 0, 0, 0.1), representing a small shadow with a 5px blur radius and a semi-transparent black color.

Medium with a value of 0 0 var(--shadow-medium) var(--black-medium), using CSS variables for the blur radius and color.

Image of the shadows and effects section of the style tab in the Visual Editor the select for the box shadow is expanded, and the two options that are coded in the example are available. They are small and medium. There's also a note that says here, box shadow overrides the default box, shadow options.

Example: `fontFamily`

Affects the font family selection in the Visual Editor's text settings.

Example:

Design tokens by space, model, role, or permissions

You can register different design tokens based on a number of different attributes, such as the currently editing model, space, user role name, or permissions.

Allowing custom values with allowOverridingTokens

By default, when you define design tokens for a specific CSS property, the Visual Editor limits users to selecting only from the predefined token values for that property. However, you may want to give users the flexibility to enter custom values in addition to the predefined tokens.

allowOverridingTokens is a boolean that you can use to specify that users can override registered design tokens. This encourages use of the registered values, while still providing the option for users to specify other values.

In the video below, users can add values to a CSS property because allowOverridingTokens is set to true. In this example, the user expands the font select to find only the registered design tokens of a serif font and a sans serif. However, with allowOverridingTokens to true, the user can type in their font.

To enable this behavior, set the allowOverridingTokens option to true when registering design tokens:

When allowOverridingTokens is set to true, users can select from the predefined design tokens or enter custom values for the corresponding CSS properties just as they would when there are no design tokens provided in the codebase. However, in order to override the values, users need to manually enter their desired value.

This provides a balance between maintaining consistency through predefined tokens and providing flexibility for custom values when needed.

Strict mode

When strict mode is off or false, which is the default, and you supply design tokens for a specific CSS property, the Visual Editor only allows selecting from the predefined tokens for that property. Custom values cannot be entered for properties that have design tokens defined.

Strict mode takes this a step further. When strict mode is on, any styles that don't have corresponding design tokens are removed from the Visual Editor and users won't be able to edit those styles at all.

The snippet below shows styleStrictMode set to true in the the register() function:

If strict mode is set to true and no design tokens are supplied, almost all styling options are removed. Users will only be able to adjust basic settings like text alignment and layout alignment.

When strict mode is on, and you have design tokens supplied for specific CSS properties, users can edit those properties but are limited to the predefined token values. All other properties without design tokens are hidden and not editable.

Image comparing strict mode true and strict mode false. There's a screenshot on the left of the Style tab when strict mode is set to false, shows all of the built-in style fields in addition to the developer-provided tokens. In this example, two fonts are supplied and show up in the list as the choices for the font.

In the second screenshot to the right, which is of the Style tab when strict mode is set to true, fields without developer-provided values are hidden.

Making design tokens optional

With designTokensOptional, you can provide your design tokens while keeping the built-in Builder options available to your users.

For example, when registering your editor settings, add designTokensOptional set to true:

As an example, the image below shows brand colors that are specified in the designTokens object. Because designTokensOptional is set to true, they show up in the Builder Visual Editor anywhere there's a color selection available. Here, they display in the list of colors while the color picker remains available: