Claude Code Storybook: Component-Driven Development, UI-Dokumentation und Design-Systeme mit KI

Wer schon einmal ein Storybook-Projekt von Grund auf aufgebaut hat, kennt das Ritual: Komponente schreiben, Story erstellen, Args definieren, Controls konfigurieren, Addons einrichten, Design Tokens verknüpfen — und das für jede einzelne Komponente. Bei einem ernsthaften Design-System mit hundert Komponenten multipliziert sich dieser Aufwand sehr schnell in Bereiche, die keine einzelne Entwicklerin mehr sinnvoll verwalten kann.

Claude Code Storybook ändert das nicht durch Magie, sondern durch eine einfache Verschiebung: der Kontextaufbau passiert einmal, nicht hundertmal. Claude Code liest deine bestehenden Komponenten, versteht ihre Props-Interfaces, sieht deine Design-Token-Struktur und generiert daraus vollständige, nutzbare Stories — nicht als Template-Füller, sondern als echte Dokumentation, die dein Storybook tatsächlich besser macht.

Dieser Artikel zeigt den konkreten Workflow: von der ersten Story bis zum vollständig konfigurierten Design-System mit Chromatic-Integration.

1. Was Claude Code bei Storybook wirklich bringt

Storybook ist seit Jahren das Standardwerkzeug für component-driven Development. Es isoliert Komponenten aus dem Anwendungskontext, macht sie unabhängig entwickelbar und dokumentiert sie gleichzeitig. Das Problem: eine gute Story zu schreiben ist fast so viel Arbeit wie die Komponente selbst. Und schlechte Stories — die nur den Default-State zeigen — helfen niemandem.

Claude Code löst genau dieses Problem: Es liest die Komponente vollständig, analysiert alle Props und ihre TypeScript-Typen, erkennt welche Kombinationen sinnvoll sind, und generiert Stories die tatsächlich die relevanten Zustände abdecken. Nicht nur Default und Primary, sondern auch Disabled, Loading, ErrorState, LongTextEdgeCase — die Zustände, die im echten Betrieb auftreten und die man manuell meistens übersieht.

2. Die erste Story generieren

Das einfachste Einstiegsszenario: eine bestehende Komponente hat noch keine Story, oder nur eine rudimentäre. Claude Code generiert eine vollständige Story-Datei inklusive Args, Controls und sinnvollen Varianten.

claude "Schreib eine vollständige Storybook-Story für die Button-Komponente in
src/components/Button/Button.tsx. Nutze CSF3-Format, definiere sinnvolle
Varianten und konfiguriere Args so dass alle Props über Controls steuerbar sind."

Claude Code liest daraufhin Button.tsx, analysiert das TypeScript-Interface und gibt eine vollständige Story-Datei zurück. Typisches Ergebnis:

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'UI/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost', 'danger'],
      description: 'Visuelle Variante des Buttons',
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
    disabled: {
      control: 'boolean',
    },
    loading: {
      control: 'boolean',
      description: 'Zeigt einen Lade-Spinner und deaktiviert den Button',
    },
    onClick: { action: 'clicked' },
  },
};

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

export const Default: Story = {
  args: {
    children: 'Button',
    variant: 'primary',
    size: 'md',
  },
};

export const AllVariants: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap' }}>
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="danger">Danger</Button>
    </div>
  ),
};

export const LoadingState: Story = {
  args: {
    children: 'Wird gespeichert...',
    variant: 'primary',
    loading: true,
  },
};

export const Disabled: Story = {
  args: {
    children: 'Nicht verfügbar',
    disabled: true,
  },
};

export const LongLabel: Story = {
  args: {
    children: 'Sehr langer Button-Text der umbricht oder abschneidet',
    variant: 'primary',
    size: 'md',
  },
};

Diese Story wäre manuell in 20–30 Minuten entstanden. Mit Claude Code sind es zwei Minuten — und die Story ist vollständiger als das, was man unter Zeitdruck üblicherweise schreibt, weil Claude Code keine Lust auf Shortcuts hat.

3. Args und Controls richtig konfigurieren

Die echte Stärke von Storybook Controls liegt in der interaktiven Dokumentation: jemand öffnet die Story, verändert die Werte in der Controls-Sidebar und sieht sofort, wie die Komponente reagiert. Das funktioniert nur, wenn argTypes sorgfältig konfiguriert sind — mit den richtigen Control-Typen, beschreibenden Labels und sinnvollen Standardwerten.

Claude Code generiert diese Konfiguration aus dem TypeScript-Interface der Komponente. Für ein komplexeres Formular-Element könnte das so aussehen:

claude "Konfiguriere argTypes für die Select-Komponente in
src/components/Select/Select.tsx so dass alle Props korrekt typisiert und
mit sinnvollen Controls ausgestattet sind. Nutze die TypeScript-Typen
als Grundlage."

