Blok.ink Design Tokens

What is a Design Token?

There is a W3C working group on this topic. Here is the definition of them:

Design tokens are a methodology for expressing design decisions in a platform-agnostic way so that they can be shared across different disciplines, tools, and technologies. They help establish a common vocabulary across organizations.

A basic design token is a pair of values and names that represent a design decision about a color, size, or other elements.

This project uses the Style Dictionary tool to generate SCSS variables from the design token files. This tool aligns with W3C standards, enabling smooth future migration.

The design tokens are created using the Token OS Figma plugin, an internal Storyblok plugin for Figma. This plugin produces JSON files, which we incorporate into this project. With these JSON files, we can generate the SCSS variables accordingly.

This is a small example of the JSON from Figma:

{
  "level": {
    "none": {
      "$type": "number",
      "$value": 100
    },
    "semiopaque": {
      "$type": "number",
      "$value": 80
    },
    "intense": {
      "$type": "number",
      "$value": 64
    },
    "medium": {
      "$type": "number",
      "$value": 32
    },
    "light": {
      "$type": "number",
      "$value": 16
    },
    "semitransparent": {
      "$type": "number",
      "$value": 8
    },
    "transparent": {
      "$type": "number",
      "$value": 0
    }
  }
}

The SCSS result is something like this:

• In SCSS

$opacity-level-none: 100;
$opacity-level-semiopaque: 80;
$opacity-level-intense: 64;
$opacity-level-medium: 32;
$opacity-level-light: 16;
$opacity-level-semitransparent: 8;
$opacity-level-transparent: 0;

• In CSS

:root {
  --opacity-level-none: 100;
  --opacity-level-semiopaque: 80;
  --opacity-level-intense: 64;
  --opacity-level-medium: 32;
  --opacity-level-light: 16;
  --opacity-level-semitransparent: 8;
  --opacity-level-transparent: 0;
}

We can include these variables in the main design system variables file and utilize them as needed.

This package works with two types of tokens: the primitives and the semantics.

Primitive tokens

A primitive token represents a value without a specific meaning. They are useful to describe colors and sizes.

A few examples of a primitive design token, in CSS

:root {
  --sb-border-width-xl: 8px;
  --sb-color-primary-50: #d5fcfa;
  --sb-color-info-300: #a2c1ee;
}

Semantic tokens

A semantic token is a token with a value that has a meaning associated with it. They are very useful for colors, as the Storyblok App works with themes, we could just have a single semantic token that holds different values depending on the theme. For example, the semantic tokens for colors:

/* the default theme has the root definitions for all semantic colors */
:root {
  --sb-color-background-primary: var(--sb-color-neutral-white);
  --sb-color-background-secondary: var(--sb-color-base-50);
  --sb-color-background-tertiary: var(--sb-color-base-200);
}

When the theme is dark, we have different values for these tokens:

[theme='dark'] {
  --sb-color-background-primary: var(--sb-color-base-950);
  --sb-color-background-secondary: var(--sb-color-base-900);
  --sb-color-background-tertiary: var(--sb-color-base-700);
}

Installation

# yarn
yarn add @storyblok/design-tokens

# npm
npm install @storyblok/design-tokens

# pnpm
pnpm install @storyblok/design-tokens

Project structure

When you install this package, it has the following structure:

# the JSON files will be placed here
jsons/
# the generated CSS and SCSS files from the JSONs
tokens/
  - css/
  - scss/
README.md
package.json

JSON's structure:

Inside the jsons folder

- colors/
  - dark-high-contrast.json
  - dark.json
  - default.json # default theme
  - light-high-contrast.json
  - primitives.json # contains all the primitive colors
- borders.json
- font.json
- opacity.json
- shadow.json
- sizes.json
- typography.json

From these JSON tokens, we build the SCSS and CSS variables in the tokens/ folder.

Variables (tokens) structure

css/
- themes/
  - all-themes.css # a file containing the variables and all theme definitions
  - dark-high-contrast.css
  - dark.css
  - default.css # imports the variables and has the main definition of semantic tokens
  - light-high-contrast.css
- typography/
  - semantic-classes.css
- variables.css # contains all variables from colors and other types

