Add a Design Tokens & CSS variables API

Problem/Motivation

After SDC in Drupal 10.1 (July 2023), and the Icon API in Drupal 11.1 (Dec 2025), we are continuing to add design systems API in Core with #3517033: Add a style utility API, in order to be able to build business agnostic, shareable, Drupal themes, providing design implementations which can be leveraged by display building tools.

There is a last design system API to cover the main parts of design systems: CSS variables.

Initially, we were targeting 2026, but an exciting discussion with XB's team in DrupalDevDays 2025 (they wanted a way of altering an utility while applying it) made us realise it will be beneficial to ship it alongside the Style API.

In Web implementations of design systems, CSS variables (sometimes referred as custom properties or cascading variables) are

• typed
• an (often small) subset of the design tokens which are overridable at runtime. So, the new value is applied by the browser and not by rebuilding the CSS.
• defined in the design system implementation (so, in the Drupal theme). Some design system are strongly branded and restrictive with their CSS variables. Other have a liberal approach. We must allow any kind of approach in our API.
• living at the page level, but they can be overridden with a CSS selector as a scope.
• names solely according to authors and users conventions; CSS will never give them a meaning beyond what is presented here.

CSS variables are a commonly found in design systems. Examples:

• Bootstrap 5: https://getbootstrap.com/docs/5.3/customize/css-variables/#root-variables
• DaisyUI 5: https://daisyui.com/docs/utilities/?lang=en#theme-css-variables
• Shoelace: https://shoelace.style/getting-started/customizing

Design Tokens are the smallest unit of design:

