Hyvä Tailwind-Config anpassen: Theme-Werte, Plugins, Purge-Pfade

1. Warum eine eigene Hyvä Tailwind-Config nötig ist

Jedes Hyvä-Theme bringt im Parent-Theme eine fertige tailwind.config.js mit, die Basiswerte für Farben, Schrift und Spacing definiert und die wichtigsten content-Pfade für den Storefront bereits enthält. Für ein produktives Projekt reicht diese Vorgabe aber selten aus: Sobald ein Kunde eigene Markenfarben, eine individuelle Schriftfamilie oder ein abweichendes Spacing-System aus dem Design-System mitbringt, braucht das Child-Theme eine eigene Hyvä Tailwind-Config, die auf der Basis des Parent-Themes aufbaut, ohne sie zu ersetzen. Genau hier liegt der Unterschied zwischen einer generischen Hyvä-Installation und einem Theme, das die Handschrift eines Kunden konsequent trägt.

Ohne eine sauber strukturierte Tailwind-Konfiguration im Hyvä-Theme entstehen schnell Inkonsistenzen: Entwickler tragen Farbwerte als Hex-Codes direkt in Klassennamen ein, statt sie zentral in theme.extend zu pflegen, oder ein Plugin fehlt, weil niemand dokumentiert hat, dass es registriert werden muss. Eine durchdachte Konfiguration löst dieses Problem strukturell: Design-Tokens werden an einer Stelle gepflegt, Plugins sind explizit deklariert und die content-Pfade erfassen zuverlässig alle Templates. Die folgenden Abschnitte zeigen Schritt für Schritt, wie diese Konfiguration in app/design/frontend/Mironsoft/default/web/tailwind/tailwind.config.js aufgebaut ist und welche Fallstricke beim Anpassen typischerweise auftreten.

2. Aufbau und Vererbung von tailwind.config.js im Theme

Das Hyvä-Parent-Theme hyva-themes/magento2-default-theme-csp liefert unter web/tailwind/tailwind.config.js eine Basis-Config, die Schriftgrößen, Standardfarben und einen Grundstock an content-Globs definiert. Ein Child-Theme wie Mironsoft/default überschreibt diese Datei nicht, sondern erweitert sie: Die eigene tailwind.config.js im Child-Theme lädt die Parent-Config per require() ein und führt sie per Object-Spread mit den eigenen Anpassungen zusammen. Dieses Muster ist die Grundlage jeder sauberen Hyvä Tailwind-Config, weil Updates am Parent-Theme automatisch weiterhin einfließen, ohne dass die eigene Anpassung bei jedem Theme-Update manuell nachgezogen werden muss.

In der Praxis bedeutet das: theme.extend.colors des Child-Themes wird mit dem colors-Objekt des Parents gemergt, plugins-Arrays werden konkateniert und content-Pfade werden addiert statt ersetzt. Wichtig ist dabei die Reihenfolge des Spreads: Steht die Parent-Config zuerst und die eigene Erweiterung danach, gewinnen bei Konflikten die eigenen Werte. Wer diese Vererbungslogik nicht versteht, überschreibt versehentlich die komplette Parent-Config und verliert plötzlich alle Hyvä-Standardklassen im gebauten CSS, was sich meist erst nach dem Static-Content-Deploy als fehlende Styles bemerkbar macht.

// app/design/frontend/Mironsoft/default/web/tailwind/tailwind.config.js
// Extends the Hyvä parent theme config instead of replacing it

const parentConfig = require(
  '../../../../Hyva/default/web/tailwind/tailwind.config.js'
);

module.exports = {
  ...parentConfig,

  // Merge content globs: parent paths + child-specific paths
  content: [
    ...parentConfig.content,
    '../../Magento_Theme/templates/**/*.phtml',
  ],

  theme: {
    ...parentConfig.theme,
    extend: {
      ...parentConfig.theme.extend,
      // Child-specific design tokens are added below (see section 3)
    },
  },

  // Concatenate plugins instead of overwriting them
  plugins: [
    ...parentConfig.plugins,
  ],
};

3. theme.extend: Farben, Schrift und Spacing aus Design-Tokens

theme.extend ist der zentrale Ort, an dem Design-Tokens aus dem Corporate Design eines Kunden in die Hyvä Tailwind-Config einfließen. Statt Tailwinds Standardpalette zu ersetzen, ergänzt extend.colors zusätzliche Markenfarben wie brand.primary oder brand.accent, die im gesamten Theme als bg-brand-primary oder text-brand-accent verfügbar werden. Der Vorteil gegenüber Inline-Hex-Werten in Templates: Ändert sich eine Markenfarbe, genügt eine Anpassung an einer einzigen zentralen Stelle, statt Dutzende phtml-Dateien zu durchsuchen.