Claude Code liest das Interface und liefert eine präzise argTypes-Konfiguration:

argTypes: {
  options: {
    control: 'object',
    description: 'Array von { value: string, label: string, disabled?: boolean }',
    table: {
      type: { summary: 'SelectOption[]' },
    },
  },
  value: {
    control: 'text',
    description: 'Aktuell selektierter Wert (controlled)',
  },
  placeholder: {
    control: 'text',
    defaultValue: 'Bitte wählen...',
  },
  multiple: {
    control: 'boolean',
    description: 'Erlaubt Mehrfachauswahl',
  },
  searchable: {
    control: 'boolean',
    description: 'Zeigt ein Suchfeld im Dropdown',
  },
  maxHeight: {
    control: { type: 'number', min: 100, max: 600, step: 50 },
    description: 'Maximale Höhe der Dropdown-Liste in Pixeln',
  },
  onChange: { action: 'changed' },
  onSearch: { action: 'searched' },
},

Der Unterschied zur Standard-Autokonfiguration von Storybook: Claude Code wählt den semantisch passenden Control-Typ. Ein numerischer maxHeight-Wert bekommt einen Slider mit sinnvollen Grenzen, kein freies Textfeld. Eine Union-Type-Prop bekommt ein Radio-Control wenn es wenige Optionen sind, ein Select-Control wenn es viele sind. Das sind Details, die Storybook nicht automatisch richtig macht — aber Details, die den Unterschied zwischen einem nützlichen und einem unbedienlichen Storybook ausmachen.

4. Design Tokens ins Storybook integrieren

Ein Design-System ohne korrekte Token-Integration ist nur halbe Arbeit. Wenn die Storybook-Vorschau andere Farben oder Abstände zeigt als die echte Anwendung, ist die Dokumentation nutzlos — oder schlimmer: irreführend.

Claude Code kann die Token-Integration aus einer bestehenden Token-Definition aufbauen. Ob das CSS Custom Properties, ein JavaScript-Objekt oder ein Design-Token-Format wie Style Dictionary ist, spielt keine Rolle: Claude Code liest die Quelle und richtet Storybook so ein, dass die Token korrekt geladen werden.

claude "Integriere unsere Design Tokens aus src/tokens/tokens.json in Storybook.
Die Tokens sollen in preview.ts geladen werden und in allen Stories verfügbar
sein. Erstelle außerdem einen Token-Browser-Story der alle Farb- und
Abstandswerte visualisiert."

Claude Code liest tokens.json, erstellt die passende preview.ts-Konfiguration und generiert eine DesignTokens.stories.tsx, die alle Tokens visuell darstellt — eine Art lebendige Style-Guide-Seite direkt in Storybook:

// .storybook/preview.ts
import '../src/tokens/tokens.css'; // generiert von Style Dictionary

export const parameters = {
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: 'var(--color-bg-primary)' },
      { name: 'dark', value: 'var(--color-bg-inverse)' },
      { name: 'brand', value: 'var(--color-brand-500)' },
    ],
  },
};

// src/stories/DesignTokens.stories.tsx
import type { Meta } from '@storybook/react';
import tokens from '../tokens/tokens.json';

const meta: Meta = {
  title: 'Design System/Tokens',
  parameters: { layout: 'fullscreen' },
};
export default meta;

export const Colors = () => (
  <div style={{ padding: '2rem' }}>
    <h2>Farbpalette</h2>
    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(160px, 1fr))', gap: '1rem', marginTop: '1rem' }}>
      {Object.entries(tokens.color).map(([name, value]) => (
        <div key={name}>
          <div style={{ background: String(value), height: 64, borderRadius: 8, border: '1px solid rgba(0,0,0,0.1)' }} />
          <code style={{ fontSize: 12 }}>{name}</code>
          <p style={{ fontSize: 12, color: '#666' }}>{String(value)}</p>
        </div>
      ))}
    </div>
  </div>
);

5. Addons konfigurieren und erweitern

Storybook lebt von seinen Addons: Accessibility-Checks mit @storybook/addon-a11y, Viewport-Tests mit @storybook/addon-viewport, Interaktionstests mit @storybook/addon-interactions. Jedes Addon erfordert Konfiguration — sowohl global in main.ts als auch oft auf Story-Ebene.

Claude Code richtet diese Konfigurationen ein und ergänzt bestehende Stories mit den passenden Addon-Parametern:

claude "Konfiguriere @storybook/addon-a11y für unser Storybook und ergänze
alle bestehenden Stories in src/components/ mit sinnvollen a11y-Parametern.
Für Komponenten die von Haus aus barrierefreiheitsrelevant sind (Formulare,
Navigation, Modals) erstelle zusätzliche a11y-spezifische Varianten."

Das Ergebnis: nicht nur die Konfiguration in main.ts, sondern auch Stories wie diese:

