Tailwind CSS v4 CSS-First Config: Theme ohne tailwind.config.js

1. Warum Tailwind CSS v4 auf CSS-First setzt

Mit Tailwind CSS v4 hat das Framework einen grundlegenden Paradigmenwechsel vollzogen: Die Konfiguration wandert von JavaScript zurück in CSS. Bisher war tailwind.config.js die zentrale Steuerdatei für Farben, Schriften, Breakpoints und alle projektspezifischen Erweiterungen. Dieser Ansatz funktionierte, hatte aber einen wesentlichen Nachteil: Die Konfiguration war von der Sprache getrennt, in der sie letztendlich Wirkung zeigte. Ein Designer, der CSS kennt, musste JavaScript verstehen, um das Theme anzupassen. Ein Entwickler musste bei jeder Änderung zwischen zwei Dateien wechseln.

Der CSS-First-Ansatz von Tailwind CSS v4 löst dieses Problem durch die neue @theme-Direktive. Design-Tokens werden direkt in der CSS-Eingabedatei definiert und stehen sofort als Tailwind-Utility-Klassen zur Verfügung. Das Framework analysiert die @theme-Blöcke zur Build-Zeit und generiert daraus sowohl die Utility-Klassen als auch native CSS Custom Properties. Der Build-Prozess wird dadurch schneller, weil kein JavaScript evaluiert werden muss, und die Konfiguration ist für jeden lesbar, der CSS versteht – ohne Node.js-Kenntnisse.

Ein weiterer Vorteil des CSS-First-Configs: Die generierten Custom Properties sind zur Laufzeit verfügbar. Das bedeutet, dass JavaScript-Code auf dieselben Tokens zugreifen kann wie CSS, und dass Theme-Werte dynamisch per JavaScript überschrieben werden können – etwas, das mit tailwind.config.js nicht möglich war, weil die Werte nur zur Build-Zeit existierten.

2. Die @theme-Direktive: Aufbau und Syntax

Die @theme-Direktive ist der Kern des CSS-First-Configs in Tailwind CSS v4. Innerhalb eines @theme-Blocks definiert man CSS Custom Properties, die einem bestimmten Namensschema folgen müssen. Tailwind erkennt diese Properties anhand ihrer Präfixe und leitet daraus Utility-Klassen ab. --color-primary-500 erzeugt Klassen wie text-primary-500, bg-primary-500 und border-primary-500. Das Präfix bestimmt, welche Utilities generiert werden – --font-* für Schriftfamilien, --spacing-* für Abstände, --radius-* für Border-Radien.

Wichtig beim Tailwind CSS v4 CSS-First-Ansatz: Die @theme-Direktive gehört in die Haupt-CSS-Eingabedatei, direkt nach dem @import "tailwindcss". Sie ist keine Standard-CSS-Direktive, sondern wird vom Tailwind-Preprocessor interpretiert. Im Ausgabe-CSS wird @theme in einen :root-Block mit den entsprechenden CSS Custom Properties umgewandelt. Diese Properties tragen dann die tatsächlichen Werte und werden sowohl von Tailwinds internen Utilities als auch von eigenem CSS referenziert.

/* main.css — Tailwind CSS v4 entry point with CSS-First config */
@import "tailwindcss";

@theme {
  /* Color tokens — generates text-*, bg-*, border-* utilities */
  --color-primary-50:  #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;
  --color-primary-900: #1e3a8a;

  /* Brand accent */
  --color-accent: #0ea5e9;

  /* Typography tokens — generates font-* utilities */
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-display: "Cal Sans", "Inter", sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;

  /* Spacing scale extension */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;
  --spacing-128: 32rem;

  /* Border radius tokens */
  --radius-card: 1rem;
  --radius-pill: 9999px;
}

