Design Tokens

Disclaimer

This is not by any means an attempt to create a definitive guide to Design Tokens, but to frame them in the context of Torquens.

There are a wealth of resources covering scope and naming (the two major headaches generally associated with Design Tokens), and much nuance and personal preference in designing them.

Design Tokens are a tool to record the key values used in the construction of a Design System.

They ensure consistency within and across implementations—whether that's design to design, or design to development, regardless of target platform.

Scope

Design Tokens are used to capture most visual aspects of a Design System.

Probably the most common areas, which benefit the most from tokenisation, are colour, typography, shape and size. However, many more aspects of a Design System can be encoded within tokens such as animation (durations or timing functions) or layouts (content distribution and direction).

Representation

There thankfully now exists a W3C standard for serialising Design Tokens. The DTCG 2025.10 specification comprehensively describes both a JSON structure for tokens, along with a resolution module for more sophisticated reuse and context switching.

Source of Truth vs Record of Truth

Who owns (and where is) the source of truth in a design system can be a sensitive question.

It used to be the case that designers (and your design tool, respectively) were held as the source of truth.

Whilst designers remain the source of truth, the advent of DTCG allows it to become the authoritative record of truth.

Here is a highly truncated example of a DTCG compliant token file:

{
  "$type": "color",
  "sentiment": {
    "positive": {
      "default": {
        "$value": {
          "colorSpace": "srgb",
          "components": [0.109375, 0.76171875, 0.48046875],
          "alpha": 1,
          "hex": "#1bc27a"
        }
      },
      "hover": {
        "$value": {
          "colorSpace": "srgb",
          "components": [0.0078125, 0.68359375, 0.41796875],
          "alpha": 1,
          "hex": "#01ae6a"
        }
      }
    }
  }
}

The significant aspect of this is that while the JSON representation is highly structured allowing for granular reuse via the $extends directive, only the leaf $valuenodes actually become tokens in most outputs, even where structured output is possible.

CSS

:root {
  --sentiment-positive-default: #1bc27a;
  --sentiment-positive-hover: #01ae6a;
}

In CSS, there is no way to refer to the parent group --sentiment-positive; as yet CSS has no variable name interpolation, which is probably for the best.

SCSS

$tokens: (
  "sentiment.positive.default": var(--sentiment-positive-default),
  "sentiment.positive.hover": var(--sentiment-positive-hover),
);

Whilst Sass would support deeply nested structures, this comes at the expense of

1. compatibility with other token outputs
2. difficulty of consumption

If the original structure were fully preserved—and only fully preserved would be possible; how would the tooling otherwise know at which point to switch from structured to flattened—then accessing leaf values would become incredibly verbose:

@use "sass:map";

$color: map.get(map.get(map.get($tokens, "sentiment"), "positive"), "default");

Figma

Tokens

Name

Value

Sentiment

Positive

Default

#1bc27a

Hover

#01ae6a

As with the underlying JSON, Figma will present the tokens as structured for readability, but in reality only the terminal values may be referenced in a design file.

Thus, while Design Tokens are defined using a structured format, their output is generally a flattened and namespaced representation.

Composite Tokens

Whilst the most basic design token is a single value (in extremis, for example, an integer), a design token may be composed of multiple sub-values.

As shown above, the DTCG colour token includes a colour space field and individual colour space components, along with an opacity value. Other composite tokens include typography, border, shadow, and stroke styles.

Primitive Tokens

Primitive Tokens, sometimes called foundational tokens, are fundamental to most Design System architectures. These are the simplest forms of Design Tokens, and map a scalar/compound value to a meaningful but semantically void name.

For example, most people can't read colour hex codes, and wouldn't immediately know that #1bc27a is in fact green. Referring to color.green.300, however, gives a much better hint as to its appearance. These are often generated as part of a colour scale, and may result in a great deal of unused colour tokens.

Similarly, it's easier to write typography.font-face than "My Cool Font", especially when it needs updating to "My Even Cooler Font" globally.

Somewhat more controversially, primitive tokens are sometimes used for trivial values like spacing - e.g. spacing.1 is 4px, spacing.2 is 8px and so on. There is some question as to the value of these, as these values are extremely unlikely to change without large changes elsewhere.

Semantic Tokens

Semantic tokens is the standard layer above primitive tokens that applies semantics to the values. For instance, here is where we assign our sentiment colours (positive, negative and so on), brand colours, spacing grids and typography styles.

Theming may also be applied at this stage in various guises; there may be multiple versions of colour semantics for different brands, or light and dark variations.