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 package uses Style Dictionary to turn token definitions into CSS, SCSS, and JavaScript outputs. That aligns with W3C-oriented token practice and keeps room to evolve with the ecosystem.

Tokens are defined as JSON and shipped in this package; the examples below illustrate the shape of those definitions.

This is a small example of token JSON:

{
  "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;
}

You can reference these values from your own stylesheets or components 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 whose name reflects intent (for example, “background primary”) rather than a raw palette value. For colors, one semantic token can resolve to different primitives per theme. For example:

/* 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);
}

For a dark theme, the same semantic names can point at different primitives:

[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, SCSS, and JS files from the JSONs
tokens/
  - css/
  - js/
  - 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

The tokens/ folder contains the CSS, SCSS and JS generated from those JSON definitions.

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

Which tokens should you use?

These tokens are intended to support Storyblok’s design language. In application UI, prefer semantic tokens over primitive ones when both exist for the same concern. Primitive families in this package include:

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

And the semantic ones:

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

How to use the tokens?

You can mix imports depending on whether you need only primitives, full themes, or JavaScript color constants.

Only variables

If you only need primitive variables (not recommended):

• In CSS

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

• In SCSS

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

// or you namespace the variables
@use '@storyblok/design-tokens/tokens/scss/variables' as vars;

JavaScript variables

The package entry @storyblok/design-tokens resolves to ESM plus TypeScript declarations (index.mjs / index.d.ts under tokens/js/). Those files are part of the published build — do not edit them inside node_modules.

What is included: only primitive color values as named exports. Theme palettes, semantic aliases, and non-color categories (spacing, typography, shadows, and so on) are not available as JS constants; use the CSS or SCSS layers and custom properties for those.

Naming: camelCase with an sb prefix (for example sbColorPrimary500, sbColorNeutralWhite), aligned with the primitive --sb-color-* custom properties.

Usage:

import { sbColorPrimary500, sbColorBase950 } from '@storyblok/design-tokens'

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
@use '@storyblok/design-tokens/tokens/scss/themes/default';

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

Import the SCSS or CSS entry points you need. In a typical SCSS setup, pull in variables (and theme files when required) near the top of your bundle.

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?

There are four theme bundles:

• default — baseline light theme
• dark
• light-high-contrast
• dark-high-contrast

Their definitions live under tokens/css/themes and tokens/scss/themes.

For semantic colors, include at least the default theme. Use al-themes when you want to have all the themes available in your app.

Set the active theme on the root element, for example:

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

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

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

And 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

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

Copyright © 2026 Storyblok GmbH