scss/
- themes/
  - all-themes.scss # a file containing the variables and all theme definitions
  - dark-high-contrast.scss
  - dark.scss
  # imports the variables and semantic-colors, additionally, has the default theme definitions
  - default.scss
  - light-high-contrast.scss
- typography/
  - semantic-classes.scss
  - semantic-mixins.scss # contains the mixins with the predefined typography styles
- _root-variables.scss # contains the variables as custom properties
- _variables.scss # contains all variables from colors and other types and imports the root-variables file

What tokens should we use?

This package was created for use with the Storyblok Design System. Therefore, in the DS, it is preferable to use semantic values instead of primitive ones. Currently, we have the following primitive tokens:

• colors
• sizing (size-unit tokens)
• opacity
• shadow
• typography

And the semantic ones:

• typography
• colors
• sizing (size-spacing tokens)

How to use the tokens?

We allow some sort of flexibility depending on the use cases.

Only variables

First, if it just wants to use the primitive variables (not recommended):

• In CSS

@import '@storyblok/design-tokens/tokens/css/variables.css';

• In SCSS

// the root-variables contains the Custom CSS Properties
@import '@storyblok/design-tokens/tokens/scss/root-variables';
@import '@storyblok/design-tokens/tokens/scss/variables';

Theme variables

Only the default theme is mandatory in this case. Then, if your app needs more themes, you can import them one by one or use the all-themes file that imports all four themes available:

• In CSS

/* The default theme already imports the variables, so you can just import it */
@import '@storyblok/design-tokens/tokens/css/themes/default';

/* or if you want all the themes */
@import '@storyblok/design-tokens/tokens/css/themes/all-themes';

• In SCSS

// The default theme already imports the variables, so you can just import it
@import '@storyblok/design-tokens/tokens/scss/themes/default';

// or if you want all the themes
@import '@storyblok/design-tokens/tokens/scss/themes/all-themes';

Finally, you can

You need to import the SCSS or the CSS files directly. In your main .scss file, you can import the variables and the root-variables at the top, along with the theme files.

With this, the Custom CSS Properties will be available in the CSS and by using the usual SCSS variables, like:

// you can use the SCSS variable
.foo {
  color: $sb-color-text-primary; // points to var(--sb-color-text-primary)
}

// or pointing directly to the custom property
.foo {
  color: var(--sb-color-text-primary);
}

How do the themes work?

We have four different sets of themes:

• default - the light and theme for Storyblok
• dark
• light-high-contrast
• dark-high-contrast

These themes are defined inside tokens/scss/themes or tokens/css/themes.

The default theme is mandatory, as we recommend using semantic colors instead of primitive ones. The other themes are optional. However, we are using all of them in the Storyblok App (app.storyblok.com).

We control the theme by using the theme property in the HTML tag, like:

<html lang="en" theme="default">
  <!--  -->
</html>

So, if you import the dark theme into your main SCSS file, for example:

@import '@storyblok/design-tokens/tokens/scss/themes/default';
@import '@storyblok/design-tokens/tokens/scss/themes/dark';

If you want to see the dark colors, you need to change the theme property to dark:

<html lang="en" theme="dark">
  <!--  -->
</html>

If you want to have all the themes available in your app, you can just import the all-themes.scss or all-themes.css file. This file contains all the content from variables and the theme definitions:

In CSS

@import '@storyblok/design-tokens/tokens/css/themes/all-themes.css';

In SCSS

@import '@storyblok/design-tokens/tokens/scss/themes/all-themes.scss';

Set up

The instructions below are for the development side.

Project structure:

# folder that contains all the generated SCSS variables from the tokens
# This folder is generated from the yarn build command, so you don't need to edit it
- tokens/

# folder that contains all the JSON tokens
- jsons/

# folder that contains the code that the StyleDictionary uses to implement the
# tokens evaluation
- src/

Please, check the instructions in the Figma Plugin repository: https://github.com/storyblok/design-tokens-figma-plugin?tab=readme-ov-file#how-to-create-the-tokens

As soon as the tokens.json is imported into the packages/design-tokens folder, you can execute the following command to update the JSON token files:

yarn generate:json

With the tokens folder updated, you can execute the following command to generate the CSS and SCSS files:

yarn build