Analog werden fontFamily-Einträge für individuelle Schriftfamilien und spacing-Werte für ein abweichendes Grid-System ergänzt. Wichtig ist, Design-Tokens so zu benennen, dass sie fachlich statt visuell beschreiben, was sie tun, etwa brand.primary statt orange-500, damit ein späterer Rebrand nicht zu semantisch falschen Klassennamen führt. Spacing-Werte sollten sich an einer konsistenten Skala orientieren, etwa Vielfachen von 4px, damit sie sich nahtlos in Tailwinds bestehende Spacing-Skala einfügen. Diese Struktur macht die Hyvä Tailwind-Config zur einzigen Quelle der Wahrheit für das visuelle Erscheinungsbild des Storefronts.

// theme.extend block inside tailwind.config.js
// Brand design tokens, kept separate from Tailwind defaults

theme: {
  extend: {
    colors: {
      brand: {
        primary: '#b3294f',
        accent: '#fb8570',
        dark: '#5c1a2e',
      },
    },
    fontFamily: {
      sans: ['"Inter"', 'system-ui', 'sans-serif'],
      display: ['"Sora"', 'system-ui', 'sans-serif'],
    },
    spacing: {
      18: '4.5rem',
      22: '5.5rem',
    },
    borderRadius: {
      card: '1.25rem',
    },
  },
},

4. Plugins registrieren: typography, forms, aspect-ratio

Hyvä-Themes nutzen häufig drei offizielle Tailwind-Plugins, die in der Hyvä Tailwind-Config explizit im plugins-Array registriert werden müssen: @tailwindcss/typography für automatisch gestylte Rich-Text-Inhalte aus CMS-Blöcken und Produktbeschreibungen, @tailwindcss/forms für konsistent gestylte Formularelemente ohne zusätzliches CSS und @tailwindcss/aspect-ratio für responsive Bild- und Video-Container ohne JavaScript. Jedes Plugin muss zunächst per npm als Dev-Dependency installiert und anschließend in der plugins-Liste der tailwind.config.js referenziert werden, sonst bleiben die zugehörigen Utility-Klassen wie prose oder aspect-video im gebauten CSS ungenutzt.

Die Reihenfolge der Plugins spielt in der Regel keine Rolle, wohl aber die Versionskompatibilität: Tailwind-v4-Plugins nutzen ein anderes Registrierungsformat als v3-Plugins, weshalb beim Umstieg auf Hyväs v4-kompatible Themes die Plugin-Versionen aus der package.json geprüft werden sollten. Ein häufig übersehener Punkt: Das typography-Plugin generiert standardmäßig eigene Farbwerte für Überschriften und Links, die mit den eigenen theme.extend.colors kollidieren können. Über die modifiers-Option lässt sich die Typography-Farbe gezielt an die Markenfarben aus der Hyvä Tailwind-Config anpassen.

{
  "name": "mironsoft-default-tailwind",
  "private": true,
  "scripts": {
    "build": "tailwindcss -i ./tailwind-source.css -o ../css/styles.css --minify",
    "watch": "tailwindcss -i ./tailwind-source.css -o ../css/styles.css --watch"
  },
  "devDependencies": {
    "tailwindcss": "^3.4.10",
    "@tailwindcss/typography": "^0.5.13",
    "@tailwindcss/forms": "^0.5.7",
    "@tailwindcss/aspect-ratio": "^0.4.2"
  }
}

5. content-Pfade und Purge-Globs korrekt konfigurieren

Das content-Array in der Hyvä Tailwind-Config bestimmt, welche Dateien beim Build nach genutzten Klassennamen durchsucht werden, und ist damit einer der fehleranfälligsten Teile der gesamten Konfiguration. Fehlt ein Pfad, verschwinden Klassen aus dem gebauten CSS, obwohl sie im Template korrekt geschrieben sind. Für ein Mironsoft-Theme müssen mindestens app/design/frontend/Mironsoft/default/**/*.phtml, die vererbten Templates aus app/design/frontend/Hyva/default/**/*.phtml sowie alle JavaScript-Dateien unter web/js/**/*.js in den content-Globs stehen, damit sowohl eigene als auch geerbte Templates korrekt erfasst werden.

