Design tokens koppelen aan Tailwind

Design tokens koppelen aan Tailwind

Drie Figma-bestanden, vier frontend-developers en één stylesheet die niemand durft aan te raken. Zo ziet een project zonder design tokens eruit. Met Hyvä UI en een goed ingericht tailwind.config.js los je dat in één keer op: kleuren, spacing en typografie zitten op één plek, Figma en code praten dezelfde taal.

Wat zijn design tokens?

Design tokens zijn de bouwstenen van een visueel systeem. Geen vage definities, maar concrete waarden:

• color-primary: #1D4ED8
• spacing-md: 1.5rem
• font-size-heading: 2.25rem

In Figma leven ze als variabelen of styles. In code leven ze in je Tailwind-configuratie. Het probleem: zonder expliciete koppeling leven ze twee keer, en lopen ze vroeg of laat uit de pas.

Hyvä UI lost dit op met een Figma Community-bestand. De design tokens en componenten in dat bestand matchen 1-op-1 met de Tailwind-classes in de code. Geen handmatig overzetten, geen "is dit de juiste blauw?"-discussies.

Hoe werkt de koppeling technisch?

Figma exporteert design tokens tegenwoordig als JSON via de Variables API of via plugins zoals Tokens Studio. Die JSON vertaal je naar Tailwind-config-waarden.

Een voorbeeld van een geëxporteerde token-set uit Figma:

{
  "color": {
    "primary": { "value": "#1D4ED8", "type": "color" },
    "primary-dark": { "value": "#1E3A8A", "type": "color" },
    "surface": { "value": "#F9FAFB", "type": "color" }
  },
  "spacing": {
    "xs": { "value": "0.5rem", "type": "spacing" },
    "sm": { "value": "1rem", "type": "spacing" },
    "md": { "value": "1.5rem", "type": "spacing" },
    "lg": { "value": "2rem", "type": "spacing" },
    "xl": { "value": "3rem", "type": "spacing" }
  },
  "font": {
    "size-base": { "value": "1rem", "type": "fontSizes" },
    "size-lg": { "value": "1.25rem", "type": "fontSizes" },
    "size-heading": { "value": "2.25rem", "type": "fontSizes" }
  }
}

Dit JSON-bestand koppel je aan Tailwind via een simpel script, of je vertaalt het direct met de hand naar de theme-sectie.

Tailwind configureren met design tokens

Een opgeschoond tailwind.config.js dat de tokens uit Figma weerspiegelt:

// tailwind.config.js
const tokens = require('./design-tokens.json');

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx,php}',
    './templates/**/*.phtml',
  ],
  theme: {
    colors: {
      transparent: 'transparent',
      current: 'currentColor',
      primary: {
        DEFAULT: tokens.color.primary.value,
        dark: tokens.color['primary-dark'].value,
      },
      surface: tokens.color.surface.value,
      white: '#ffffff',
      black: '#000000',
    },
    spacing: {
      0: '0',
      xs: tokens.spacing.xs.value,
      sm: tokens.spacing.sm.value,
      md: tokens.spacing.md.value,
      lg: tokens.spacing.lg.value,
      xl: tokens.spacing.xl.value,
    },
    fontSize: {
      base: [tokens.font['size-base'].value, { lineHeight: '1.6' }],
      lg: [tokens.font['size-lg'].value, { lineHeight: '1.5' }],
      heading: [tokens.font['size-heading'].value, { lineHeight: '1.2' }],
    },
    extend: {
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
    },
  },
  plugins: [],
};

Merk op dat we hier theme gebruiken in plaats van theme.extend voor kleuren en spacing. Dat is een bewuste keuze: je wilt niet dat Tailwind's standaard-palet door je custom tokens heen lekt. Gebruik extend alleen voor zaken die je wilt optellen, niet vervangen.

Hyvä UI en de Figma-koppeling in de praktijk

Wat dat betekent in de praktijk:

• Een designer past de primaire kleur aan in Figma: één waarde in het token-bestand.
• De developer exporteert de nieuwe JSON, runt de build, klaar.
• Geen "kun je dat blauw nog iets donkerder maken?" terwijl je twintig losse bestanden doorzoekt.

Wij zien bij klanten dat dit soort losse eindjes van Figma naar code gemiddeld 20-40% van de front-end-reviewtijd opslurpt. Design tokens elimineren die categorie fouten volledig.

Welke tokens pak je als eerste aan?

Begin niet met alles tegelijk. De hoogste impact zit in:

Start met kleuren en spacing. Die geven in de eerste sprint al zichtbaar resultaat.

Structuur: tokens in lagen

Professionele design-systemen werken met twee lagen tokens:

• blue-700: #1D4ED8
• space-6: 1.5rem

• color-primary: {blue-700}
• spacing-section: {space-6}

