Tailwind CSS 4: @theme, Oxide Engine & Container Queries in der Praxis

Tailwind CSS 4 ist kein inkrementelles Update — es ist ein kompletter Architektur-Wechsel. Die tailwind.config.js ist weitgehend abgelöst. Die Konfiguration findet jetzt direkt im CSS statt. Der Compiler ist neu geschrieben. Und mehrere Browser-Features, die bisher Polyfills erforderten, sind jetzt nativ eingebaut. Dieser Artikel erklärt, was das konkret bedeutet und wie die Migration von v3 aussieht.

CSS-first: Konfiguration per @theme

In Tailwind CSS 3 lebten alle Design-Token in tailwind.config.js:

// v3 — JavaScript-Konfiguration
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: { 500: '#0072BB' },
      },
    },
  },
};

In Tailwind CSS 4 definiert man Design-Token direkt im CSS mit der neuen @theme-Direktive:

/* global.css — v4 */
@import 'tailwindcss';

@theme {
  --color-primary-500: #0072BB;
  --color-primary-600: #004C91;
  --color-primary-700: #003d74;

  --font-family-heading: 'Inter', sans-serif;

  --spacing-section: 5rem;
  --radius-card: 0.75rem;
}

Diese CSS Custom Properties sind nach der @theme-Deklaration als Tailwind-Utilities verfügbar — text-primary-500, bg-primary-600, rounded-card funktionieren automatisch. Das bedeutet: kein Build-Schritt, kein tailwind.config.js, keine Umwandlung von Tokens in Utility-Klassen — alles ist zur Laufzeit native CSS.

@theme vs. :root

Wichtig: @theme-Variablen sind nicht dasselbe wie :root-Variablen. Sie werden von Tailwind verarbeitet und erzeugen Utility-Klassen. :root-Variablen sind reguläre CSS Custom Properties, die nur per var() referenziert werden können.

Für Design Tokens, die in Komponenten via var() genutzt werden UND als Tailwind-Utilities verfügbar sein sollen, definiert man sie in @theme und referenziert sie mit dem gleichen Namen:

@theme {
  --color-brand: #0072BB;
}

/* Nutzung als var() */
.logo { color: var(--color-brand); }

/* Nutzung als Utility-Klasse */
/* <div class="text-brand"> funktioniert */

Der Oxide Compiler: was sich ändert

Tailwind CSS 4 nutzt einen neu geschriebenen Compiler (intern “Oxide” genannt), der mit Rust implementiert ist. Die Auswirkungen auf den Entwicklungsalltag:

• Build-Geschwindigkeit: Full Builds sind ca. 5x schneller, inkrementelle Rebuilds ca. 100x. Bei großen Projekten mit 200+ Seiten ist das spürbar.
• Content-Konfiguration entfällt: Der Oxide-Scanner erkennt Tailwind-Klassen automatisch durch statische Datei-Analyse — kein content-Array in der Konfiguration mehr nötig.
• Kein PostCSS erforderlich: Tailwind 4 funktioniert als eigenständiges Tool oder als Vite-Plugin ohne PostCSS-Pipeline.

Für Astro-Projekte mit dem @tailwindcss/vite-Plugin:

// astro.config.mjs
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

/* global.css — ein einziger Import reicht */
@import 'tailwindcss';

Container Queries nativ

Tailwind CSS 4 unterstützt Container Queries ohne Plugin. Die entsprechenden Utilities sind eingebaut:

<!-- Container definieren -->
<div class="@container">
  <!-- Responsiv zum Container, nicht zum Viewport -->
  <div class="grid grid-cols-1 @md:grid-cols-2 @xl:grid-cols-3">
    <!-- ... -->
  </div>
</div>

Container Query Breakpoints folgen derselben Naming-Konvention wie Viewport Breakpoints: @sm, @md, @lg, @xl, @2xl. Custom Container Breakpoints lassen sich in @theme definieren:

@theme {
  --container-card: 28rem;
}

Damit steht @card: als Utility-Prefix zur Verfügung.

Wann Container Queries statt Media Queries?

