Tailwind in Hyvä: Design-Tokens und die Build-Pipeline

Luma-Themes werden mit LESS-Dateien, Variablen und einer langen Kette von Overrides gestaltet. Hyvä ersetzt das durch Tailwind CSS, ein Utility-first-Framework, bei dem das Styling als Klassen direkt im Template-Markup steht.

Diese Umstellung verwirrt manche Teams anfangs. Wenn jedes Element seine eigenen Klassen trägt – wo lebt dann die Marke? Die Antwort: in Design-Tokens und einer Build-Pipeline, die daraus ein kleines Stylesheet macht. Dieser Beitrag erklärt beides am Beispiel unserer eigenen Hyvä-Shops.

Was ein Design-Token ist

Ein Design-Token ist ein benannter Wert, den das gesamte Theme teilt. Statt einen Hex-Farbwert in zwanzig Templates zu schreiben, definieren Sie primary einmal und verwenden Klassen wie bg-primary und text-primary überall.

Typische Token-Gruppen in einem Hyvä-Theme sind:

• Farben: Primär-, Sekundär-, Hintergrund-, Text- und Rahmenfarben sowie Sale- und Lagerstatus.
• Typografie: Schriftfamilien, -größen und -stärken für Überschriften und Fließtext.
• Abstände und Größen: die Skala für Padding, Margins und Container-Breiten.
• Breakpoints: die Bildschirmbreiten, bei denen sich das Layout ändert.
• Radien und Schatten: die kleinen Details, die ein Design stimmig wirken lassen.

Ändert sich eine Markenfarbe, ändern Sie ein Token und bauen neu. Jeder Button, jeder Link und jedes Badge zieht mit.

Wo Tokens in Hyvä liegen

Das Standard-Theme von Hyvä definiert in seiner Tailwind-Konfiguration bereits eine Reihe von Tokens. Ihr Child-Theme kopiert den web/tailwind Ordner und erweitert diese Werte – mehr dazu in unserem Leitfaden zum Hyvä-Child-Theme.

Eine einfache Erweiterung der Farb-Tokens sieht so aus:

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

Ein Token wie oben auf eine CSS Custom Property zeigen zu lassen, ist ein nützliches Muster. Der Klassenname bleibt gleich, die tatsächliche Farbe lässt sich aber an anderer Stelle festlegen, etwa pro Store View oder im Admin.

Der genaue Dateiaufbau hängt von Ihrer Hyvä-Version ab, da neuere Tailwind-Versionen mehr Konfiguration ins CSS verlagern. Das Prinzip bleibt gleich: Tokens einmal definieren, überall verwenden.

Farben ohne Code durch das Team ändern lassen

In unseren Shops stellen wir Header- und Markenfarben unter Stores > Configuration bereit. Ein Marketingteam kann eine Farbe im Admin ändern, ohne ein Ticket zu eröffnen.

Hinter dieser Einstellung werden die Tailwind-Tokens beim Deployment aus Konfiguration und Theme-Dateien neu gebaut. Der Admin hält die Werte, die Tokens die Namen, und der Build verbindet beides.

Wir beschränken das bewusst auf eine Handvoll Werte. Ein Farbwähler für jedes Element macht aus einem sauberen Design schnell einen Flickenteppich – deshalb bietet der Admin die Markenentscheidungen, und das Theme hält alles andere einheitlich. Mehr Details dazu in unserem Beitrag über das Ändern von Hyvä-Theme-Farben im Admin.

So funktioniert die Build-Pipeline

Tailwind liefert nicht jede mögliche Utility-Klasse an den Browser aus. Beim Build scannt es Ihre Templates, findet die verwendeten Klassen und schreibt nur diese ins finale Stylesheet.

Bei einem Hyvä-Shop muss der Build jede Stelle sehen, aus der eine Klasse stammen kann:

1. Templates in Ihrem Child-Theme.
2. Templates, die weiterhin aus dem Hyvä-Standard-Theme im vendor-Ordner ausgeliefert werden.
3. Templates und Tailwind-Quellen aus Hyvä-kompatiblen Modulen.
4. Alle Klassen, die per PHP, CMS-Inhalt oder im Admin gesetzt werden.