Nach dem Build erzeugt Tailwind daraus automatisch alle passenden Utility-Klassen. bg-primary-500, text-primary-700, border-primary-100 stehen sofort zur Verfügung – ohne weitere Konfiguration. Das --color-accent-Token ohne Stufe erzeugt einfarbige Utilities wie bg-accent. Das ist der elegante Kern des CSS-First-Configs: Was in @theme steht, wird automatisch zu Tailwind-Klassen.

3. Farben mit CSS-First Config definieren

Farben sind der häufigste Anwendungsfall für den Tailwind CSS v4 CSS-First-Config. In v3 musste man in tailwind.config.js ein verschachteltes JavaScript-Objekt mit den Farbstufen definieren. In v4 genügt das Präfix --color- gefolgt vom Farbnamen und der Stufe. Die Stufen müssen nicht dem Standard-Tailwind-Schema (50, 100, 200 … 900) folgen – eigene Stufenbezeichnungen wie --color-brand-muted oder --color-surface-elevated sind möglich.

Für semantische Farbsysteme bietet sich das Muster an, neben den konkreten Farbpaletten auch semantische Tokens zu definieren, die auf die konkreten Farben verweisen. In Tailwind CSS v4 mit CSS-First-Config funktioniert das über native CSS-Variable-Referenzen: --color-background: var(--color-neutral-50). Ändert man später die zugrundeliegende Palette, aktualisieren sich alle semantischen Tokens automatisch. Das ist ein erheblicher Vorteil gegenüber dem alten Ansatz, bei dem Farbwerte dupliziert werden mussten.

4. Schriften und Spacing im CSS-First-Ansatz

Schriftfamilien werden in der Tailwind CSS v4 CSS-First-Konfiguration über das Präfix --font- definiert. Der Wert ist eine vollständige Font-Stack-Deklaration, wie sie auch in regulärem CSS verwendet wird. --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif erzeugt die Klasse font-sans mit diesem vollständigen Stack. Das ersetzt die frühere fontFamily-Konfiguration in tailwind.config.js vollständig und erlaubt dieselbe Kontrolle über Fallback-Schriften.

Das Spacing-System lässt sich mit --spacing-*-Tokens erweitern. Tailwind v4 verwendet intern ein mathematisches Spacing-System mit einer Basiseinheit, sodass man nicht jede Stufe einzeln definieren muss. Mit dem CSS-First-Config fügt man gezielt Lücken im Standard-System hinzu, etwa --spacing-18: 4.5rem für einen Wert zwischen 16 (4rem) und 20 (5rem). Diese ergänzenden Tokens erscheinen dann in allen Spacing-Utilities: p-18, m-18, gap-18, w-18 und so weiter – ohne Sonderbehandlung oder Plugin.

/* Extended theme with semantic color tokens and custom spacing */
@theme {
  /* Semantic color layer — references the concrete palette */
  --color-background:        var(--color-neutral-50);
  --color-surface:           #ffffff;
  --color-surface-elevated:  var(--color-neutral-100);
  --color-foreground:        var(--color-neutral-900);
  --color-muted:             var(--color-neutral-500);
  --color-border:            var(--color-neutral-200);

  /* Interactive states */
  --color-interactive:       var(--color-primary-600);
  --color-interactive-hover: var(--color-primary-700);
  --color-interactive-focus: var(--color-primary-500);

  /* Font size tokens (generates text-* utilities) */
  --text-display-xl: 4.5rem;
  --text-display-lg: 3.75rem;

  /* Line height tokens */
  --leading-display: 1.1;
  --leading-relaxed-lg: 1.75;

  /* Shadow tokens */
  --shadow-card:    0 1px 3px 0 rgba(0,0,0,0.10), 0 1px 2px -1px rgba(0,0,0,0.10);
  --shadow-overlay: 0 20px 60px -12px rgba(0,0,0,0.25);
}

5. Eigene Design-Tokens mit @theme erstellen