• They point to style values like colors, fonts, and measurements
• Components, style utilities, icons, grid systems... are made of tokens
• Each of them is named for how or where it’s used. Even if a token’s end value is changed, its name and use remain the same
• They can be extracted from the designer tool ans shared between many implementations. In a Web implementation, they can be resolved at buildtime (Sass variable, Tailiwind's @apply directive...) or exposed at runtime (CSS variables).

Analysis of the current solutions in the contrib space

Like SDC, the Icon API and the upcoming Style API, we believe it must be front-dev friendly, UI logic focused, YAML plugin declaration available in Drupal theme. So, let's have a look on contrib modules are already covering this scope.

UI Skins (usage: 330)

https://www.drupal.org/project/ui_skins

Discovery: {provider}.ui_skins.css_variables.yml in modules and themes.

Example (Material 2 background color variables):

mdc_theme_background:
  label: "Default background color"
  category: Background colors
  type: color
  default_values:
    ":root": "#ffffff"

mdc_theme_surface:
  label: "Surface background color"
  category: Background colors
  type: color
  default_values:
    ":root": "#ffffff"

You can override the variables values (by scope) in theme settings. The overridden values are added in a style element to the page header.

Personal opinion:

I am maintainer of this module and I participated to define this format. So I believe this format could be one of the starting point. However, there is a few issues we can fix in this proposal:

• type property is using the Drupal From API instead of a front-dev friendly format like JSON Schema, W3C's Design Tokens format (DTCG), or CSS value types.
• default values are set manually, scope by scope, so any change in the CSS file need to be ported to the YAML file. We may need to use a library like sabberworm/php-css-parser for automatic discovery instead.
• underscores in variable names are automatically replaced by dashes, however underscores are allowed in variable names: https://developer.mozilla.org/en-US/docs/Web/CSS/custom-ident

Design Tokens

https://www.drupal.org/project/design_tokens

A fascinating proof-of-concept from the e0ipso, the creator of SDC

Design Tokens are be declared:

• at theme level, in JSON files, only using the W3C's Design Tokens format (DTCG). JSON is a subset of YAML so it is OK.
• at component level. Example: /with-design-tokens.component.yml

Example (in YAML, but the standard serialization is JSON):

shadow-token:
  "$type": shadow
  "$value":
    color: "#00000080"
    offsetX:
      value: 0.5
      unit: rem
    offsetY:
      value: 0.5
      unit: rem
    blur:
      value: 1.5
      unit: rem
    spread:
      value: 0
      unit: rem
font-size:
  "$value":
    value: 3
    unit: rem
  "$type": dimension

You can override the token values with config entities implementing DesignTokenInterface. The override values are published in a dynamically generated CSS file (see LibraryStyleController and CssVarsSerializer

Personal opinion:

An other great starting point . The dependency to jsonrpc must be skipped for Core inclusion. The idea of using directly DTCG is as great as using Json Schema for SDC props. However, we need to clarify:

• what is happening if we get a DTCG files which is describing all tokens, event the ones not exposed as CSS variables? Or if the CSS variables are not exactly names like the tokens (prefix, format...)?
• do we need other (meta)data?
• how do we treat CSS variables scopes? No default values in the theme and we add only in the override config entity?

CSS Variables (usage: 10)

https://www.drupal.org/project/cssvars

Not compatible with Drupal 11.

No definition format.

Personal opinion:

If my understanding is right, CSS Variables are not really integrated with Drupal. It is only a form with a textarea where people put free values which are attached to page renderable.

CSS color variables (usage: 4)

Works only for colors, but use CSS variables anyway.

Not a YAML plugin discovery but a PHP file to add in the theme, so not front-dev friendly enough: https://git.drupalcode.org/project/css_color_variables/-/blob/1.0.x/colo...

[
  // Available colors and color labels used in theme.
  'fields' => [
    'primary' => t('Primary'),
    'primary__contrast' => t('Primary contrast'),
    'secondary' => t('Socondary'),
    'secondary__contrast' => t('Socondary contrast'),
      ...
  ],
  // Pre_defined color schemes.
  'schemes' => [
    'default' => [
      'title' => t('deGov default'),
      'colors' => [
        'primary' => '#004673',
        'primary__contrast' => '#ffffff',
        'secondary' => '#818D97',
        'secondary__contrast' => '#ffffff',
      ],
    ],
]

Personal opinion:

Value are not scoped/scopable. Predefined schemes are interesting, but let's keep them out of this scope. We may discuss this in a future ticket.

Honorable mentions

• https://www.drupal.org/project/css_custom_properties : only a few weeks old, a single commit.
• https://www.drupal.org/project/style_settings: stuck in Drupal 7

Proposed resolution

Definition & discovery

Based on the analysis below, with some discussions.

For example, it seems it would be a mistake to rely only on automatic discovery from CSS files to get the list of CSS variables, because we will miss the metadata, and because not all CSS variables from a codebase must be exposed to tyhe Drupal CMS. For example, Bootstrap 5 did the mistake of converting all Sass variables (build-time tokens) to CSS variables (runtime tokens) and we need to cherry-pick them.

In the renderer service

There is two expected usage of those variables in the render API.

1. Local usage. Modules can leverage this API by overriding variables values in $build["#attributes"]["style"]. However, this is causing a few issues:

• The syntax is verbose and error prone
• Variables values are mixed with other inline styles
• There is no possibility to add checks about the existence of a variable, or the correctness of the value.

So, it would be better to introduce #variables (or #tokens) universal property, which can be added to every renderables already accepting an #attributes property:

• ['#type' => 'html_tag']
• ['#type' => 'component']
• Most of #theme and most of render elements

This is excluding #markup, #plain_text and maybe some #theme and some render elements.

Example:

$b['#variables'] = [
  'primary-color' => '#2341AB',
]

or:

$b['#tokens'] = [
  'primary-color' => '#2341AB',
]

If we implement also component-specific variables, it will be the opportunity of processing a check to see if the variable exists when #variables (or #tokens) is added to a SDC render element.

So the renderer service to process this by adding the variables/values pair to $build['#attributes']['style']

2. Global usage. Modules can leverage this API by overriding variables values at the page level, leveraging the scope, like UI Skins module is currently doing: https://git.drupalcode.org/project/ui_skins/-/blob/1.1.x/src/HookHandler...

What do we do? We extend #attached render property with a variable (or token) keyword? We extends our own #variables render property? We add an other universal render property?

Example:

$b['#attached']['variable']['primary-color'][':root'] = '#EF2411',

Or:

$b['#attached']['token']['primary-color'][':root'] = '#EF2411',

Remaining tasks

Let's start by contacting the maintainer of the contrib modules to ask them if they want to participate.

User interface changes

No. API only.

Introduced terminology

"CSS variables", "custom properties", "design tokens", "runtime tokens", "cascading variables", "CSS cscope"

API changes

Only additions.

Data model changes

No.