Zusätzlich müssen Alpine.js-Ausdrücke berücksichtigt werden: Klassen, die dynamisch innerhalb von x-data, x-bind:class oder :class-Attributen als String zusammengesetzt werden, findet Tailwinds Scanner nur, wenn der vollständige Klassenname irgendwo als Literal im Quellcode auftaucht. Auch Vendor-Module wie Magefan_Blog oder Drittanbieter-Hyvä-Module, die eigene phtml-Templates mitbringen, müssen in den content-Pfaden der Hyvä Tailwind-Config berücksichtigt werden, sonst bleiben deren Utility-Klassen im finalen Build ungenutzt. Ein Glob wie vendor/hyva-themes/**/*.phtml deckt das ab, verlangsamt aber den Build spürbar, weshalb er nur bei tatsächlich genutzten Modulen ergänzt werden sollte.

// content array: scans phtml, JS and Alpine expressions for used classes
content: [
  '../../Magento_Theme/templates/**/*.phtml',
  '../../Magento_Catalog/templates/**/*.phtml',
  '../../Magento_Checkout/templates/**/*.phtml',
  '../../Magefan_Blog/templates/**/*.phtml',
  './web/js/**/*.js',
  // Inherited Hyvä parent-theme templates
  '../../../../Hyva/default/Magento_Theme/templates/**/*.phtml',
  '../../../../Hyva/default/Magento_Catalog/templates/**/*.phtml',
  // Third-party Hyvä modules shipping their own templates
  '../../../../../../vendor/hyva-themes/magento2-catalog-graphql/**/*.phtml',
],

6. Safelist für dynamische Klassennamen

Dynamisch zusammengesetzte Klassennamen sind das häufigste Problem beim Konfigurieren einer Hyvä Tailwind-Config: Ein PHP-ViewModel, das eine Farbklasse als Variable zusammenbaut, etwa 'bg-' . $farbe, liefert zur Build-Zeit keinen vollständigen String, den Tailwinds Scanner erkennen könnte. Das Ergebnis: Die Klasse wird im gebauten CSS nicht generiert und die Farbe fehlt im Frontend, obwohl der PHP-Code syntaktisch korrekt ist. Die safelist-Option in der Config löst dieses Problem, indem sie bestimmte Klassennamen oder Muster unabhängig davon erzwingt, ob sie im Quellcode als Literal auftauchen.

Für eine begrenzte Anzahl bekannter Werte, etwa Badge-Farben aus einem CMS-Attribut, genügt eine explizite Liste von Klassennamen in der safelist. Für größere Wertebereiche, etwa dynamische Grid-Spalten aus einem Produkt-Slider, ist ein regex-Pattern in der safelist effizienter als Dutzende Einzeleinträge. Wichtig: Die safelist sollte so klein wie möglich gehalten werden, weil jeder zusätzliche Eintrag die CSS-Ausgabegröße erhöht. Der bessere Weg ist meist, dynamische Klassennamen im PHP- oder Alpine-Code komplett als Literal zu schreiben, etwa über ein Mapping-Array, statt sich dauerhaft auf die safelist der Hyvä Tailwind-Config zu verlassen.

7. Tailwind v3 JS-Config vs. v4 CSS-first @theme

Tailwind v3 konfiguriert Theme-Werte ausschließlich in der JavaScript-Datei tailwind.config.js: Farben, Schriftgrößen und Spacing werden als verschachtelte Objekte definiert und beim Build von PostCSS eingelesen. Tailwind v4 verschiebt einen Großteil dieser Konfiguration in CSS selbst, über die @theme-Direktive direkt in der Haupt-CSS-Datei. Statt colors.brand.primary in der JS-Config zu definieren, schreibt man in v4 --color-brand-primary: #b3294f; innerhalb eines @theme-Blocks, und Tailwind generiert daraus automatisch die passenden Utility-Klassen. Für Hyvä-Themes bedeutet das: Aktuelle Hyvä-Parent-Themes unterstützen oft beide Ansätze parallel, was beim Anpassen der eigenen Hyvä Tailwind-Config zu Verwechslungen führen kann.

Die praktische Brücke zwischen beiden Welten: Die tailwind.config.js bleibt für Plugins, content-Pfade und komplexere JavaScript-Logik zuständig, etwa dynamische Werte aus einer externen Konfigurationsdatei, während @theme in der CSS-Datei für reine Design-Token-Werte genutzt wird, die keine Logik benötigen. Tailwind v4 liest beide Quellen zusammen ein, sodass eine Hyvä Tailwind-Config mit theme.extend und eine @theme-Direktive im selben Projekt koexistieren können. Wer ein bestehendes v3-Theme auf v4 migriert, sollte schrittweise vorgehen: zuerst die JS-Config unverändert lassen, dann einzelne Design-Tokens in @theme übernehmen und erst danach redundante Einträge aus der tailwind.config.js entfernen.