Container Queries lösen ein grundlegendes Problem: Eine Karte, die in einer 3-Spalten-Grid verwendet wird, ist schmaler als dieselbe Karte auf einer Single-Column-Seite. Mit Media Queries muss man das Breakpoint-Verhalten für jeden Kontext separat definieren. Mit Container Queries definiert die Karte ihr eigenes responsives Verhalten — unabhängig vom Viewport.

<!-- Dieselbe Komponente funktioniert korrekt in jedem Layout -->
<div class="@container rounded-card p-4 bg-white shadow-sm">
  <img class="w-full @lg:w-1/3 @lg:float-right @lg:ml-4" src="..." alt="..." />
  <h2 class="text-base @md:text-lg font-semibold">Titel</h2>
  <p class="text-sm @md:text-base text-gray-600">Beschreibung</p>
</div>

color-mix() in Tailwind 4

Tailwind CSS 4 integriert die CSS-native color-mix()-Funktion für Farbmodifikationen. Das ermöglicht transparente Varianten ohne separate Token-Definitionen:

/* Transparenz über color-mix() */
.overlay {
  background-color: color-mix(in srgb, var(--color-primary-600) 20%, transparent);
}

Als Tailwind-Utility:

<!-- 20% Deckkraft des primären Blaus -->
<div class="bg-primary-600/20">...</div>

Die /-Syntax für Opacity-Modifier ist in Tailwind 4 direkt an color-mix() gebunden — es gibt keine separaten -transparent-Varianten mehr.

Wichtige Änderungen bei bestehenden Utilities

Mehrere Tailwind-v3-Utilities verhalten sich in v4 anders oder wurden umbenannt:

v3	v4	Änderung
bg-opacity-50	bg-primary/50	Opacity-Modifier direkt
ring-offset-*	entfernt	Ring-Offset-Utilities gestrichen
flex-shrink-0	shrink-0	Kurzform
overflow-ellipsis	text-ellipsis	Umbenannt
transform	automatisch	Kein explizites transform mehr nötig

Die Migration ist gut dokumentiert unter tailwindcss.com/docs/upgrade-guide. Ein automatisches Codemod steht bereit:

npx @tailwindcss/upgrade@next

Versionskompatibilität und Pinning

Da Tailwind 4 zusammen mit Vite 7 deployed wird, gibt es Build-Inkompatibilitäten mit bestimmten Patch-Versionen. Für stabile Astro-Projekte empfiehlt sich ein explizites Version-Pinning in package.json:

{
  "overrides": {
    "vite": "^7.3.2"
  },
  "devDependencies": {
    "tailwindcss": "4.2.2",
    "@tailwindcss/vite": "4.2.2"
  }
}

Tailwind 4.2.4 mit Vite 8 (Rolldown-Bundler) kann zu Build-Fehlern wie Missing field 'tsconfigPaths' führen — bis die Kompatibilität offiziell bestätigt ist, bleibt man bei den genannten Versionen.

Migration von v3: Schritt für Schritt

1. Codemod ausführen: npx @tailwindcss/upgrade@next — migriert automatisch ~80% der Änderungen
2. tailwind.config.js analysieren: Theme-Extend-Werte in @theme-Block im CSS überführen
3. PostCSS-Config entfernen: falls ausschließlich für Tailwind genutzt
4. content-Array entfernen: der neue Scanner braucht es nicht
5. Build testen: npm run build und auf Utility-Klassen achten, die umbenannt wurden
6. Visuelle Regression prüfen: Screenshots vergleichen, besonders bei ring, bg-opacity, shadow

Fazit

Tailwind CSS 4 macht das Framework deutlich weniger abhängig von JavaScript-Konfiguration und näher an nativen CSS-Workflows. Die wichtigsten Gewinne: schnellere Builds, eingebaute Container Queries und ein Token-System, das direkt im CSS lebt.

Weiterführende Artikel auf Wender Media Wissen:

• Dark Mode mit semantischen Design-Tokens
• Astro 6 Architektur: Islands, Server Islands & Content Layer API
• BFSG technisch umsetzen in Astro

---

Sie planen eine Migration auf Tailwind CSS 4 oder einen Neubau auf modernem Stack? Wender Media berät Sie technisch und umsetzt — info@wendermedia.info.