Skip to content

Design tokens ​

The tokens of your design system become the values editors pick in Layout and style, and the same values reach your SCSS and CSS. They are declared once, in the .info.yml of the theme.

Map your tokens ​

Take the scales of your design and write them under frame_editor: uikit:. Names are yours; keep them short, they are what editors see and what a layout stores.

yaml
# my_theme.info.yml
frame_editor:
  uikit:
    spacing:        # margin, padding, gaps, offsets
      xs: 0.25rem
      s: 0.5rem
      m: 1rem
      l: 2rem
      xl: 4rem
    font_sizes:     # sizes an editor can give text
      s: 0.875rem
      m: 1rem
      l: 1.25rem
      xl: 1.5rem
    sizes:          # how wide and how tall a component can be
      s: 30rem
      m: 45rem
      l: 60rem
      full: 100%
    colors:         # the only colours an editor can pick
      primary: { label: 'Primary', value: '#0b5cad' }
      surface: { label: 'Surface', value: '#f4f6f8' }
      ink: { label: 'Ink', value: '#1b1f24' }
    border_widths:
      thin: 1px
      thick: 3px
    icon_sizes:
      m: 1.5rem
    stroke_widths:
      regular: 2
    radii:
      s: 0.25rem
      m: 0.5rem
      full: 9999px
    image_styles:   # leave out to offer all of them
      - large
      - 'responsive:wide'
    layout:
      content: 72rem
      wide: 90rem

Every key, its default and what is accepted: Settings reference.

Your design hasPut it in
a spacing scale (4, 8, 16, 32…)spacing, as rem or px
a type scalefont_sizes
container or column widthssizes for components, layout for the page
brand and neutral colourscolors, each with a label editors read
border and corner tokensborder_widths, radii
icon sizes and stroke widthsicon_sizes, stroke_widths
a page grid with a max widthlayout.content, and layout.wide for wide bands

