Tailwind CSS Komponenten mit Storybook dokumentieren

1. Warum Storybook für Tailwind CSS Projekte?

In einem Tailwind CSS Projekt wachsen UI-Komponenten oft schneller als ihre Dokumentation. Button-Varianten, Badge-Farben, Card-Layouts – jede neue Komponente bringt neue Tailwind-Klassen-Kombinationen mit sich. Ohne eine lebendige Komponentendokumentation verlieren Entwickler und Designer schnell den Überblick, welche Varianten existieren, welche Klassen sie verwenden und wie sie in verschiedenen Zuständen aussehen. Tailwind CSS Storybook löst dieses Problem: Jede Komponente wird isoliert dokumentiert, in allen relevanten Zuständen dargestellt und für das gesamte Team zugänglich gemacht.

Storybook ist framework-agnostisch und unterstützt React, Vue, Angular, Svelte und reines HTML. In Tailwind CSS Projekten ist der Ansatz derselbe, unabhängig vom Framework: Die Komponente rendert HTML mit Tailwind-Klassen, Storybook zeigt sie isoliert an, und Storybook Controls ermöglichen es, Tailwind-Klassen oder Komponent-Props interaktiv zu ändern. Designer können direkt im Browser überprüfen, ob die Farben korrekt sind. QA-Teams können Zugänglichkeit testen. Neue Entwickler finden alle Komponenten an einem Ort. Das Tailwind CSS Storybook wird zum Single Source of Truth für das Design System.

2. Storybook mit Tailwind CSS einrichten

Das Storybook-Setup für ein Tailwind CSS Projekt beginnt mit der Installation von Storybook in das bestehende Projekt. npx storybook@latest init erkennt automatisch das verwendete Framework (React, Vue, etc.) und konfiguriert die grundlegenden Storybook-Dateien. Der nächste Schritt ist die Tailwind-Integration: Die CSS-Hauptdatei des Projekts, die den @tailwind base, @tailwind components und @tailwind utilities-Import enthält, muss in der Storybook-Preview-Konfiguration importiert werden. Das geschieht in .storybook/preview.js oder preview.ts.

Wenn das Projekt Vite als Build-Tool nutzt, muss die .storybook/main.js zusätzlich das Vite-Config-File referenzieren, damit die Tailwind CSS PostCSS-Pipeline auch in Storybook aktiv ist. Bei Webpack-Projekten wird das PostCSS-Plugin in der Storybook-Webpack-Konfiguration aktiviert. In beiden Fällen ist das Ziel dasselbe: Storybook soll dieselbe CSS-Ausgabe erzeugen wie die eigentliche Anwendung. Ein häufiger Fehler beim Tailwind CSS Storybook-Setup: Die content-Konfiguration in tailwind.config.js schließt die Story-Dateien nicht ein, sodass Tailwind die in Stories verwendeten Klassen nicht findet und im Build entfernt.

// .storybook/main.js — Storybook + Tailwind CSS + Vite setup
import { mergeConfig } from 'vite';

/** @type { import('@storybook/react-vite').StorybookConfig } */
const config = {
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
  ],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',         // Accessibility testing
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  viteFinal: async (config) => {
    // Merge Tailwind CSS PostCSS config from the main Vite config
    return mergeConfig(config, {
      css: {
        postcss: './postcss.config.js',
      },
    });
  },
};

export default config;

// .storybook/preview.js — Import Tailwind CSS and global styles
import '../src/styles/globals.css'; // Contains @tailwind base/components/utilities

/** @type { import('@storybook/react').Preview } */
const preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    // Default background for stories — white matches most Tailwind components
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'gray', value: '#f8fafc' },
        { name: 'dark', value: '#0f172a' },
      ],
    },
  },
};

export default preview;

3. Die erste Tailwind CSS Story schreiben

Eine Story in Storybook ist eine Funktion, die eine Komponente in einem bestimmten Zustand rendert. Für Tailwind CSS Komponenten bedeutet das: Die Story rendert die Komponente mit bestimmten Tailwind-Klassen oder Props, die Tailwind-Klassen intern steuern. Das Component Story Format (CSF) ist die Standardform: Eine Default-Export-Objekt definiert den Komponent-Typ und die Metadaten, einzelne benannte Exports definieren die Stories. Für eine einfache Button-Komponente gibt es separate Stories für Primary, Secondary, Destructive, Disabled und Loading.

Die wichtigste Design-Entscheidung bei Tailwind CSS Storybook-Stories: Werden die Tailwind-Klassen als Props übergeben (z. B. variant="primary", das intern zu bestimmten Klassen mappt) oder werden die Klassen direkt als Args übergeben? Der erste Ansatz ist sauberer und macht die Komponenten-API explizit. Der zweite Ansatz ist flexibler, aber er koppelt die Story direkt an Tailwind-Klassen und macht zukünftige Änderungen schwieriger. Für wiederverwendbare Design-System-Komponenten ist das Variant-Prop-Pattern die empfohlene Wahl, weil es die Tailwind-Implementierung von der Komponenten-API trennt.