8. Build-Integration im Mark-Shust-Docker-Setup

Im Mark-Shust-Docker-Setup läuft der Tailwind-Build nicht auf dem Host, sondern im Container, weshalb npm-Befehle immer über den bin/npm-Wrapper ausgeführt werden. Nach jeder Änderung an der Hyvä Tailwind-Config muss der Build neu angestoßen werden, damit neue Design-Tokens, Plugins oder content-Pfade tatsächlich im gebauten CSS landen. Der Befehl bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run build kompiliert die finale CSS-Datei einmalig, während der Watcher-Modus Änderungen an der Config und an Templates kontinuierlich überwacht und automatisch neu baut.

Da Tailwind die content-Pfade der Hyvä Tailwind-Config beim Start einliest, erkennt der Watcher neue Glob-Muster erst nach einem Neustart des Watcher-Prozesses, nicht während er läuft. Wer also einen neuen Pfad in den content-Globs ergänzt, muss den laufenden bin/npm-Watch-Prozess beenden und neu starten. Vor dem produktiven Deploy sollten zusätzlich var/view_preprocessed und pub/static/frontend geleert werden, weil Magento sonst weiterhin die alte, im Cache liegende CSS-Datei ausliefert, selbst wenn Config und Build bereits aktualisiert wurden.

# One-off production build after changing tailwind.config.js
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run build

# Watcher mode: rebuilds on template and config changes
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run watch

# Restart required after adding a new glob to the content array
# (the watcher only re-reads content paths on startup)

# Clear caches before deploying so Magento serves the freshly built CSS
cd src && rm -rf var/view_preprocessed/* pub/static/frontend/*
bin/magento setup:static-content:deploy de_DE -t Mironsoft/default -f
bin/magento cache:flush

9. Typische Fehler und die Hyvä Tailwind-Config im Vergleich

Der häufigste Fehler beim Arbeiten mit einer Hyvä Tailwind-Config ist das versehentliche Überschreiben statt Erweitern des Parent-Themes: Wird theme.extend durch theme ersetzt, gehen sämtliche Hyvä-Basiswerte verloren und das Storefront verliert unbemerkt Abstände und Farben, die vorher aus dem Parent-Theme kamen. Ein zweiter klassischer Fehler betrifft vergessene content-Pfade nach dem Hinzufügen eines neuen Vendor-Moduls: Die Templates werden korrekt gerendert, aber ohne Styling, weil Tailwind die neuen phtml-Dateien beim Scan schlicht nicht kennt.

Die folgende Tabelle stellt unstrukturierte Ad-hoc-Anpassungen den empfohlenen Mustern einer sauber gepflegten Hyvä Tailwind-Config gegenüber. Der Unterschied zeigt sich meist erst beim nächsten Theme-Update oder beim Onboarding eines neuen Entwicklers, wenn unklar ist, wo eine bestimmte Farbe oder ein bestimmter Pfad überhaupt definiert wurde.

10. Zusammenfassung

Eine gut strukturierte Hyvä Tailwind-Config löst immer dasselbe Grundproblem: Ohne klare Trennung zwischen Parent-Theme und Child-Theme-Anpassung entstehen Inkonsistenzen bei Farben, fehlende Plugins und Templates ohne Styling. require() und Object-Spread erweitern die Parent-Config, statt sie zu ersetzen. theme.extend nimmt Design-Tokens für Farben, Schrift und Spacing auf. Plugins wie Typography, Forms und Aspect-Ratio werden explizit im plugins-Array registriert, und die content-Pfade erfassen zuverlässig alle phtml-, JS- und Alpine-Dateien im Theme.

Der größte Hebel liegt darin, die Hyvä Tailwind-Config als lebendes Dokument zu behandeln: Jedes neue Vendor-Modul, jede neue Alpine-Komponente und jeder neue Design-Token gehört sofort in die Konfiguration, statt als Ad-hoc-Ausnahme im Template zu landen. Der Unterschied zwischen Tailwind v3 und v4 verschiebt zwar Teile der Konfiguration von JavaScript nach CSS, ändert aber nichts an diesem Grundprinzip: Struktur, Vererbung und vollständige content-Pfade entscheiden darüber, ob das gebaute CSS im Storefront tatsächlich alle genutzten Klassen enthält.

11. FAQ: Hyvä Tailwind-Config anpassen