Custom properties

Extend the definition of tokens in your design system, allowing more possibilities
for working with tokens in code

Usage

Custom properties are the most useful for storing additional metadata next to design tokens.

Defined custom properties will be:

  1. displayed in documentation,
  2. sent as additional parameters to code exporters. (e.g. to be used for conditional rendering).

Examples of custom properties

There are many ways how to use custom properties. Here is a list of a few examples of how others use custom properties for design tokens.

Name

Type

Description

Internal token

Boolean

For tokens that are not supposed to be exported as variables to code. These tokens are created only for easier management of our token set.
For example, for having tokens in Measures for referencing purposes, but not meant to be used in final code components.

CTI structure

Text

For generating variable names based on CTI structure (Category / Type / Item) as defined in Style Dictionary or any other token naming schema (like in Mineral UI).

Deprecated

Boolean

If the token is not supposed to be used anymore in new components, but still needs to exist in the codebase before removed completely.

Themeable

Boolean

If the token is themeable or not (as seen e.g. Salesforce Lightning).

Group

Text

For structuring design tokens into groups, so it can be used by exporters for generating Sass maps (like in this article by Cristiano Rastelli).

iOS/Android/Web Platform

Boolean(s)

To define which tokens are supposed to be generated for a specific platform and which to ignore (e.g. tokens for responsive breakpoints only for web, nothing else).

Structure of a property

A custom property consists of the following structure:

  • Name -> Name of the property
  • Code name -> The code friendly name that will be used in code generation
  • Type -> The type of value. We support 4 types of custom properties (Text, Number, Boolean, Generic)
  • Default value -> The default value of the property

Once a property is defined, everything but the type can be edited.

Available types

Custom property type

Description

In exporters

Text

A common text value; sent to an exporter wrapped in quotes

"key": "text value"

Number

A numeric value; sent to an exporter as a number

"key": 123

Boolean

A true or false value, sent to an exporter as a boolean

"key": true

Generic

Similar to text, but sent to an exporter like a constant

"key": constant


Define custom properties

Custom properties for tokens are applied at the design system level, to all tokens, and can be overridden for each token. You can create, edit and remove custom properties of a design system.

Design system → Settings → Custom properties

 

Only owners and admins can define custom properties.

Create a custom property

  1. In your design system, navigate to Design System Settings > Properties
  2. Click + New to create a new property
  3. Enter the details of the property: name, code name, type, and default value
  4. Click ✓ to save (or x to cancel)

Edit a custom property

  1. In your design system, navigate to Design System Settings > Properties
  2. Edit the name, code name or default value of the property
  3. Click to save
Note → Once the type has been defined and the property saved, it cannot be changed

Remove a custom property

  1. To remove a property, hover and click Remove
  2. In the dialog, type DELETE to confirm
Removing a custom property will also remove all token overrides

Override token properties

Custom properties defined at the design system level can be overridden on any token.

  1. In your design system, select a token and click to open the edit dialog
  2. Under Custom properties you will find a list of the properties you have defined
  3. Change the value of the property you wish to override
  4. Click Confirm to save

Override custom properties for a token


Remove a token override

  1. To remove a token override, click the reset icon in the input to reset it to default
  2. Click Confirm to save

Reset override to default


Remove all token overrides

  1. To remove all overrides for a token, click the ••• icon to open the menu
  2. Click Reset all overrides to reset all to default
  3. Click Confirm to save