// src/components/Button/Button.stories.tsx — Tailwind CSS + Storybook
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Design System/Button',
  component: Button,
  parameters: {
    layout: 'centered',
    docs: {
      description: {
        component: 'Primary UI action button. Uses Tailwind CSS utility classes internally.',
      },
    },
  },
  // Auto-generate controls for all props
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'destructive', 'ghost'],
      description: 'Visual style of the button',
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
      description: 'Button size — maps to Tailwind padding and text classes',
    },
    disabled: { control: 'boolean' },
    loading: { control: 'boolean' },
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

// Default story — primary, medium size
export const Primary: Story = {
  args: { variant: 'primary', size: 'md', children: 'Jetzt anfragen' },
};

export const Secondary: Story = {
  args: { variant: 'secondary', size: 'md', children: 'Mehr erfahren' },
};

export const Destructive: Story = {
  args: { variant: 'destructive', size: 'md', children: 'Löschen' },
};

export const AllVariants: Story = {
  render: () => (
    <div className="flex flex-wrap gap-4 items-center">
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="destructive">Destructive</Button>
      <Button variant="ghost">Ghost</Button>
    </div>
  ),
};

4. Storybook Controls für Tailwind-Varianten

Storybook Controls machen den größten Unterschied bei der Tailwind CSS Storybook-Erfahrung: Sie erlauben es, Props interaktiv in der Storybook-UI zu ändern, ohne Code schreiben zu müssen. Für Tailwind CSS Komponenten, die Varianten über Props steuern, funktionieren Controls direkt: Ein Select-Control für variant, ein Boolean-Control für disabled, ein Range-Control für Größenstufen. Das macht es möglich, alle Zustände einer Komponente ohne separate Stories zu erkunden.

Für fortgeschrittene Anwendungsfälle – etwa wenn Tailwind-Klassen direkt als String-Prop übergeben werden – kann das Control als freier Text-Input konfiguriert werden. Das ist praktisch für Spacing-Overrides oder Farbanpassungen. Ein dediziertes Addon namens storybook-tailwind-controls (oder ähnliche Community-Addons) kann Tailwind-Farbpaletten direkt als Farbauswahl in Controls darstellen. In der Regel reicht aber das eingebaute Controls-Addon vollständig aus, wenn die Komponenten-API klar strukturiert ist und Tailwind-Klassen intern über Props gemappt werden.

5. Design Tokens: Tailwind-Farben in Storybook verfügbar machen

Ein zentrales Feature eines Design Systems ist die Dokumentation der Designentscheidungen selbst – also der Farben, Abstände, Schriftgrößen und anderen Token. Mit Tailwind CSS Storybook lässt sich die tailwind.config.js direkt in Storybook importieren, um eine lebendige Farbpalette, Spacing-Dokumentation und Typo-Skala anzuzeigen. Dafür wird in einer separaten MDX-Datei oder Story die Tailwind-Konfiguration importiert und in einer formatierten Übersicht gerendert.

Das Storybook-Addon @storybook/addon-docs enthält die ColorPalette-Komponente, die Farb-Swatches mit Name und Hex-Wert rendert. Indem man die Tailwind-Farbpalette programmatisch in dieses Format umwandelt, entsteht eine automatisch aktuelle Farbdokumentation, die nie veraltet. Wenn das Farbschema in tailwind.config.js geändert wird, aktualisiert sich die Storybook-Dokumentation beim nächsten Build automatisch. Das ist das Versprechen eines lebendigen Design Systems: Dokumentation und Implementierung sind nie auseinander.

6. Dark Mode in Storybook testen

Wenn das Tailwind CSS Projekt Dark Mode über dark:-Klassen unterstützt, muss Storybook einen Weg bieten, zwischen Light und Dark Mode zu wechseln. Das Addon storybook-dark-mode fügt einen Toggle in die Storybook-Toolbar ein und wechselt die CSS-Klasse dark am <html>-Element. Da Tailwind CSS v3 im Klassen-basierten Dark Mode auf genau diese Klasse reagiert, funktioniert der Toggle direkt ohne weitere Konfiguration.

In der .storybook/preview.js wird das Addon konfiguriert: Welches Theme in Storybook selbst für Light und Dark Mode gilt (das Storybook-UI-Theme), und welche Klasse am Canvas-Element gesetzt wird. Für Tailwind CSS v3 mit darkMode: 'class' ist es wichtig, dass die Klasse am <html>-Element des Story-Canvas gesetzt wird, nicht am Canvas-Container selbst. Die Story sollte außerdem einen Dark-Mode-Hintergrund zeigen, damit die weißen Texte auf dunklem Hintergrund korrekt sichtbar sind.

