Design tokens zodat AI consistent blijft

Tokens zijn de technische kant van een consistent ontwerp. Zolang een waarde nergens een naam heeft, is elke keer dat een AI-tool hem nodig heeft een nieuwe keuze. Met tokens maak je die keuze één keer, en kiest de tool daarna uit jouw lijst. Hieronder een voorbeeldset in gewone CSS en in Tailwind 4, hoe je de standaardwaarden uitzet, hoe je een tool aan je tokens houdt en hoe je controleert of dat gelukt is.

Herken je dit?

Zonder namen kiest het model uit alles

Een AI-tool die Tailwind gebruikt, heeft een standaardpalet tot zijn beschikking: tientallen kleuren in elf tinten elk. Voor gedempte tekst passen er een stuk of wat grijzen uit verschillende families, en het model heeft geen reden om steeds dezelfde te nemen. Bij afstanden en lettergroottes gaat het net zo. Waar Tailwind niet in de buurt is, schrijft het model hexcodes en pixels uit het hoofd.

Een token draait dat om. Er is één --color-text-muted, en elke component gebruikt die. Verander je de waarde, dan verandert hij overal. Voor een AI-tool is een naam ook makkelijker te volgen dan een waarde: “gebruik alleen tokens uit tokens.css” is een opdracht die hij kan controleren, “gebruik onze kleuren” niet.

Tokens werken in twee lagen. Basiswaarden zijn de kleuren en maten zelf, met een neutrale naam. Rollen zeggen waarvoor een waarde is: tekst, vlak, actie, focus. Componenten gebruiken alleen de rollen. Wil je later een andere actiekleur, dan wijzig je één regel en blijft de naam kloppen.

Zo zet je tokens op

1. Een voorbeeldset in CSS

Dit is een kleine, complete set voor een zakelijke site. Elke kleurcombinatie die voor tekst bedoeld is, haalt de 4,5:1 contrast die WCAG voor gewone tekst vraagt.

:root {
  /* basiswaarden */
  --blue-900: #12243A;
  --blue-600: #1F5FA8;
  --grey-50: #F5F7FA;
  --grey-600: #56606B;

  /* rollen */
  --color-bg: #FFFFFF;
  --color-surface: var(--grey-50);
  --color-text: var(--blue-900);
  --color-text-muted: var(--grey-600);
  --color-action: var(--blue-600);
  --color-focus: var(--blue-600);

  --font-display: "Archivo", system-ui, sans-serif;
  --font-body: "Source Serif 4", Georgia, serif;
  --text-sm: 0.875rem;
  --text-base: 1.125rem;
  --text-xl: 1.5rem;
  --text-3xl: 2.5rem;

  --space-1: 0.5rem;
  --space-2: 1rem;
  --space-3: 1.5rem;
  --space-4: 2rem;
  --space-6: 3rem;
  --space-8: 6rem;

  --radius-sm: 4px;
  --radius-md: 8px;
}

Zes afstanden en twee afrondingen lijken weinig. Dat is de bedoeling: met minder keuzes valt een afwijking eerder op.

2. Dezelfde set in Tailwind 4

In Tailwind 4 staan tokens in een @theme-blok in je CSS. Elke variabele maakt de bijbehorende classes aan: --color-action geeft bg-action en text-action. Met --color-*: initial gooi je het standaardpalet weg, zodat text-gray-600 niet meer bestaat.

@import "tailwindcss";

@theme {
  --color-*: initial;
  --color-white: #FFFFFF;
  --color-ink: #12243A;
  --color-muted: #56606B;
  --color-surface: #F5F7FA;
  --color-action: #1F5FA8;

  --font-display: "Archivo", system-ui, sans-serif;
  --font-body: "Source Serif 4", Georgia, serif;

  --radius-*: initial;
  --radius-sm: 4px;
  --radius-md: 8px;
}

Afstanden rekent Tailwind 4 uit één basiswaarde, --spacing. Dat is al een schaal. Spreek af welke stappen je gebruikt, bijvoorbeeld 2, 4, 6, 8, 12 en 24, en zet die afspraak in je regels.

3. Houd de tool aan je tokens

Leg de tokens vast voordat je de eerste pagina laat genereren, en zeg in de opdracht dat niets anders mag.

Gebruik voor kleur, lettertype, afstand en afronding alleen de tokens uit tokens.css.
Schrijf nooit een hexcode, een px-waarde of een Tailwind-kleur die daar niet in staat.
Mis je een waarde, stop dan en vraag welke token je moet gebruiken.

In Claude Code en Cursor zet je die instructie in het instructiebestand van het project, zodat hij elke sessie meegaat. Hoe dat werkt, en wat er verder in zo’n regelbestand hoort, staat in een DESIGN.md maken voor je AI-tools.

4. Controleer op losse waarden

Ook een tool die zich aan de afspraak houdt, glipt er af en toe een waarde doorheen. Twee zoekopdrachten vinden ze.

grep -rnE '#[0-9a-fA-F]{3,8}|rgb\(' src/ | grep -v 'tokens.css'

grep -rnoE '[a-z-]+-\[[^]]+\]' src/

Wil je dat het vanzelf gaat, zet dan de regel color-no-hex aan in Stylelint. Die geeft een fout bij elke hexcode. In het tokenbestand zelf zet je hem uit met /* stylelint-disable color-no-hex */ bovenaan.

Veelgemaakte fouten

Wanneer je hulp nodig hebt

Heb je een export vol losse waarden, dan is omzetten naar tokens precies het werk waar AI-design laten verbeteren over gaat. Bij AI-design omzetten naar een echte website bouwen we de site vanaf het begin op één set tokens, zodat een kleurwijziging later één regel is. Waarom een AI-tool zonder tokens per scherm andere keuzes maakt, staat in waarom is mijn AI-design inconsistent. Alle gidsen staan in het overzicht van AI-design.