Über die Standard-Präfixe hinaus erlaubt der Tailwind CSS v4 CSS-First-Config vollständig eigene Token-Kategorien. Wenn ein Präfix nicht einem der eingebauten Tailwind-Präfixe entspricht, wird keine Utility-Klasse generiert – die Variable existiert aber trotzdem als CSS Custom Property im :root und ist in beliebigem CSS verwendbar. Damit dient @theme auch als zentrales Design-Token-Register für Werte, die außerhalb der Utility-Klassen eingesetzt werden, etwa in komplexen CSS-Animationen oder SVG-Attributen.

Für Projekte mit mehreren Themes oder White-Label-Anforderungen ist der CSS-First-Ansatz von Tailwind CSS v4 besonders wertvoll. Man definiert ein Basis-Theme mit @theme und überschreibt einzelne Tokens in tema-spezifischen CSS-Dateien, die per @import geladen werden. Da alle Werte letztendlich CSS Custom Properties sind, lassen sie sich auch über JavaScript dynamisch überschreiben – etwa für Nutzer-Präferenzen wie Dark Mode oder Schriftgrößen-Einstellungen.

6. @import und Dateistruktur im CSS-First-Projekt

Die empfohlene Dateistruktur für ein Tailwind CSS v4 CSS-First-Projekt sieht vor, dass eine zentrale Eingabedatei – typischerweise app.css oder main.css – alle @import-Direktiven und die @theme-Blöcke enthält. Das ist ein Bruch mit früheren Tailwind-Versionen, bei denen nur drei @tailwind-Direktiven in der Eingabedatei standen und die eigentliche Konfiguration in tailwind.config.js lag. In v4 ist die CSS-Datei der einzige Konfigurationsort.

Für größere Projekte empfiehlt sich eine Aufteilung: tokens.css für alle @theme-Definitionen, base.css für globale Reset- und Basisstile mit @layer base, components.css für wiederverwendbare Komponentenklassen mit @layer components und utilities.css für projektspezifische Utilities mit @layer utilities. Die Hauptdatei importiert diese mit @import "./tokens.css". Das Ergebnis ist eine klare Trennung ohne die Komplexität einer JavaScript-Konfigurationsdatei.

/* app.css — CSS-First project entry point */
@import "tailwindcss";

/* Project-specific token definitions */
@import "./tokens/colors.css";
@import "./tokens/typography.css";
@import "./tokens/spacing.css";

/* Base layer overrides */
@layer base {
  *, *::before, *::after {
    box-sizing: border-box;
  }

  html {
    /* Enable smooth scrolling globally */
    scroll-behavior: smooth;
    -webkit-text-size-adjust: 100%;
  }

  body {
    font-family: var(--font-sans);
    color: var(--color-foreground);
    background-color: var(--color-background);
    line-height: var(--leading-normal);
  }
}

/* Custom component definitions */
@layer components {
  .btn-primary {
    @apply inline-flex items-center justify-center gap-2 font-semibold;
    @apply bg-primary-600 text-white rounded-card px-6 py-3;
    @apply hover:bg-primary-700 focus-visible:outline-none;
    @apply focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2;
    @apply transition-colors duration-200;
  }
}

7. Migration von tailwind.config.js zu CSS-First

Die Migration eines bestehenden Tailwind-v3-Projekts auf den CSS-First-Config-Ansatz von v4 ist in den meisten Fällen geradlinig, erfordert aber systematisches Vorgehen. Der erste Schritt ist die Analyse der bestehenden tailwind.config.js: Welche Farben wurden erweitert, welche Schriften hinzugefügt, welche Spacing-Werte ergänzt? Jeder dieser Werte muss in entsprechende @theme-Deklarationen übersetzt werden. Die Namenskonvention folgt dem Muster: Aus dem JavaScript-Pfad theme.extend.colors.primary[500] wird --color-primary-500.

