Problem/Motivation

Once #3531854: Add a Design Tokens & CSS variables API is shipped, we can extend it with missing features. One of those is the ability for a token value to reference an other token.

There are lots of different words the community uses to describe this kind of Token Value:

  • Reference Tokens
  • Alias Tokens
  • Semantic Tokens
  • Decision Tokens

An Alias Token is how the DTCG W3C specification defines a Design Token with a Value which references another Token.

It's called an "Alias" Token because it provides a new name, or alias, for an existing design decision in our system.

Ideally, the new name/alias provides meaningful context about how, where, or when we intend to implement our design decisions.

Source: https://docs.tokens.studio/manage-tokens/token-values/references

A token value that is a reference to another token.
Example: The value of color.text.primary is #000000, because it references color.palette.black:

color:
  palette:
    black:
      "$type": color
      "$value": "#000000"
  text:
    primary:
      "$type": color
      "$value": "{color.palette.black}"

Source: https://www.designtokens.org/glossary/#alias

Proposed resolution

Let's discuss. It may happen in both the plugin manager level and the config entity level.

User interface changes

There will be some UI Stuff to decide and implement. For example, do we provide the resolved value as a hint when an user fill a token value with an aliases in the config entity form? But the initial Core commit (#3531854: Add a Design Tokens & CSS variables API) doesn't provide any UI, so it may be to early to discuss this and such decision may happen in contrib space.

Introduced terminology

"alias token" or "reference token": A design token's value can be a reference to another token. The same value can have multiple names or aliases.

API changes

We extend but we don't break anything.

Data model changes

No. The aliases use the existing token ID system and live in the existing token values.

Comments

pdureau created an issue.

grimreaper’s picture

grimreaper
Primary language French
Location France 🇫🇷
commented

Raw note:

https://git.drupalcode.org/project/drupal/-/merge_requests/13470#note_82...

In Typography plugin, handle references.

pdureau’s picture

pdureau commented

According to upstream specs:

When a tool needs the actual value of a token it MUST resolve the reference - i.e. lookup the token being referenced and fetch its value. Tools SHOULD preserve references and therefore only resolve them whenever the actual value needs to be retrieved..

That means we will not resolved aliases at the plugin manager level but at the config entity level, after the entity is loaded and before the CSS variablew are generated (to avoid pushing the burden of the task to the browser).

Aliases MAY reference other aliases. In this case, tools MUST follow each reference until they find a token with an explicit value.

Do we do like the path alias (and or redirect) system, flattening the aliases? a -> b; b -> c becoming a -> b; a -> c...

grimreaper’s picture

grimreaper
Primary language French
Location France 🇫🇷
commented

Tools SHOULD preserve references and therefore only resolve them whenever the actual value needs to be retrieved..

Indeed, but we must retrieve the actual value earlier, during the plugin discovery because our value plugins are strongly typed and we can't afford the uncertainty of keeping the reference system until the config entity.