Tailwind in Hyvä: design tokens en de build-pipeline

Luma-thema's worden gestyled met LESS-bestanden, variabelen en een lange keten van overrides. Hyvä vervangt dat door Tailwind CSS, een utility-first framework waarbij de styling als classes direct in de markup van de template staat.

Die verandering verwart sommige teams in het begin. Als elk element zijn eigen classes heeft, waar leeft het merk dan? Het antwoord: design tokens, en een build-pipeline die er een kleine stylesheet van maakt. Dit artikel legt beide uit, op basis van hoe we onze eigen Hyvä-webshops opzetten.

Wat een design token is

Een design token is een benoemde waarde die het hele thema deelt. In plaats van een hexkleur in twintig templates te schrijven, definieer je primary één keer en gebruik je overal classes zoals bg-primary en text-primary .

Gebruikelijke tokengroepen in een Hyvä-thema zijn:

• Kleuren: primair, secundair, achtergrond, tekst, randen, sale- en voorraadstatussen.
• Typografie: lettertypefamilies, -groottes en -gewichten voor koppen en broodtekst.
• Witruimte en afmetingen: de schaal voor padding, marges en containerbreedtes.
• Breakpoints: de schermbreedtes waarop de layout verandert.
• Radii en schaduwen: de kleine details waardoor een design consistent aanvoelt.

Verandert een merkkleur, dan pas je één token aan en build je opnieuw. Elke knop, link en badge volgt vanzelf.

Waar tokens staan in Hyvä

Het standaardthema van Hyvä definieert al een set tokens in de Tailwind-configuratie. Je childthema kopieert de map web/tailwind en breidt die waarden uit, zoals beschreven in onze gids voor Hyvä-childthema's.

Een eenvoudige uitbreiding van de kleurtokens ziet er zo uit:

theme: {
    extend: {
        colors: {
            primary: {
                lighter: 'var(--color-primary-lighter)',
                DEFAULT: 'var(--color-primary)',
                darker: 'var(--color-primary-darker)'
            }
        }
    }
}

Een token naar een CSS custom property laten wijzen, zoals hierboven, is een handig patroon. De classnaam blijft gelijk, maar de werkelijke kleur kan elders worden ingesteld, bijvoorbeeld per store view of vanuit de beheeromgeving.

De exacte bestandsindeling hangt af van je Hyvä-versie, omdat nieuwere Tailwind-versies meer van de configuratie naar CSS verplaatsen. Het principe blijft hetzelfde: definieer tokens één keer, gebruik ze overal.

Het team kleuren laten aanpassen zonder code

In onze webshops maken we header- en merkkleuren beschikbaar in Stores > Configuration. Een marketingteam kan een kleur in de beheeromgeving aanpassen zonder een ticket aan te maken.

Achter die instelling worden de Tailwind-tokens bij de deploy opnieuw opgebouwd uit de configuratie- en themabestanden. De beheeromgeving bevat de waarden, de tokens bevatten de namen, en de build verbindt ze.

We beperken dit bewust tot een handvol waarden. Een kleurkiezer voor elk element maakt van een strak design al snel een lappendeken, dus de beheeromgeving biedt de merkkeuzes en het thema houdt al het andere consistent. Meer details lees je in ons artikel over kleuren van een Hyvä-thema aanpassen vanuit de beheeromgeving.

Hoe de build-pipeline werkt

Tailwind stuurt niet elke mogelijke utility class naar de browser. Tijdens de build scant het je templates, zoekt de classes die je gebruikt en schrijft alleen die in de uiteindelijke stylesheet.

Voor een Hyvä-webshop moet de build elke plek zien waar een class vandaan kan komen:

1. Templates in je childthema.
2. Templates die nog uit het standaardthema van Hyvä in de vendor-map komen.
3. Templates en Tailwind-bronnen van Hyvä-compatibele modules.
4. Alle classes die vanuit PHP, CMS-content of de beheeromgeving worden ingesteld.

Hyvä regelt het derde punt met het commando bin/magento hyva:config:generate. Dat schrijft een lijst weg van de geïnstalleerde Hyvä-compatibele modules en hun paden, en de Tailwind-build leest die lijst.

Het vierde punt vraagt om zorg. Tailwind kan geen classnaam zien die alleen in de database bestaat. Typen redacteuren classnamen in CMS-blokken, dan moet je die classes expliciet in de configuratie opnemen zodat de build ze behoudt. Anders zien ze er in development goed uit en gaan ze in productie stuk.

Onze deployvolgorde

We behandelen de gecompileerde stylesheet als build-artefact, nooit als bestand dat iemand bewerkt of commit. Onze stack draait Magento 2.4.9 in production mode met static content deploy, en de deploy loopt in een vaste volgorde.

bin/magento hyva:config:generate
npm --prefix app/design/frontend/Vendor/default/web/tailwind ci
npm --prefix app/design/frontend/Vendor/default/web/tailwind run build-prod
bin/magento setup:static-content:deploy -f en_GB de_DE
bin/magento cache:flush

Controleer in je thema de naam van het buildscript in package.json, want die verschilt per Hyvä-versie. Met npm ci in plaats van npm install krijg je bij elke deploy de exacte packageversies uit het lockbestand.

Na de deploy legen we de CDN-cache voor de stylesheet, zodat bezoekers geen nieuwe HTML met oude CSS krijgen.

Waarom dit pagina's licht houdt

In onze benchmark op dezelfde server en catalogus wogen schone Hyvä-pagina's 195 tot 226 KB, tegenover 756 tot 962 KB voor dezelfde pagina's op Luma. Een groot deel van het verschil is JavaScript, maar CSS speelt ook een rol.

Een Luma-stylesheet bevat stijlen voor elke widget die het thema zou kunnen tonen. Een Tailwind-build bevat de classes die je templates gebruiken en verder heel weinig. De volledige cijfers staan in onze Hyvä vs Luma-benchmark.

De build blijft alleen slank als je gedisciplineerd blijft. Een paar gewoontes helpen:

• Gebruik tokens in plaats van willekeurige waarden, zoals eenmalige pixelbreedtes.
• Bouw geen classnamen op uit strings in PHP of JavaScript, want Tailwind kan die niet detecteren.
• Verwijder oude componenten als je ze vervangt, zodat hun classes ook uit de build verdwijnen.
• Houd eigen CSS-bestanden klein, en gebruik ze alleen voor wat Tailwind niet goed kan uitdrukken.

Veelvoorkomende problemen en hun oorzaken

Veelgestelde vragen

Moeten designers Tailwind leren?

Niet diepgaand. Designers moeten een duidelijke set kleuren, tekstgroottes en witruimtewaarden aanleveren, en developers maken daar tokens van. Die gedeelde lijst is vaak het nuttigste resultaat van de hele designfase.

Kunnen we in Hyvä nog gewone CSS schrijven?

Ja. Hyvä-thema's kunnen eigen CSS bevatten, en Tailwind ondersteunt component classes voor terugkerende patronen. We houden eigen CSS tot een minimum, zodat de meeste styling zichtbaar blijft in de templates.

Vertraagt het opnieuw bouwen van de CSS bij elke deploy de deploys?

De Tailwind-build is een kleine stap vergeleken met de static content deployment. Hij voegt een korte, voorspelbare fase toe aan de pipeline, en neemt een hele categorie bugs door niet-synchrone bestanden weg.

Wil je een Hyvä-thema dat je team veilig kan aanpassen? Lees meer over onze aanpak op de pagina over Hyvä-thema-ontwikkeling, of vraag een Magento 2-audit aan van je huidige frontend.