Plugins aus tailwind.config.js, die neue Utilities hinzufügen, müssen gesondert betrachtet werden. Einfache Plugins, die nur Utility-Klassen mit festen Werten hinzufügen, lassen sich in @layer utilities übersetzen. Plugins, die dynamisch auf Konfigurationswerte zugreifen, sind in Tailwind CSS v4 mit CSS-First-Config oft vereinfachbar, weil die Tokens jetzt als CSS Custom Properties verfügbar sind und direkt referenziert werden können. Einige Community-Plugins haben bereits v4-kompatible Versionen veröffentlicht.

8. CSS-First Config im Vergleich zur JavaScript-Konfiguration

Der direkte Vergleich zeigt die konkreten Unterschiede zwischen dem alten JavaScript-Ansatz und dem neuen Tailwind CSS v4 CSS-First-Config.

Der CSS-First-Config-Ansatz von Tailwind CSS v4 ist nicht nur eine syntaktische Änderung. Er verändert, wie das Framework in einem Projekt eingebettet ist. Statt einer Grenze zwischen CSS und JavaScript-Konfiguration gibt es nur noch eine einzige Quelle der Wahrheit: die CSS-Eingabedatei. Das vereinfacht Tooling, erleichtert das Onboarding neuer Entwickler und öffnet die Türen für bessere IDE-Integration, weil CSS-Editoren nativ mit @theme-Direktiven umgehen können.

9. Häufige Fehler beim CSS-First-Ansatz

Der häufigste Fehler beim Einstieg in den Tailwind CSS v4 CSS-First-Config ist das Vergessen des korrekten Präfixes. Wer --primary-500 statt --color-primary-500 schreibt, bekommt keine Tailwind-Utility-Klassen – die Variable existiert als CSS Custom Property, aber Tailwind generiert kein bg-primary-500 oder text-primary-500 daraus. Das Präfix muss exakt dem eingebauten Tailwind-Schema entsprechen. Ein weiterer verbreiteter Fehler ist das Definieren von @theme-Blöcken in Dateien, die nicht als Tailwind-Eingabedatei konfiguriert sind – @theme wird nur in der Haupteingabedatei und ihren direkten @import-Dateien verarbeitet.

Projekte, die von Tailwind v3 auf v4 migrieren, stoßen häufig auf das Problem, dass Plugins, die in tailwind.config.js registriert waren, im CSS-First-Ansatz nicht automatisch funktionieren. Plugins müssen explizit mit @plugin "plugin-name" in der Eingabedatei geladen werden. Das content-Array aus tailwind.config.js entfällt in v4 komplett – Tailwind erkennt die zu scannenden Dateien durch automatische Heuristik oder durch explizite @source-Direktiven. Wer noch mit einem expliziten Content-Pfad arbeitet, muss auf @source "../src/**/*.{html,js,php}" umstellen.

10. Zusammenfassung

Der CSS-First-Config-Ansatz von Tailwind CSS v4 ist ein durchdachter Schritt näher an die CSS-Plattform. Die @theme-Direktive ersetzt tailwind.config.js vollständig für die meisten Projekte und bringt Design-Tokens dahin, wo sie hingehören: in CSS. Farben, Schriften, Spacing, Border-Radien und Custom Tokens werden mit vertrauter CSS-Syntax definiert und stehen sofort als Tailwind-Utility-Klassen und als CSS Custom Properties zur Verfügung. Der Build-Prozess wird schneller, weil kein JavaScript evaluiert werden muss. Die Laufzeit-Verfügbarkeit der Tokens als CSS Custom Properties öffnet neue Möglichkeiten für dynamische Themes und JavaScript-Integration.

Für Teams, die von Tailwind v3 migrieren, ist der Umstellungsaufwand überschaubar: Die Konfigurationswerte übersetzen sich direkt in @theme-Deklarationen, und die neue Dateistruktur mit zentraler CSS-Eingabedatei ist in den meisten Projekten innerhalb weniger Stunden eingerichtet. Der CSS-First-Ansatz ist keine Breaking Change im Sinne der Klassen-API – die Utility-Klassen bleiben identisch. Was sich ändert, ist ausschließlich die Art, wie das Theme konfiguriert wird.