In Tailwind configureer je het liefst de semantische laag. Dat maakt het mogelijk om van een licht naar donker thema te wisselen zonder alle Tailwind-classes te herschrijven. Hyvä UI's Figma-bestand werkt ook zo: de componenten refereren aan semantische tokens, niet aan directe hex-waarden.

Build-pipeline: tokens automatisch bijhouden

Handmatig exporteren werkt, maar je wil uiteindelijk automatisering. Een simpele setup:

1. Designer wijzigt een variabele in Figma.
2. CI/CD-job triggered via de Figma API en exporteert de nieuwe design-tokens.json.
3. Pull request wordt aangemaakt met de diff.
4. Developer reviewt en mergt — Tailwind build pikt de nieuwe waarden op.

Dit kost een dag om in te richten. Het bespaart daarna uren per sprint.

Voor kleinere teams werkt ook een halfautomatische aanpak: designer exporteert handmatig de JSON via Tokens Studio, gooit hem in de repo, developer runt npm run build. Minder elegant, maar beter dan geen koppeling.

Hyvä UI gebruiken buiten Magento

Hyvä UI is framework-agnostisch. De componentbibliotheek draait op Tailwind CSS en Alpine.js, niet op een specifiek framework. Dat betekent:

• Bruikbaar in Magento 2 (boven op een Hyvä theme of standalone)
• Bruikbaar in Laravel + Blade
• Bruikbaar in headless setups
• Bruikbaar in statische sites

Hyvä UI is expliciet niet hetzelfde als een Hyvä theme. Een Hyvä theme is de volledige Magento 2 frontend die Luma (met RequireJS, jQuery en Knockout) vervangt. Hyvä UI is een losse componentbibliotheek die je bovenop een bestaand project kunt gebruiken. Verwar ze niet.

Meer over de Tailwind-configuratie specifiek voor Hyvä lees je in dit artikel over de Hyvä UI Tailwind-config.

Performance: waarom dit relevant is voor Lighthouse-scores

Tailwind met een goed geconfigureerde content-scan genereert alleen de CSS die je daadwerkelijk gebruikt. Dat is standaard al efficiënt. Met design tokens voeg je daar consistentie aan toe: geen utility-class-spaghetti, geen dubbele kleur-definities die de purge-stap verwarren.

Hyvä UI's performance-filosofie: ~95% minder JavaScript dan de standaard Luma-frontend van Magento 2. Lighthouse-scores van 95+ zijn realistisch. Maar die scores vereisen ook dat je CSS niet uit de hand loopt. Een goede Tailwind-config met tokens houdt de stylesheet klein en voorspelbaar.

Wanneer Hyvä UI niet de juiste keuze is

Eerlijk zijn hoort erbij. Hyvä UI is niet altijd de juiste keuze:

• Je gebruikt geen Tailwind. Hyvä UI is gebouwd op Tailwind CSS. Gebruik je Bootstrap, SCSS-modules of een ander framework, dan is de componentbibliotheek niet bruikbaar zonder aanpassingen.
• Je team werkt al met een ander design system. Als je al een volwassen systeem hebt in Storybook of met Web Components, voeg je een extra laag toe zonder duidelijke winst.
• Je hebt geen Figma-workflow. Het Figma Community-bestand is waardevol als je Figma gebruikt. Is dat niet zo, dan mis je een groot deel van de waarde.
• Je verwacht een volledig Magento 2 theme. Hyvä UI is geen theme. Als je Luma wilt vervangen, heb je een Hyvä theme nodig. Hyvä UI is een toevoeging, geen vervanging.

De prijs is eenmalig rond de 250 euro per developer/projectlicentie, geen abonnement. Dat is een lage drempel. Maar een lage drempel rechtvaardigt geen verkeerde keuze.

Meer context over het complete design-systeem vind je in dit overzicht van het Figma-bestand van Hyvä UI.

Samengevat: één bron van waarheid

Design tokens zijn geen luxe. Ze zijn de afspraak tussen Figma en code. Zonder die afspraak groeien de twee systemen uit elkaar, en betaal je dat verschil als technische schuld.

Met Hyvä UI en een goed geconfigureerd tailwind.config.js zit die afspraak vast:

• Figma exporteert JSON.
• Tailwind leest JSON.
• Componenten praten dezelfde taal.
• Reviews gaan over functionaliteit, niet over "is dit de juiste blauw?".

Dat is het systeem. Klein, voorspelbaar, onderhoudbaar.

Wil je weten of je huidige frontend-setup klaar is voor deze aanpak? Wij doen een gratis Tech Check: we kijken naar je Tailwind-config, je Figma-workflow en je build-pipeline, en geven concrete aanbevelingen. Neem contact op via /contact — geen verkoopgesprek, geen rapport van dertig pagina's.