Den dritten Punkt löst Hyvä mit dem Befehl bin/magento hyva:config:generate. Er schreibt eine Liste der installierten Hyvä-kompatiblen Module und ihrer Pfade, und der Tailwind-Build liest diese Liste ein.

Der vierte Punkt erfordert Sorgfalt. Tailwind sieht keinen Klassennamen, der nur in der Datenbank existiert. Wenn Redakteure Klassennamen in CMS-Blöcke eintragen, müssen Sie diese Klassen explizit in der Konfiguration auflisten, damit der Build sie behält – sonst sehen sie in der Entwicklung gut aus und brechen in Produktion.

Unsere Deployment-Reihenfolge

Wir behandeln das kompilierte Stylesheet als Build-Artefakt, nie als Datei, die jemand bearbeitet oder committet. Unser Stack betreibt Magento 2.4.9 im Production-Modus mit Static Content Deploy, und das Deployment läuft in einer festen Reihenfolge.

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

Prüfen Sie den Namen des Build-Skripts in Ihrem Theme in der Datei package.json, da er sich zwischen Hyvä-Versionen unterscheidet. Mit npm ci statt npm install erhalten Sie bei jedem Deployment exakt die Paketversionen aus der Lock-Datei.

Nach dem Deployment leeren wir den CDN-Cache für das Stylesheet, damit Besucher kein neues HTML mit altem CSS erhalten.

Warum das die Seiten leicht hält

In unserem Benchmark auf demselben Server mit demselben Katalog wogen saubere Hyvä-Seiten 195 bis 226 KB, gegenüber 756 bis 962 KB für dieselben Seiten auf Luma. Ein Großteil des Unterschieds ist JavaScript, doch auch CSS spielt eine Rolle.

Ein Luma-Stylesheet enthält Styles für jedes Widget, das das Theme anzeigen könnte. Ein Tailwind-Build enthält die Klassen, die Ihre Templates nutzen, und kaum etwas anderes. Die vollständigen Zahlen finden Sie in unserem Hyvä-vs.-Luma-Benchmark.

Der Build bleibt nur schlank, wenn Sie diszipliniert bleiben. Ein paar Gewohnheiten helfen:

• Verwenden Sie Tokens statt beliebiger Werte wie einmaliger Pixelbreiten.
• Setzen Sie Klassennamen nicht in PHP oder JavaScript aus Strings zusammen, denn Tailwind kann sie nicht erkennen.
• Entfernen Sie alte Komponenten, wenn Sie sie ersetzen, damit auch ihre Klassen aus dem Build verschwinden.
• Halten Sie eigene CSS-Dateien klein und nutzen Sie sie nur für das, was Tailwind nicht gut ausdrücken kann.

Häufige Probleme und ihre Ursachen

FAQ

Müssen Designer Tailwind lernen?

Nicht im Detail. Designer sollten einen klaren Satz an Farben, Schriftgrößen und Abständen liefern, und Entwickler machen daraus Tokens. Diese gemeinsame Liste ist oft das nützlichste Ergebnis der gesamten Designphase.

Können wir in Hyvä weiterhin normales CSS schreiben?

Ja. Hyvä-Themes können eigenes CSS enthalten, und Tailwind unterstützt Komponentenklassen für wiederkehrende Muster. Wir halten eigenes CSS minimal, damit der Großteil des Stylings in den Templates sichtbar bleibt.

Verlangsamt der CSS-Build bei jedem Deployment die Deployments?

Der Tailwind-Build ist ein kleiner Schritt im Vergleich zum Static Content Deploy. Er fügt der Pipeline eine kurze, planbare Stufe hinzu und beseitigt eine ganze Klasse von Fehlern durch nicht synchrone Dateien.

Sie möchten ein Hyvä-Theme, das Ihr Team sicher anpassen kann? Mehr über unseren Ansatz lesen Sie auf der Seite Seite zur Hyvä-Theme-Entwicklung, oder fordern Sie einen Magento-Audit Ihres aktuellen Frontends an.