Tailwind CSS 4 @theme, @layer & @utility in Hyvä Theme erklärt | Mironsoft Blog

Fünf Direktiven, die du kennen musst

Wer mit dem Hyvä Theme und Tailwind CSS 4 in Magento 2 Projekten arbeitet, stößt schnell auf Begriffe wie @theme, @layer components, @utility, :root und @keyframes. Auf den ersten Blick wirken sie ähnlich – alle befassen sich mit CSS-Definitionen. Doch ihre Funktionen unterscheiden sich grundlegend, und wer sie verwechselt, stellt fest: Klassen fehlen im kompilierten Stylesheet, CSS-Variablen sind im Browser nicht verfügbar, Hintergründe erscheinen nicht, und der PageBuilder verhält sich anders als erwartet.

Dieser Blogbeitrag erklärt alle fünf Konzepte verständlich und praxisnah. Du lernst, was jede Direktive bewirkt, wann du welche einsetzen sollst und welche typischen Fehler bei der Arbeit mit Tailwind CSS 4 im Hyvä Theme entstehen. Die Beispiele stammen direkt aus der realen Entwicklungspraxis.

Tailwind CSS 4 hat den Ansatz der Framework-Konfiguration grundlegend neu gedacht. Es gibt keine JavaScript-Konfigurationsdatei mehr. Alles läuft über CSS. Das ist elegant – aber nur dann, wenn man versteht, welche CSS-Direktive welche Aufgabe übernimmt. Genau das erklären wir jetzt.

1. Der CSS-First-Ansatz von Tailwind CSS 4

Tailwind CSS existiert seit Version 1 nach einem einfachen Prinzip: Anstatt eigene CSS-Klassen zu schreiben, kombiniert man kleine, vorgefertigte Utility-Klassen direkt im HTML-Markup. Eine Zeile wie class="flex items-center gap-4 bg-white text-slate-900 rounded-lg p-4" genügt, um ein vollständig gestaltetes Element zu erzeugen. Kein separates CSS-File, kein Namensgebungsproblem, keine Spezifitätskonflikte.

In Tailwind CSS 3 wurde das Framework noch über eine JavaScript-Datei konfiguriert. Eigene Farben, Schriftgrößen und Abstände wurden in der tailwind.config.js unter theme.extend eingetragen. Der Build-Prozess las diese Konfiguration und transformierte sie in CSS-Ausgabe.

Tailwind CSS 4 bricht mit dieser Konvention vollständig. Die neue Version nutzt ausschließlich CSS als Konfigurationsquelle – daher der Begriff CSS-First-Ansatz. Es gibt keine tailwind.config.js mehr. Alles landet in der zentralen CSS-Eintrittsdatei. Im Hyvä Theme ist das die Datei tailwind-source.css im Verzeichnis web/tailwind/ des Themes.

Diese Datei ist der einzige Ort, an dem das gesamte Tailwind CSS 4 Framework konfiguriert wird: Design-Tokens wie Farben, Typografie und Abstände, eigene Animations-Definitionen, Komponentenstile für wiederkehrende UI-Elemente und explizite Safelists für Klassen, die aus Datenbankinhalten stammen und nicht automatisch gescannt werden können.

Jede dieser Direktiven hat eine klar definierte, exklusive Aufgabe. Tailwind CSS 4 kompiliert nur das, was semantisch korrekt platziert ist. CSS-Klassen im falschen Block werden mit einem Build-Fehler quittiert. CSS-Variablen an der falschen Stelle sind im Browser schlicht nicht vorhanden. Das ist die Stärke von Tailwind CSS 4: Klarheit durch Struktur. Aber diese Struktur muss man verstehen.

2. @theme – Das Herzstück von Tailwind CSS 4

Der @theme-Block ist das zentrale neue Konzept in Tailwind CSS 4. Er ersetzt die theme.extend-Konfiguration aus der tailwind.config.js vollständig und ist konzeptionell auf zwei Dinge beschränkt: CSS Custom Properties mit erkannten Namespaces und @keyframes-Definitionen. Nichts anderes hat im @theme-Block etwas verloren.

Erkannte Namespaces und automatische Utility-Generierung

Der entscheidende Mechanismus von @theme ist die automatische Utility-Klassen-Generierung aus CSS Custom Properties. Tailwind CSS 4 kennt eine festgelegte Liste von CSS-Property-Präfixen – sogenannte Namespaces –, aus denen es automatisch Utility-Klassen erstellt.

Das bekannteste Beispiel ist der --color-*-Namespace. Wenn du --color-brand-red: #991B1B; in @theme definierst, generiert Tailwind CSS 4 sofort eine komplette Palette: bg-brand-red, text-brand-red, border-brand-red, ring-brand-red, from-brand-red, via-brand-red, to-brand-red und weitere. Eine einzige Property – Dutzende Klassen.