export const WithScreenReaderLabel: Story = {
  args: {
    placeholder: 'Suchen...',
    'aria-label': 'Globale Suche',
  },
  parameters: {
    a11y: {
      config: {
        rules: [
          {
            id: 'label',
            enabled: true,
          },
        ],
      },
    },
  },
};

export const KeyboardNavigation: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const input = canvas.getByRole('searchbox');
    await userEvent.tab();
    await expect(input).toHaveFocus();
    await userEvent.type(input, 'Test');
    await expect(input).toHaveValue('Test');
  },
};

Interaktionstests mit play-Funktionen

Die play-Funktion ist eine der mächtigsten Storybook-Features — und eine der am meisten unterschätzten. Sie erlaubt es, Interaktionssequenzen zu definieren, die direkt in Storybook ablaufen: Klicks, Tastatureingaben, Assertions. Das ist Storybook als Testumgebung.

Claude Code generiert diese Interaktionstests präzise, weil es die Komponente kennt und versteht, welche Interaktionen sinnvoll sind:

claude "Schreib play-Funktionen für die Form-Komponente in
src/components/Form/Form.tsx. Die Tests sollen: Submit mit validen Daten,
Submit mit invaliden Daten, und das Verhalten bei Netzwerkfehler abdecken."

export const SuccessfulSubmit: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByLabelText('E-Mail'), 'user@example.com');
    await userEvent.type(canvas.getByLabelText('Passwort'), 'sicheres-passwort-123');
    await userEvent.click(canvas.getByRole('button', { name: /anmelden/i }));

    await waitFor(() => {
      expect(canvas.getByText('Erfolgreich angemeldet')).toBeInTheDocument();
    });
  },
};

export const ValidationErrors: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.click(canvas.getByRole('button', { name: /anmelden/i }));

    await waitFor(() => {
      expect(canvas.getByText('E-Mail ist erforderlich')).toBeInTheDocument();
      expect(canvas.getByText('Passwort ist erforderlich')).toBeInTheDocument();
    });
  },
};

6. Chromatic-Integration einrichten

Chromatic ist der de-facto Standard für visuelles Testing in Storybook-Projekten. Es erstellt Snapshots jeder Story, vergleicht sie bei Änderungen und zeigt visuelle Diffs im Pull-Request-Prozess. Der Aufwand für die Einrichtung ist überschaubar — aber die Integration in den CI-Prozess erfordert etwas Konfigurationsarbeit.

claude "Richte Chromatic-Integration für unser Storybook ein. Erstelle:
1. GitHub Actions Workflow der Chromatic bei jedem PR ausführt
2. Konfiguration für Baseline-Updates bei Merges in main
3. Sinnvolle Ignore-Regeln für Komponenten die sich absichtlich dynamisch verhalten
4. Dokumentation welche Stories getestet werden und welche ausgeschlossen sind"

Claude Code liest die bestehende GitHub Actions Konfiguration (falls vorhanden), die package.json und die Storybook-Konfiguration und erstellt einen vollständigen Workflow:

# .github/workflows/chromatic.yml
name: Chromatic Visual Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  chromatic:
    name: Visual Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Publish to Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          buildScriptName: build-storybook
          onlyChanged: true
          exitZeroOnChanges: true
          autoAcceptChanges: main

Die onlyChanged: true-Option ist entscheidend: Chromatic testet nur Stories, die von den aktuellen Änderungen betroffen sind — was die Testzeit bei großen Storybooks drastisch reduziert.

Stories von Chromatic ausschließen

Nicht alle Stories sollten in Chromatic getestet werden. Animationen, randomisierte Inhalte, Komponenten mit externen API-Abhängigkeiten — diese werden als "flaky" markiert und stören den Review-Prozess. Claude Code kann diese Ausnahmen systematisch identifizieren:

claude "Analysiere alle Stories in src/ und identifiziere welche für Chromatic
ungeeignet sind (Animationen, zufällige Inhalte, API-Abhängigkeiten).
Füge diesen Stories den chromatic.disableSnapshot Parameter hinzu
und erkläre warum."

// Animierte Komponente - visuelle Änderungen sind beabsichtigt
export const AnimatedTransition: Story = {
  parameters: {
    chromatic: {
      disableSnapshot: true,
      // Grund: CSS-Transitions erzeugen inkonsistente Snapshots
      // je nach Rendering-Timing
    },
  },
};

7. Vollständiges Design-System dokumentieren

Der häufigste Blocker bei der Storybook-Einführung ist nicht die technische Hürde, sondern der Aufwand: ein Design-System mit 80 Komponenten vollständig zu dokumentieren bedeutet 80 mal das gleiche Ritual — Story erstellen, Args konfigurieren, Varianten schreiben, Controls einrichten. Mit Claude Code wird aus diesem Ritual ein einziger Batch-Prozess.

