Design Tokens

A design token is an underlying object that is a base for the following object types:

• Color

• Font

• Gradient

• Shadow

• Border

• Measure

• Typography

• Text

Token Structure

Design tokens carry one piece of atomic information (such as color) either as a raw value or as a reference to other tokens (for example, a token defining primary-cta might be inherited by many color tokens that have a different semantic purpose, such as button-main). This allows you to change one color and propagate the change to all colors that share the reference.

Each token always defines the base information such as name, description, or type. Extra to that, each token also carries its value inside value property:

{
  "id": string
  "name": string
  "description": string
  "tokenType": TokenType
  "origin": {
    "source": "Supernova" | "Figma" | "Sketch",
    "id": string | null,
    "name": string | null,
  } | null
  "value": TokenValue
}

The TokenValue differs based on what type of token it is. For example, the full definition for Color Token will look like this:

{
  "id": "abcd-efgh-ijkl"
  "name": "Base 00"
  "description": "Primary brand black color"
  "tokenType": "Color"
  "origin": {
    "source": "Figma",
    "id": "lkji-hgfe-dcba",
    "name": "Base 00",
  }
  "value": {
    "hex": "000000FF"
    "r": 0,
    "g": 0,
    "b": 0,
    "a": 255
  }
}

Token aliases and referencing

In order to avoid duplication, Supernova introduces the concept of referencing and aliases - shared values that are defined once but then referenced throughout the design system.

If a token reference is used, the token payload will give you that information as well. This is useful if you really want to export the entire chain as it was defined, not just the raw values.

{
  "id": "abcd-efgh-ijkl"
  "name": "Base 00"
  "description": "Primary brand black color"
  "tokenType": "Color"
  "origin": {
    "source": "Figma",
    "id": "lkji-hgfe-dcba",
    "name": "Base 00",
  }
  "value": {
    "hex": "000000FF"
    "r": 0,
    "g": 0,
    "b": 0,
    "a": 255,
    "referencedToken": {
      "id": "xyzw-efgh-caed",
      "name": "Base Referencing 00"
      ...
    }
  }
}

All tokens are automatically resolved for your convenience, but each property always contains referencedToken property so you know when the value comes from a reference. You don't have to worry about circular references, as Supernova prevents the creation of them.

When the token was defined as value without reference, referencedToken will be null.

Token Types

Many functions will ask you for token type. Following is the reference list of all token types available:

• Color - for color tokens

• Font - for font tokens

• Gradient - for shadow tokens

• Shadow - for shadow tokens

• Border - for border tokens

• Radius - for radius tokens

• Measure - for measure tokens

• Typography - for typography tokens

• Text - for text tokens

You can use this type to know what type of token was retrieved or as a filter in certain functions, such as:

{[ const tokens = @ds.tokensByType("Color") /]} 

This will fetch only tokens of type Color, and ignore everything else.