Die wichtigsten erkannten Namespaces:

• --color-* – Generiert alle Farb-Utilities (bg-, text-, border-, ring-, from-, via-, to-)
• --font-* – Generiert Font-Family-Utilities
• --text-* – Generiert Font-Size-Utilities (text-sm, text-2xl usw.)
• --breakpoint-* – Definiert responsive Breakpoints (sm, md, lg, xl, 2xl)
• --spacing-* – Generiert Abstands-Utilities für Margin, Padding, Gap
• --radius-* – Generiert Border-Radius-Utilities
• --animate-* – Generiert Animation-Utilities (animate-fade-up, animate-float usw.)

Was @theme NICHT kann: Dead-Code-Elimination

Hier liegt eine der häufigsten Fehlerquellen. Was passiert mit CSS Custom Properties ohne erkannten Namespace? Angenommen, du definierst --grad-header: linear-gradient(...); in @theme. Der Namespace --grad-* ist kein erkannter Tailwind CSS 4 Namespace. Das Framework generiert daraus keine Utility-Klassen. Und Tailwind CSS 4 wendet Dead-Code-Elimination an: Wenn diese Variable nirgendwo in der CSS-Datei referenziert wird, wird sie beim Build vollständig entfernt.

Das Ergebnis: Du schreibst style="background:var(--grad-header);", aber der Browser kann die Variable nicht auflösen, weil sie im kompilierten Stylesheet fehlt. Die Lösung: Solche Properties gehören nicht in @theme, sondern in :root.

Ein weiterer häufiger Fehler: CSS-Selektoren in @theme platzieren. Wer .scrollbar { width: 6px; } innerhalb von @theme schreibt, bekommt einen expliziten Build-Fehler: „Error: @theme blocks must only contain custom properties or @keyframes."

3. @keyframes – Animationen in Tailwind CSS 4 definieren

@keyframes ist in Tailwind CSS 4 auf zwei Arten verwendbar: direkt innerhalb des @theme-Blocks oder außerhalb in einem regulären CSS-Bereich. Beide Varianten sind gültig.

@keyframes innerhalb von @theme

Wenn du eine Animation über den --animate-*-Namespace in @theme definierst, gehört die zugehörige @keyframes-Definition idealerweise direkt in denselben @theme-Block. Die Property --animate-fade-up und die Keyframes fadeUp stehen dann beieinander. Das ist kein technisches Muss – es ist eine Frage der Organisation und Lesbarkeit.

@keyframes außerhalb von @theme

Manchmal braucht man Keyframe-Animationen für Klassen, die nicht über den --animate-*-Namespace gesteuert werden – zum Beispiel für Animationen in @layer components-Klassen. In diesem Fall definiert man @keyframes außerhalb von @theme direkt in der CSS-Datei. Das ist normales CSS und wird unverändert in das kompilierte Stylesheet übernommen.

4. :root – CSS Custom Properties global verfügbar machen

Im Gegensatz zu @theme ist :root kein Tailwind-spezifisches Konzept. Es ist ein gewöhnlicher CSS-Selektor, der das <html>-Element anspricht. CSS Custom Properties in :root sind auf der gesamten Seite verfügbar und können in jedem Selektor mit var(--property-name) abgerufen werden.

Warum :root in Tailwind CSS 4 wichtig ist

Wegen der Dead-Code-Elimination in @theme spielt :root eine wichtige Ergänzungsrolle. Immer dann, wenn man CSS Custom Properties benötigt, die Tailwind CSS 4 nicht als Utility-Namespace erkennt, ist :root die richtige Wahl. Typische Kandidaten:

• Gradient-Definitionen wie --grad-header, --grad-footer
• Muster-Definitionen wie --grid-pattern für komplexe repeating-linear-gradient-Werte
• Komponentenspezifische Variablen wie --card-border-color
• Alle Variablen, die in HTML style=""-Attributen (z.B. im PageBuilder) referenziert werden

Die Merkregel für den Alltag

@theme für alles, woraus Tailwind CSS 4 Utility-Klassen generieren soll. :root für alle anderen CSS Custom Properties, die im Browser direkt verfügbar sein müssen. Tailwind CSS 4 schreibt alle durch @theme generierten Properties intern ebenfalls in einen :root, :host { ... }-Block – aber nur für die, die einen erkannten Namespace haben. Eigene :root-Blöcke werden vollständig und unverändert ins Output-CSS übernommen.

5. @utility – Eigene Utility-Klassen in Tailwind CSS 4