claude "Erstelle vollständige Storybook-Stories für alle Komponenten in
src/components/. Gehe Verzeichnis für Verzeichnis vor. Für jede Komponente:
1. Analysiere alle Props und ihre Typen
2. Erstelle mindestens 4 sinnvolle Story-Varianten
3. Konfiguriere argTypes vollständig
4. Füge JSDoc-Kommentare für die autodocs-Generierung hinzu
Beginne mit den Atom-Komponenten (Button, Input, Badge) und arbeite dich
zu den zusammengesetzten Komponenten vor."

Claude Code arbeitet das Verzeichnis systematisch ab. Bei jedem Schritt liest es die Komponente, generiert die Story und erklärt kurz, warum es welche Varianten gewählt hat. Der Output ist keine generische Vorlage — jede Story ist spezifisch für die jeweilige Komponente.

8. Stories reviewen und verbessern lassen

Claude Code ist nicht nur ein Generator, sondern auch ein Review-Partner. Bestehende Stories, die unvollständig oder veraltet sind, können systematisch verbessert werden:

claude "Reviewe alle Stories in src/components/Form/ und prüfe:
1. Werden alle relevanten Zustände abgedeckt?
2. Sind die argTypes vollständig konfiguriert?
3. Gibt es Edge Cases die fehlen?
4. Stimmen die Stories noch mit der aktuellen Komponenten-Implementierung überein?
Gib für jede Story eine Einschätzung und konkrete Verbesserungsvorschläge."

Das Ergebnis ist eine strukturierte Analyse jeder Story-Datei, mit konkreten Änderungsvorschlägen. Dieser Review-Prozess ist besonders wertvoll nach größeren Refactorings: Claude Code kann schnell feststellen, welche Stories durch Änderungen am Komponenten-Interface inkompatibel geworden sind.

"InputField.stories.tsx: Die Story 'WithError' übergibt noch den alten Prop-Namen 'errorText', der in v2.3 zu 'error' umbenannt wurde. Die Story rendert zwar noch, zeigt aber keinen Fehler mehr. Außerdem fehlt eine Story für den neuen 'helperText'-Prop."

9. Storybook-Konfiguration optimieren

Eine oft übersehene Aufgabe: die Performance des Storybooks selbst. Bei großen Design-Systemen mit vielen Stories und statischen Assets wird die Build-Zeit schnell zum Problem. Claude Code kann die Konfiguration analysieren und optimieren:

claude "Analysiere unsere Storybook-Konfiguration in .storybook/ und
identifiziere Performance-Probleme. Wir haben 200+ Stories und der Build
dauert über 4 Minuten. Was kann optimiert werden?"

Typische Optimierungen die Claude Code vorschlägt und umsetzt:

• Lazy Loading für Addons: Schwere Addons nur laden wenn sie wirklich gebraucht werden
• Story-Indexierung: storyStoreV7 aktivieren für on-demand Kompilierung
• Asset-Optimierung: Große statische Assets in externe CDN auslagern statt in den Build einzuschließen
• Split-Chunks: Webpack-Konfiguration für besseres Code-Splitting bei vielen Komponenten
• TypeScript-Incremental: tsBuildInfoFile für schnellere Neukompilierung

10. Muster aus der Praxis

Drei konkrete Situationen, in denen Claude Code Storybook-Arbeit signifikant beschleunigt hat:

Situation 1: Migration von Storybook v6 auf v7. Das neue CSF3-Format, neue Addons, geänderte API. Claude Code liest alle bestehenden Stories im alten Format und migriert sie automatisch ins neue — inklusive der Umstellung von storiesOf auf export default und der Anpassung aller parameters-Strukturen. Was manuell zwei Tage gedauert hätte, war in zwei Stunden fertig.

Situation 2: Neue Entwicklerin ins Team einarbeiten. Statt die Storybook-Konventionen im Wiki zu dokumentieren, wurde Claude Code als lebendige Dokumentation genutzt. Neue Entwicklerin beschreibt eine Komponente, Claude Code zeigt wie die Story nach den Teamkonventionen aussehen sollte — inklusive der projektspezifischen Namenskonventionen und den Addon-Konfigurationen die im Projekt Standard sind.

Situation 3: Design-System-Audit. Vor einer Designüberarbeitung: Claude Code analysiert alle Stories und erstellt eine Übersicht aller Zustände und Varianten, die aktuell dokumentiert sind. Diese Übersicht wurde als Grundlage für das Design-Review genutzt — um zu sehen, welche Zustände das Design abdecken muss.

Weiterführende Artikel zu verwandten Themen:

• Claude Code TypeScript — TypeScript-Typen generieren, Interfaces definieren, Generics verstehen
• Claude Code Testing — Unit-Tests, Integrationstests und E2E mit Claude Code automatisieren