Values must be plain CSS lengths (a number and one of px, rem, em, %, vw, vh, ch, or 0) and plain colours (#hex, rgb(), hsl(), or a colour name). Anything else is left out without an error. layout also takes var(), calc(), min() and max().

Tokens of Drupal core (<theme>.tokens.yml) ​

Drupal core (11.5 and later) has a Design Tokens API: a theme declares tokens in my_theme.tokens.yml in the DTCG format, and a design_token configuration entity can override a token in a CSS scope (:root, .card). Frame reads the same file, so you declare a scale once. Frame only reads the file as YAML: it needs no class of core and also works on Drupal 11.4, which has no such API. The SCSS build (frame/tokens) reads it too.

yaml
# my_theme.tokens.yml
spacing:
  $type: dimension
  s: { $value: { value: 0.5, unit: rem } }
  m: { $value: { value: 1, unit: rem } }
  l: { $value: { value: 2, unit: rem } }
fontSize:
  $type: dimension
  lede: { $value: { value: 1.4, unit: rem } }
color:
  $type: color
  brand: { $value: '#0f766e', $description: 'Brand teal' }
  accent: { $value: '{color.brand}' }   # a reference to another token

A group at the top of the file gives a scale of Frame when it has one of these names (case, -, _ and spaces do not matter):

GroupScale of Frame
spacing, spacespacing
fontSize, font-size, font_sizesfont sizes
size, sizessizes
radius, radii, borderRadiuscorner radii
borderWidth, border-widthsborder widths
iconSize, iconSizesicon sizes (icon_sizes)
strokeWidth, strokeWidthsstroke widths of icons (stroke_widths), plain numbers
lineHeight, lineHeightsline heights of text (line_heights), plain numbers or dimensions
color, colorspalette (see below)

A token is a name and a $value: a dimension ({ value: 1, unit: rem }), a text (1rem) or a reference ({spacing.m}). A group inside a group adds its name to the names of its tokens (brand.light is brand-light). Values are checked as in the .info.yml: only lengths and colours pass. Editors see the names of the tokens ("M (1rem)"); a colour is labelled with its $description, else with its name.

The editor offers the tokens of tokens.yml

Which file wins: for every theme, base themes first, the tokens file, then uikit of its .info.yml. So uikit stays the override, and a scale is replaced as a whole. The file does not set layout, features or image styles.

Colours. Core has no colour type yet, so it ignores a color group. Frame reads it, but the colour is not a token of core: it has no custom property of core and no override. Keep colours here or in uikit.colors, as you like.

One source of truth, with overrides. A dimension that core knows (type dimension, unit px or rem, written as { value, unit }) is printed by core as a custom property named after its path: spacing.m is --spacing-m, fontSize.lede is --fontSize-lede (the case is kept; ., _ and spaces become -). Frame uses it as var(--spacing-m, 1rem), with the value of the file as the fallback, in its utility classes, in --frame-space-m and in the styles of components. So a design_token override changes them. Core does not print the overrides itself yet, so Frame does it on the pages of your theme, with core's own DesignToken::toCss(); where core has no such API nothing is printed and the values of the file are used. Tokens that core does not know (a reference, a text such as 1rem, a unit such as em) are plain values. --frame-space-m is set on :root, so a scope override (.card) reaches the classes, not that variable.

Not offered. Typography, font family, font weight and number tokens are for your own CSS (--typography-...); Frame has fixed choices for text. Creating an override from Frame (an admin form) is not part of Frame; use core's configuration.

A design_token override changes the page; the file's value is the fallback

Custom properties as tokens ​

A value of any scale or of the palette can also be a custom property, var(--name) or var(--name, fallback), where the fallback is a value of the same kind (a length, a colour, or another var()). Frame prints it as it is in the custom properties of the page, in the utility classes and in the inline styles of components, so a kit whose colours or spaces are custom properties, and that change them with a colour scheme or a density, is followed by every page:

yaml
frame_editor:
  html_attributes:
    data-theme: { default: light, options: { light: Light, dark: Dark } }
  uikit:
    colors:
      brand: { label: Brand, value: 'var(--kit-brand, #0b5fff)' }
      surface: 'var(--kit-surface)'
    spacing: { m: 'var(--kit-space-4, 1rem)', l: 'var(--kit-space-6)' }
    radii: { s: 'var(--kit-radius)' }

The editor shows what a token looks like now: swatches and the values in the lists of sizes are computed in the canvas, on the <html> element of the page being edited, so they follow its html attributes (a dark scheme shows the dark colours). Without a computed value the fallback is shown, then the name. A layout still stores the name of the token, never the computed value. What an editor types as a custom length is still a plain length.

A value with anything that could end the declaration (;, {, }, quotes, url(), a fallback that is not a value of the kind) is left out, as any other value that is not valid.

Names are stored, values are not ​

A layout stores the name ("size": "m", "color": "primary"), not the value. Changing m from 1rem to 1.25rem changes every page that uses it. Removing or renaming a name makes the places that used it fall back to nothing, so rename with care.

Use them in SCSS ​

The build of a subtheme gives the same tokens as a Sass module:

scss
@use 'frame/tokens' as frame;

.teaser {
  padding: frame.space(m);
  color: frame.color(ink);
  font-size: frame.font-size(l);

  @include frame.breakpoint(tablet) {
    padding: frame.space(l);
  }
}

A name the theme does not declare stops the build, with the list of the names it has. With a build of your own, write the module to a file: node ../../contrib/frame/bin/frame.mjs tokens --out scss/_tokens.scss. All functions and mixins: Tokens in SCSS.

Use them in CSS ​

With the editor module on, every page of the theme has the tokens as custom properties: --frame-space-<name>, --frame-font-<name>, --frame-color-<name>, --frame-border-<name>, --frame-radius-<name>, and --frame-accent (the colour named accent or primary, else the first one). The components of the base theme use them, so they take your colours without CSS.

css
.teaser { padding: var(--frame-space-m); border-radius: var(--frame-radius-m); }

An existing token set ​

If your design system already has its tokens as CSS custom properties or SCSS variables, keep them as the source and copy the values into the .info.yml, or point your own variables at Frame's:

scss
@use 'frame/tokens' as frame;

:root {
  --brand-primary: #{frame.color(primary)};
  --space-4: #{frame.space(m)};
}

Either way, the editor offers only what the .info.yml declares. A token that is not there cannot be picked.

Limitations ​

  • The tokens are read from the .info.yml: after a change, rebuild caches (drush cr) and the theme's CSS.
  • A scale or palette of a subtheme replaces the base theme's as a whole.
  • Sizes (sizes) have no custom property of their own.
  • There is no second palette: one palette per theme. For a dark mode, make the tokens custom properties that the colour scheme changes.