Guide

Design tokens, explained with real files

A design token is a named design decision: a color, a spacing, a font size. Stored once, used everywhere, by the design tool and by the code.

Why tokens matter

Without tokens, the blue of your buttons is written in the design file, then again in the CSS, then again in the app. Change it once and you must find it everywhere. With tokens, you change color.brand and every place that uses it follows.

What a token file looks like

The W3C Design Tokens Community Group defines a JSON format where each token has a $value and a $type.

{
  "color": {
    "brand": { "$value": "#2F5BEA", "$type": "color" },
    "ink":   { "$value": "#121214", "$type": "color" }
  },
  "space": {
    "4": { "$value": "16px", "$type": "dimension" }
  }
}

The same decisions, turned into CSS variables the browser can use:

:root {
  --color-brand: #2F5BEA;
  --color-ink: #121214;
  --space-4: 16px;
}

How Kalka uses tokens

  • One folder: every project has a design-system/ folder with tokens.json in the W3C format and tokens.css next to it.
  • Used on the canvas: when you pick a color or a spacing in the design panel, you pick a token, and the CSS uses the variable.
  • Versioned with Git: a change to your brand color is a commit you can review, like any code change.

Kalka is in development and open source. The folder structure above comes from our product spec.