@utility ist eine neue Direktive in Tailwind CSS 4, die es ermöglicht, eigene Utility-Klassen zu definieren, die sich vollständig wie Tailwind's eingebaute Utilities verhalten: volle Unterstützung für Modifier wie hover:, focus:, lg:, dark: und alle weiteren responsiven und zustandsabhängigen Präfixe.

@utility vs. @layer components

Eine Utility-Klasse macht genau eine Sache – sie setzt eine einzelne CSS-Property oder eine eng verwandte Gruppe. Eine Komponentenklasse kann viele Properties, Pseudo-Elemente und komplexe Selektor-Kombinationen enthalten. Verwende @utility für:

• Benutzerdefinierte Hintergrundverläufe als Klasse (bg-grad-header)
• Benutzerdefinierte Muster-Hintergründe (bg-grid-pattern, bg-dot-pattern)
• Klassen, die du mit hover: oder lg: kombinieren willst
• Einzelne Property-Erweiterungen, die nicht über den @theme-Namespace generiert werden

@utility und der Hyvä PageBuilder JIT-Compiler

Das Modul Hyva_CmsTailwindJit kompiliert Tailwind CSS im Browser, wenn CMS-Seiten im Admin gespeichert werden. Der Browser-JIT-Compiler nutzt eine separate Konfigurationsdatei (tailwind.browser-jit-config.js) im Tailwind v3 Format. Um eigene Gradient-Klassen wie bg-grad-header im PageBuilder zu nutzen, müssen sie auch dort eingetragen sein.

6. @layer components – Komponentenstile strukturieren

@layer components ist das Werkzeug für komplexe, wiederverwendbare CSS-Klassen, die über die Grenzen einer einzelnen Property hinausgehen. Es handelt sich um einen der drei Standard-Layer von Tailwind CSS 4: base, components und utilities.

Diese Reihenfolge definiert die Kaskaden-Priorität. Stile in @layer base haben die niedrigste Priorität, Stile in @layer utilities die höchste. Ein Tailwind-Utility wie bg-brand-red im HTML überschreibt immer einen background-color-Wert aus einer @layer components-Klasse. Das ist gewollt.

Was gehört in @layer components?

@layer components und PageBuilder

Klassen aus @layer components stehen im globalen styles.css des Hyvä Theme zur Verfügung. Im PageBuilder ist die Situation komplexer: Der Hyva_CmsTailwindJit-Compiler kennt nur Tailwind-Utilities – keine benutzerdefinierten CSS-Klassen aus @layer components. Für PageBuilder-Inhalte empfehlen sich deshalb reine Tailwind-Utilities oder als @utility definierte Klassen.

7. Die Entscheidungsmatrix: Was kommt wohin?

Nach allem, was wir besprochen haben, lässt sich die Entscheidung in einer klaren Matrix zusammenfassen. Diese Matrix ist das wichtigste praktische Werkzeug für die tägliche Hyvä Theme Entwicklung.

Die Faustregel in drei Fragen

1. Soll Tailwind CSS 4 daraus automatisch Utility-Klassen generieren? → @theme (mit erkanntem Namespace wie --color-*, --animate-*).
2. Handelt es sich um eine einzelne Property ohne Pseudo-Element oder :hover-Selektor? → @utility (ermöglicht Modifier wie hover:, lg:, dark:).
3. Braucht die Klasse Pseudo-Elemente oder mehrere Selektoren? → @layer components.
4. Brauche ich eine Custom Property, die im Browser verfügbar sein muss, aber nicht durch Tailwind generiert werden soll? → :root.

8. Hyvä Theme: Besonderheiten bei Tailwind CSS 4 in Magento 2

Das Hyvä Theme für Magento 2 ist das erste prominente E-Commerce-Theme, das vollständig auf Tailwind CSS 4 und Alpine.js setzt. Es verzichtet bewusst auf Knockout.js, jQuery und die klassischen Magento-UI-Komponenten. Das Ergebnis sind regelmäßig Lighthouse-Werte über 95.

Build-Time CSS vs. Browser-JIT CSS

Das Hyvä Theme unterscheidet grundlegend zwischen zwei CSS-Kompilierungswegen. Das Build-Time-CSS – also das kompilierte styles.css – enthält alle Tailwind CSS 4 Klassen, die beim Build-Prozess aus gescannten .phtml- und .xml-Dateien gefunden wurden. Klassen, die nur in Magento-Datenbankinhalten vorkommen – CMS-Seiten, PageBuilder-Blöcke – sind darin nicht enthalten.

Hier kommt das Modul Hyva_CmsTailwindJit ins Spiel. Es kompiliert Tailwind CSS 3 direkt im Browser, wenn CMS-Seiten im Magento-Admin gespeichert werden. Der sogenannte Browser-JIT-Compiler liest eine separate Konfigurationsdatei – tailwind.browser-jit-config.js – im alten Tailwind v3 JavaScript-Format, da der Browser kein Node.js ausführen kann.

