De token- en configuratielaag bouwen

De tokenlaag vormt de verbinding tussen je ontwerpbeslissingen en het genereren van Tailwind-hulpprogrammaklassen. De laag bestaat uit CSS-aangepaste eigenschappen (designtokens op CSS-niveau) en de Tailwind-configuratie die naar deze eigenschappen verwijst. Als je dit correct implementeert, hoef je voor het wisselen van thema alleen de waarden van de CSS-variabelen te wijzigen — Tailwind-klassen en componentcode blijven ongewijzigd.

Begin met het definiëren van alle onbewerkte kleur-, spatiërings- en typografiewaarden in een bestand tokens/primitives.css, met behulp van CSS-aangepaste eigenschappen. Componenten gebruiken deze primitieve waarden niet rechtstreeks — ze dienen alleen als invoer voor de laag met semantische tokens. Gebruik een gestructureerde naamgevingsconventie, zoals --color-blue-500 voor kleuren en --space-4 voor spatiëringswaarden.

Semantische tokens geven betekenis aan primitieve waarden. Definieer ze in een afzonderlijk bestand tokens/semantic.css. Elke semantische token verwijst naar een primitieve token en vertegenwoordigt een doel in plaats van een waarde. Je overschrijft dezelfde semantische token binnen een donkere scope of een andere merkscope om van thema te wisselen.

Overschrijf semantische tokens onder de klasse .dark (voor de klassenstrategie) of onder @media (prefers-color-scheme: dark) (voor de mediastrategie). Alleen semantische tokens veranderen — primitieve definities blijven ongewijzigd. Dat is de kracht van het systeem met twee niveaus: de donkere modus wordt volledig in de tokenlaag geïmplementeerd, zonder wijzigingen aan CSS van componenten of Tailwind-klassen.

Verwijs vanuit de thema-uitbreiding van de Tailwind-configuratie naar CSS-aangepaste eigenschappen. Gebruik var(--token-name) als waarde. Dit betekent dat elk Tailwind-hulpprogramma dat naar de thematoken verwijst, tijdens runtime de CSS-variabele gebruikt, zodat je live van thema kunt wisselen zonder opnieuw te compileren. De JIT-engine genereert in de uitvoer-CSS klassen met var()-waarden.

Nu de tokens aan de configuratie zijn gekoppeld, gebruik je ze net als elke andere Tailwind-kleur. bg-surface past de CSS-variabele --color-surface toe als achtergrond. Wanneer de gebruiker naar de donkere modus overschakelt, verandert de waarde van de CSS-variabele en wordt de achtergrond automatisch bijgewerkt, zonder wijzigingen aan componenten. Klassen op basis van tokens zien er in de markup hetzelfde uit als ingebouwde Tailwind-klassen.

Definieer lettertypefamilie, lettergrootte, regelhoogte en letterdikte als tokens. Lettertypefamilies moeten naar een CSS-variabele verwijzen, zodat je voor het wisselen van merklettertypen alleen een variabele hoeft te wijzigen. Je kunt lettergroottes in de Tailwind-configuratie uitbreiden met semantische namen zoals text-display en text-caption, naast de standaard numerieke schaal.

Breid de schalen voor spatiëring en randafronding uit met semantische namen voor constanten op componentniveau. In plaats van te onthouden dat kaarten rounded-xl en badges rounded-full gebruiken, definieer je radius.card: xl en radius.badge: full in de configuratie. Zo documenteert componentcode zichzelf en gebruiken alle kaarten dezelfde afronding, ook wanneer de waarde verandert.

Definieer consistente schaduwniveaus in de Tailwind-configuratie met semantische namen. Schaduwen geven de visuele hiërarchie aan: none voor vlakke elementen, card voor oppervlakelementen, elevated voor vervolgkeuzelijsten en modals, en focus voor indicatoren van interactieve toestanden. Zo voorkom je dat willekeurige schaduwwaarden verspreid door de codebasis staan.

Voeg een CI-stap toe die de integriteit van tokens valideert — controleer of elke semantische token verwijst naar een bestaande primitieve token en of geen semantische token een onbewerkte hexwaarde is (waarmee je het systeem met twee niveaus zou omzeilen). Een eenvoudig Node.js-script dat het CSS-variabelenbestand parseert en verwijzingen controleert, kan verschuivingen in tokens onderscheppen voordat die productie bereiken.

Test de donkere modus visueel op tokenniveau door de klasse .dark op html te zetten en te controleren of elk semantisch kleurvlak, elke tekst en elke rand correct wordt weergegeven. Gebruik Playwright of Cypress om schermafbeeldingen te maken met dark toegepast en vergelijk die met baselines voor de lichte modus. Voer deze testsuite uit telkens wanneer het tokenbestand verandert, zodat je visuele regressies direct ontdekt.

In deze les heb je geleerd hoe je: primitieve en semantische tokens als CSS-aangepaste eigenschappen definieert in afzonderlijke bestanden, semantische tokens aan de Tailwind-configuratie koppelt met var(), zodat ze tijdens runtime worden bijgewerkt, en de donkere modus implementeert door alleen semantische tokens onder de klasse .dark te overschrijven. Hierna bouwen we met deze tokens de componentbibliotheek.