New API for Design Tokens and CSS variables

A dedicated API has been added to allow modules and themes to define design tokens as Drupal plugins.

Design tokens are small, reusable design decisions that make up a design system's visual style. A token can be a color, font style, unit of white space, or even a motion animation designed for a specific need. This definition follows the DTCG standard format.

A token needs to be translated to CSS variables (aka “custom properties”) to be usable on the Web. CSS variables are scoped and can be overridden. This API introduces a config entity type to achieve that.

Examples

Add design tokens plugins

In the *.tokens.yml file in a theme or module:

corner-radius-small:
  "$type": dimension
  "$value":
    value: 4
    unit: px
corner-radius-big:
  "$type": dimension
  "$value":
    value: 16
    unit: px

Override a design tokens plugin with a design token entity

You can convert to CSS variables with values overridden by scope (using CSS selector):

\Drupal::service('entity_type.manager')->getStorage('design_token')->create([
  'id' => 'my_id',
  'path' => 'corner-radius-small',
  'type' => 'dimension',
  'scopes' => [
    ':root' => [
      'value' => 6,
      'unit' => 'px',
    ],
    '.card' => [
      'value' => 8,
      'unit' => 'px',
    ],
  ],
])->toCss();

Producing:

:root { --corner-radius-small: 6px; }
.card { --corner-radius-small: 8px; }

This API doesn’t do much more for now and covers 5 token types (Dimension, FontFamily, FontWeight, Number and Typography) upon the 15 available in DTCG. It will be extended in the next releases and is enough to be used as a foundation for a contrib ecosystem.

Alongside SDC and the Icon API, Design Tokens API is a milestone in the road to make Drupal a Design System first CMS.