@source inline() – Der Safelist-Mechanismus

Tailwind CSS 4 kompiliert standardmäßig nur Klassen, die in den gescannten Quelldateien gefunden werden. Für Klassen, die nur dynamisch gesetzt werden – über JavaScript, Alpine.js-Bindings oder PageBuilder-Inhalte – bietet Tailwind CSS 4 den @source inline()-Mechanismus an.

9. Typische Fehler bei Tailwind CSS 4 im Hyvä Theme

Fehler 1: CSS-Klassen in @theme platzieren

Der häufigste Fehler beim Umstieg von Tailwind CSS 3. In Tailwind CSS 4 führen CSS-Selektoren innerhalb von @theme zu einem expliziten Build-Fehler: „@theme blocks must only contain custom properties or @keyframes." Lösung: Alle CSS-Selektoren aus @theme entfernen und in @layer components oder als @utility definieren.

Fehler 2: Gradient-Variablen in @theme statt :root

--grad-header wird in @theme definiert und in HTML-style=""-Attributen referenziert. Die Dead-Code-Elimination entfernt sie, weil kein CSS-Selektor auf sie verweist. Im Browser ist die Variable nicht verfügbar. Lösung: Solche Variablen in :root { ... } außerhalb von @theme definieren.

Fehler 3: @keyframes ohne zugehörige --animate-* Property

Eine @keyframes fadeUp { ... }-Definition ist vorhanden, aber die Property --animate-fade-up: fadeUp 0.6s ease-out forwards; in @theme fehlt. Resultat: Keine automatisch generierte .animate-fade-up-Klasse im kompilierten CSS. Lösung: Immer --animate-*-Property und @keyframes zusammen definieren – idealerweise im selben @theme-Block.

Fehler 4: @source inline() Safelist vergessen

Neue Markenfarben oder Animation-Utilities werden in @theme definiert, tauchen dann aber im PageBuilder-HTML auf – und werden deshalb nicht gescannt. Das kompilierte styles.css enthält die Klassen nicht. Lösung: Alle Klassen, die im PageBuilder oder über JavaScript dynamisch verwendet werden, explizit über @source inline() in die Safelist aufnehmen.

Fehler 5: JIT-Config nicht synchronisiert

Neue Utilities werden in tailwind-source.css ergänzt, aber nicht in der tailwind.browser-jit-config.js. Auf regulären Template-Seiten funktioniert alles. Im PageBuilder fehlt das CSS. Lösung: Beide Dateien immer synchron halten und nach Änderungen sowohl npm run build ausführen als auch die betroffenen CMS-Seiten im Admin neu speichern.

10. Praktische Empfehlungen für Hyvä Theme Entwicklung

Klare Struktur in tailwind-source.css

Empfohlene Reihenfolge: Imports und @source-Direktiven, gefolgt von @source inline()-Safelists, dann der vollständige @theme-Block, dann :root-Block für globale Custom Properties, dann @utility-Definitionen, schließlich @layer components für komplexe Komponentenklassen.

Design-Tokens konsequent in @theme halten

Alle Markenfarben, Schriftskalen, Abstands-Tokens und Breakpoints gehören in @theme. Das gibt Tailwind CSS 4 die Möglichkeit, daraus ein vollständiges Utility-System zu generieren. Wer einen Farbwert direkt in eine @layer components-Klasse hardcoded, verliert die Vorteile der systematischen Utility-Generierung.

PageBuilder-kompatible Klassen bevorzugen

Für Hyvä-Projekte mit aktivem CMS-Editing gilt: Lieber mehr Tailwind-Standard-Utilities kombinieren als eigene Komponentenklassen in @layer components, die der Browser-JIT nicht kennt. bg-grid-pattern animate-grid-flow statt grid-bg. Das führt zu längerem HTML, aber besserem Verhalten im PageBuilder.

Nach CSS-Änderungen immer neu bauen

Nach jeder Änderung an tailwind-source.css muss das Stylesheet neu gebaut werden (npm run build). Nach jeder Änderung an tailwind.browser-jit-config.js müssen alle betroffenen CMS-Seiten im Magento-Admin neu gespeichert werden. Beide Schritte werden im Tagesgeschäft gerne vergessen.

11. Zusammenfassung

Tailwind CSS 4 und das Hyvä Theme sind ein leistungsstarkes Gespann für die Magento 2 Frontend-Entwicklung. Der CSS-First-Ansatz mit @theme, :root, @utility und @layer components bietet klare Strukturierungsmöglichkeiten – aber nur dann, wenn man die Verantwortlichkeiten der einzelnen Direktiven versteht.

12. FAQ: Tailwind CSS 4 im Hyvä Theme