# 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](https://styledictionary.com/) 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:

```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

```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

```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

```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:

```css
/* 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:

```css
[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

```sh
# 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:

```sh
# 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

```sh
- 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

```sh
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

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

- In SCSS

```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:**

```ts
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

```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

```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:

```scss
// 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
<html lang="en" theme="default">
  <!--  -->
</html>
```

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

```scss
@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
<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

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

In SCSS

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

Copyright © 2026 Storyblok GmbH