# Design tokens: één bron voor kleur en typografie

[Canonical HTML page](https://gradiently.design/nl/guide/design-tokens)

Een merkkleur die in veertig bestanden staat, gaat afwijken. Een token staat op één plek en elk platform leest ervan. Zo structureer je design tokens, benoem je ze zodat ze blijven werken en lever je ze aan code en ontwerptools.

## The short version

- Design tokens zijn benoemde, platformneutrale waarden voor ontwerpbeslissingen zoals kleuren, lettertypefamilies, formaten, spatiëring, hoekradii, schaduwen en bewegingstijden.
- De meeste tokensystemen gebruiken drie lagen: primitieve tokens bevatten ruwe waarden, semantische tokens beschrijven een doel en componenttokens passen doelen toe op specifieke onderdelen.
- Het formaat van de W3C Design Tokens Community Group slaat tokens op als JSON met de eigenschappen $value en $type en verwijst naar andere tokens met accolades.
- Tools zoals Style Dictionary zetten één tokenbestand om naar CSS custom properties, JavaScript en iOS- en Android-resources.
- Dark mode en meerdere merken komen neer op het verwisselen van de waarden achter semantische tokens, terwijl componenten ongewijzigd blijven.

**Design tokens** zijn benoemde waarden voor elke ontwerpbeslissing die een merk herhaalt: kleuren, lettertypen, lettergroottes, spatiëring, hoekradii, schaduwen en animatietiming. In plaats van `#5b21b6` in een stylesheet, een Figma-bestand en een iOS-app te typen, definieer je `color.brand.700` één keer, in één bestand, en genereer je daaruit het formaat van elk platform. Wijzig de token en elk product wordt tegelijk bijgewerkt. Die ene bron van waarheid is het hele punt.

## Hoe een design token eruitziet

Een token heeft een naam, een waarde en een type. Het formaat van de [W3C Design Tokens Community Group](https://www.w3.org/community/design-tokens/) schrijft ze als JSON, met eigenschappen die met een dollarteken beginnen zodat ze niet botsen met groepsnamen.

```json
{
  "color": {
    "violet": {
      "100": { "$type": "color", "$value": "#ede9fe" },
      "500": { "$type": "color", "$value": "#8b5cf6" },
      "700": { "$type": "color", "$value": "#6d28d9" },
      "900": { "$type": "color", "$value": "#4c1d95" }
    },
    "ink": { "$type": "color", "$value": "#14121f" },
    "paper": { "$type": "color", "$value": "#faf8ff" }
  },
  "font": {
    "heading": { "$type": "fontFamily", "$value": ["Fraunces", "Georgia", "serif"] },
    "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
  },
  "radius": {
    "control": { "$type": "dimension", "$value": { "value": 10, "unit": "px" } }
  },
  "duration": {
    "quick": { "$type": "duration", "$value": { "value": 160, "unit": "ms" } }
  }
}
```

Primitieve tokens in het formaat van de community group. Groepen nesten vrij; het pad, zoals color.violet.700, wordt de naam van de token.

- color.violet.100: #ede9fe
- color.violet.500: #8b5cf6
- color.violet.700: #6d28d9
- color.violet.900: #4c1d95
- color.ink: #14121f
- color.paper: #faf8ff

De kleurtokens hierboven als stalen. Dit zijn ruwe ingrediënten: nog niets zegt welke een knop of een kop is.

## Primitieve, semantische en componenttokens

Een platte lijst kleuren is een palet, geen systeem. De structuur die jaren standhoudt heeft drie lagen, die elk naar de laag eronder verwijzen. Componenten raken nooit ruwe waarden aan; ze vragen om een doel.

| Laag | Voorbeeldnaam | Waarde | Verandert wanneer |
| --- | --- | --- | --- |
| Primitief | `color.violet.700` | `#6d28d9` | Het palet opnieuw wordt ontworpen |
| Semantisch | `color.action.primary` | `{color.violet.700}` | Een rol naar een andere kleur verhuist |
| Semantisch | `color.text.default` | `{color.ink}` | Dark mode, een nieuw merk |
| Component | `button.primary.background` | `{color.action.primary}` | Eén component een uitzondering nodig heeft |

Verwijzingen tussen accolades zijn aliassen. Wijzig color.violet.700 en elke token die ernaar verwijst volgt.

```json
{
  "color": {
    "action": {
      "primary": { "$type": "color", "$value": "{color.violet.700}" },
      "primary-hover": { "$type": "color", "$value": "{color.violet.900}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.ink}" },
      "on-action": { "$type": "color", "$value": "{color.paper}" }
    },
    "surface": {
      "page": { "$type": "color", "$value": "{color.paper}" },
      "tint": { "$type": "color", "$value": "{color.violet.100}" }
    }
  }
}
```

Semantische tokens beschrijven waar een kleur voor dient. Dit is de laag waarin ontwerpers en ontwikkelaars met elkaar moeten praten.

Veel teams stoppen bij twee lagen, primitief en semantisch, en voegen componenttokens alleen toe waar een component echt afwijkt. Zo blijft het bestand klein genoeg om te begrijpen.

## Design tokens zo benoemen dat de namen blijven werken

Namen overleven waarden. Een token met de naam `color.purple` breekt op de dag dat het merk turquoise wordt; een token met de naam `color.action.primary` overleeft dat. Benoem semantische tokens naar rol en laat primitieve namen de waarde beschrijven.

### Namen die slecht verouderen

- `color.purple` gebruikt voor knoppen
- `text.dark`, dat licht is in dark mode
- `spacing.16` gebruikt als opmaakregel
- `blue2`, `blueNew`, `blueFinal`
- `hero.gradient.lisa` vernoemd naar een persoon

### Namen die blijven werken

- `color.action.primary`
- `color.text.default`
- `space.section` verwijzend naar `{space.16}`
- Een genummerde schaal zoals `blue.100` tot `blue.900`
- `gradient.hero` met zijn stops als tokens

Kies een patroon, zoals categorie, dan rol, dan variant, dan status, en leg het vast in je [merkstijlgids](https://gradiently.design/nl/guide/brand-style-guide). Consistentie in naamgeving telt zwaarder dan welk patroon je kiest.

## Van tokenbestand naar CSS en apps

Het tokenbestand wordt niet zoals het is meegeleverd. Een buildstap zet het om naar wat elk platform nodig heeft. Style Dictionary is daarvoor de meest gebruikte opensourcetool, en andere lezen hetzelfde formaat. Voor het web is de uitvoer meestal CSS custom properties.

```css
:root {
  --color-violet-100: #ede9fe;
  --color-violet-700: #6d28d9;
  --color-violet-900: #4c1d95;
  --color-ink: #14121f;
  --color-paper: #faf8ff;

  --color-action-primary: var(--color-violet-700);
  --color-text-default: var(--color-ink);
  --color-surface-page: var(--color-paper);

  --font-heading: Fraunces, Georgia, serif;
  --radius-control: 10px;
  --duration-quick: 160ms;
}

.button {
  background: var(--color-action-primary);
  color: var(--color-paper);
  border-radius: var(--radius-control);
  transition: background var(--duration-quick) ease;
}
```

Gegenereerde uitvoer. Aliassen worden var()-verwijzingen, zodat de semantische laag tot in de browser blijft bestaan. Zie [CSS-variabelen voor thema’s](https://gradiently.design/nl/guide/css-custom-properties-theming).

Gebruik je Tailwind v4, dan is het `@theme`-blok zelf een tokenlaag: elke `--color-*`-variabele wordt een utility. [Tailwind-kleuren](https://gradiently.design/nl/guide/tailwind-colors) laat zien hoe je een tokenreeks erin aansluit. Hetzelfde bestand kan ook Swift-constanten en Android-resources maken, en daar betalen tokens zichzelf terug bij teams die op meerdere platforms werken.

## Dark mode en meerdere merken

Omdat componenten alleen semantische tokens lezen, is een thema gewoon een andere set waarden voor die laag. Dark mode definieert `color.text.default` en `color.surface.page` opnieuw; een tweede merk definieert `color.action.primary` opnieuw. Aan de componenten verandert niets.

```css
@media (prefers-color-scheme: dark) {
  :root {
    --color-text-default: #e9e5f5;
    --color-surface-page: #0b0a14;
    --color-action-primary: var(--color-violet-500);
  }
}

[data-brand="harbour"] {
  --color-action-primary: #0f766e;
}
```

Twee overschrijvingen, geen aanpassingen aan componenten. Ook verlopen verdienen eigen donkere waarden; [dark mode verlopen](https://gradiently.design/nl/guide/dark-mode-gradients) legt uit hoe je ze afstemt.

> **Tokens in ontwerptools** Figma Variables ondersteunen collecties en modi, die netjes overeenkomen met primitieve en semantische tokens en met lichte en donkere thema’s. Houd het tokenbestand als bron en synchroniseer naar de ontwerptool, niet andersom, anders zijn de twee binnen een maand het oneens.

## Design tokens uitrollen

1. **Inventariseer wat er is** Verzamel elke gebruikte kleur, lettergrootte en spatiëringswaarde. Verwacht duplicaten die één hexcijfer verschillen.
2. **Definieer primitieven** Breng ze terug tot heldere schalen. Kleurreeksen bouwen in OKLCH houdt de stappen gelijkmatig; zie [OKLCH uitgelegd](https://gradiently.design/nl/guide/oklch-explained).
3. **Voeg de semantische laag toe** Benoem rollen: tekst, vlak, rand, actie, feedback. Laat elk naar een primitief verwijzen.
4. **Automatiseer de build** Genereer CSS en app-resources uit het bestand in je build, nooit met de hand.
5. **Bewaak het** Lint op ruwe hexwaarden in componenten, zodat nieuwe code vanaf dag één tokens gebruikt.

Tokens houden het product consistent, maar merken driften ook in de beelden die erbuiten worden gemaakt: posts, slides, banners. Een merkkit in Gradiently bevat dezelfde beslissingen, je kleurenpaletten, kop- en broodlettertypen, logo’s en toon, zodat ontwerpen uit de Studio erbij passen. En omdat Gradiently werkt binnen ChatGPT, Claude en andere assistenten die remote MCP-servers ondersteunen, kan een assistent met een afgebakende API-sleutel ontwerpen in je huisstijl maken vanuit dezelfde werkruimte. [Merkconsistentie](https://gradiently.design/nl/guide/brand-consistency) behandelt de bredere gewoonte.

## FAQ

### Wat zijn design tokens?

Benoemde waarden voor ontwerpbeslissingen zoals kleuren, lettertypen, spatiëring, radii en beweging, opgeslagen in één platformneutraal bestand en omgezet naar CSS, appcode en variabelen van ontwerptools.

### Wat is het verschil tussen primitieve en semantische tokens?

Primitieve tokens bevatten ruwe waarden, zoals `color.violet.700`. Semantische tokens beschrijven een doel, zoals `color.action.primary`, en verwijzen naar een primitief.

### Zijn design tokens hetzelfde als CSS-variabelen?

Nee. Tokens zijn de bron, opgeslagen in een neutraal formaat zoals JSON; CSS custom properties zijn één uitvoer die eruit wordt gegenereerd, naast uitvoer voor andere platformen.

### Is er een standaardformaat voor design tokens?

De W3C Design Tokens Community Group publiceert een JSON-formaat met $value, $type en aliassen tussen accolades, dat tools zoals Style Dictionary kunnen lezen.

### Hoe gaan design tokens om met dark mode?

Componenten lezen semantische tokens en een donker thema levert andere waarden voor die tokens, zodat componenten niet hoeven te veranderen.