7. Accessibility-Testing direkt in Storybook

Das Storybook-Addon @storybook/addon-a11y führt automatisch axe-core-Checks auf jede Story aus und zeigt Verstöße direkt in der Storybook-UI an. Für Tailwind CSS Komponenten ist das besonders wertvoll, weil Tailwind selbst keinerlei Aussagen über Barrierefreiheit macht – die Korrektheit von Farbkontrasten, ARIA-Attributen und Keyboard-Navigation liegt vollständig beim Entwickler. Das a11y-Addon prüft automatisch Kontrastverhältnisse der Tailwind-Farben, fehlende alt-Texte, falsche ARIA-Rollen und weitere WCAG-Verstöße.

Das Vorgehen für ein vollständiges Tailwind CSS Storybook Accessibility-Setup: Das Addon in main.js einbinden, eine Story mit einem bekannten Accessibility-Problem erstellen (z. B. ein Button ohne ARIA-Label), und beobachten, wie das Addon den Verstoß meldet. Danach das Problem beheben und sicherstellen, dass alle weiteren Stories die a11y-Checks bestehen. Die Checks können auch in eine CI-Pipeline integriert werden: npx storybook build && npx axe-core-storybook schlägt fehl, wenn eine Story einen kritischen Accessibility-Fehler enthält. Das macht Barrierefreiheit zu einem automatisierten Gate im Entwicklungsprozess.

8. Autodocs und MDX für vollständige Dokumentation

Storybook 8 bietet mit tags: ['autodocs'] in der Story-Metadaten eine automatische Dokumentationsseite für jede Komponente. Diese Seite zeigt alle Stories, alle Props mit ihren Typen und Standardwerten, und einen beschreibbaren Beschreibungstext. Für Tailwind CSS Komponenten ist das besonders nützlich, weil es den Prop-zu-Klassen-Mapping dokumentiert: Welche Props steuern welche Tailwind-Klassen? Welche Varianten gibt es? Das ist Dokumentation, die direkt aus dem TypeScript-Typen und den Story-ArgTypes generiert wird.

MDX-Dateien erlauben noch mehr Kontrolle: In einer Button.mdx-Datei kann Markdown-Text mit eingebetteten Stories kombiniert werden. Das ermöglicht es, Kontext, Verwendungsrichtlinien und Code-Beispiele direkt neben der interaktiven Story-Vorschau zu platzieren. Ein Abschnitt erklärt, wann welche Button-Variante zu verwenden ist. Ein weiterer zeigt, welche Tailwind-Klassen intern verwendet werden. Eine Tabelle dokumentiert alle Props. Das ist die vollständige Komponentendokumentation, die Designer und Entwickler gemeinsam nutzen können.

9. Storybook-Strategien für Tailwind im Vergleich

Es gibt verschiedene Ansätze, wie Tailwind CSS und Storybook zusammenarbeiten können. Die Wahl hängt von der Teamgröße, dem Framework und dem gewünschten Detailgrad der Dokumentation ab.

Der praktische Einstieg für ein bestehendes Tailwind CSS Storybook-Projekt: Zuerst die wichtigsten wiederverwendbaren Komponenten (Button, Badge, Card, Input) mit einfachen CSF-Stories und Autodocs dokumentieren. Dann Controls für die häufigsten Varianten hinzufügen. Das a11y-Addon von Anfang an einbinden – es kostet fast nichts und findet echte Probleme. MDX und Design-Token-Seiten dann ergänzen, wenn das Team gewachsen ist und Designer regelmäßig mit Storybook arbeiten.

10. Zusammenfassung

Tailwind CSS Storybook ist die Kombination, die aus einer Sammlung von Utility-Klassen ein dokumentiertes, testbares und für alle Teammitglieder sichtbares Design System macht. Das Setup beginnt mit dem Import der Tailwind CSS Hauptdatei in .storybook/preview.js und der korrekten PostCSS-Konfiguration in main.js. CSF-Stories mit Autodocs erzeugen automatisch Dokumentationsseiten. Storybook Controls machen Tailwind-Varianten interaktiv explorierbar. Das a11y-Addon prüft Barrierefreiheit automatisch auf jeder Story.

Der längerfristige Wert liegt in der Konsistenz: Wenn jede neue Tailwind CSS Komponente direkt in Storybook dokumentiert wird, verrottet die Dokumentation nicht. Designer können Komponenten direkt im Browser überprüfen. QA-Teams können Zustände ohne Testaufbau in der Applikation erkunden. Neue Entwickler finden alle Komponenten an einem Ort. Und wenn das Team wächst, kann das Storybook mit MDX-Seiten, Design-Token-Dokumentation und visuellen Regressionstests mit Chromatic erweitert werden – ohne die grundlegende Struktur ändern zu müssen.

11. FAQ: Tailwind CSS Storybook