Design System Tokens

Unofficial Content
This documentation is valid for:

This article explains design tokens, the concepts, and their use in GeneXus.

What is a Design Token?

A token is the most basic element of a Design System that allows you to capture an option for visual or interaction design.
A token allows you to model a – platform-agnostic– choice of color, typography, spacing, time, media, zindex, border, opacity, size.

With tokens, you can give options for low-level values of your product.

Having a Token set for your Design System will allow your product to be more maintainable and consistent in terms of design.

How to define tokens in GeneXus?

GeneXus incorporates the possibility of defining token sets for a Design System, in a Design System object

The language is declarative and allows to define tokens in different categories.

GeneXus provides a textual and a visual representation for the tokens.

The textual representation provides an easy way to edit/share/compare and on the other side, the visual representation allows to understand visually the details of the options given by the tokens.

Textual Representation

Design_Tokens_TextualEditor

Visual Representation

Design_Tokens_VisualEditor

Textual editor specification

GeneXus provides a side by side editor for textual & visual design.

Token Set

A Token Set allows you to group a set of options of various types. These sets have a name and can have one or more types of tokens

tokens MyDesignTokens
{
  // Here define tokens
}

Token Types

A specific Token Set includes several tokens defined by Types.

There is a set of predefined token types. Having Token Types allows giving a clear meaning of the kind of token we are creating.

Readers can have a clear understanding of what context this token can be used in, and tools can give different ways of editing or showing these tokens.

Predefined token types are:

#colors
#spacing
#borders
#opacity
#radius
#shadows
#times  (Use timing tokens for animation durations.)
#fonts
#fontsizes
#mediaqueries
#zindex

A type of token could appear more than once. If a token appears more than once with the same type, the last value in the file is the one considered.

Sample

tokens MyDesignTokens
{
  #colors
  {
    active: red;
    text: #FFFFF;
  }
}

Token

For each Token Type inside a Token Set we can define Tokens.

Each Token has at least a token name and a token value

Depending on the Token Type is the kind of Token Value allowed.

The syntax for the two required elements is equal to a CSS property, the only difference is that validators should take into account that the domain for values has constraints depending on the Token Type group.

Setting Tokens to specific values is the core function of the Design System Tokens language

A Token is defined by two required properties (Name and Value).

Both properties and values are case insensitive. The pair is separated by a colon ':'.

The syntax for the Token Name follows the same rules as CSS properties names. There are different values allowed and each Token Type defines which are the valid values.

<TokenName> : <TokenValue>

The most compact way of defining a token is by just given a value to a name.

activeColor: red;

But sometimes optionally we would like to give more semantic to our token. This additional information is expressed by supporting the value of a token to have much more information than simply the value.

TokenValue : Value | ValueAndData

ValueAndData has the format of a JSON Object that only supports at the first level the keys: value, description, and info.

The info is a JSON Object that supports any kind of structure inside.

Sample

tokens MyDesignSystemTokens
{
   #spacing
   {
     small: 12px;
     big: 45px;
   }
    #colors
   {
     active: { 
         value: red; 
         description: "This token represent the active color to be used for control activation"; 
         info : { 
             version: 1.0 
         }
     };
     text: #FFFFFF;
   }
}

Token value resolution

The same token name and type can appear in a token set more than once. In these cases when more than one value can be valid, the latest definition is taken.

Sample

tokens MyTokens
{
   #colors
   {
     back: red;
     back: white;
   }
}

In this case, the value for the Token 'back' will be white.

Token Set Parameters: Setting or switching token sets at runtime

Token Sets allow receiving parameters that can be used in conditions.

tokens Unanimo(option:dark|light,platform:android|ios)
{
   @option = dark
   {
     #colors
     {
        text = white;
        back = black;
     }
   }
   @option = light
   {
     #colors
     {
        text = black;
        back = white;
     }
   }
}

Token Set Conditions

Conditions allow assigning tokens depending on some condition.

You specify a condition using the prefix @.

Conditions are boolean expressions where you can use and operators. These conditions could be nested, which means the same as an and operator.

Parameters from the token should be used in conditions.

Samples

Check some parameters.

 @option = dark

Check for a Platform

 @platform = Android

Which token sets are used in a specific moment, can also be defined in runtime as explained here.

Where are Tokens used?

As we said before Tokens are the options to be used in Design System Styles

What does Tokens mean for Web Development?

When the generation target is Web, GeneXus generates CSS Custom Properties for each of the defined tokens.
When performing this conversion, the tokens lose the semantics of their category, so a conversion from CSS Custom Properties to Tokens is not possible.
However, the CSS Custom Properties generated by GeneXus can be imported without problems to a Token Set because GeneXus gives consistency to the way to generate the tokens.

Export Tokens for Designers

Tokens can be exported to the following formats for a DesignOps loop:

  • scss
  • css
  • sketch
  • brand.ai

Which is the relation with Palette Colors?

Actually, a Color Palette object is just a Token Set with only color tokens. A token set is a superset of a Color Palette Color.