Yosegi — Bildschirm-UI aus Storybook-Komponenten zusammensetzen

Yosegi — Bildschirme aus den eigenen Komponenten eines Hosts erstellen

Version: 2026-08-13. Ein Agenten-Harness kann eine veraltete Kopie eines Skills laden, ohne dies zu erwähnen. Wenn dieses Datum älter ist als das im Repository unter skills/yosegi/SKILL.md, liest du eine veraltete Kopie – installiere sie erneut, bevor du fortfährst.

Yosegi verwandelt die Komponenten eines Host-Projekts in Fakten, aus denen du einen Bildschirm erstellen kannst, und gibt den Bildschirm als Story (CSF) zur Überprüfung aus, bevor etwas implementiert wird. Es hat weder eine eigene Rendering-Umgebung noch eine GUI; du überprüfst das Aussehen im Storybook des Hosts. Auf einem Host ohne Storybook wird das Ergebnis zu einer einfachen React-Komponentendatei (--target component) – der Zweig Schritt 1 unten zeigt, wie sich das Verfahren ändert.

Dieses Dokument ist das Verfahren, und du bist derjenige, der es ausführt. Die CLI (und die entsprechenden MCP-Tools) sind die Werkzeuge, die es dafür verwendet.

Wann es verwendet wird

• Erstellen eines Bildschirmvorschlags oder UI-Mocks aus einem vorhandenen Designsystem in einer überprüfbaren Form.
• Erstellen eines ersten Entwurfs eines neuen Bildschirms, der in Storybook sichtbar ist, bevor er implementiert wird.
• Nachschlagen, welche Komponenten ein Host hat und welche Props sie wirklich erwarten, bevor UI geschrieben wird.
• Umsetzen eines genehmigten Mock-Storys in eine echte Seite. Führe die Schritte 1 und 2 aus und springe dann zu Schritt 5.

Nicht geeignet für: Einmalige Komponentenänderungen.

Wo der Wert liegt

Die Aufgabe der Registry ist eng gefasst: Sie ist die Quelle der Wahrheit für die Props einer Komponente – die tatsächlichen Prop-Namen, die tatsächlichen Enum-Optionen, welche erforderlich sind, welche Slots im Vergleich zu Children sind, die Aufrufsignatur einer Funktion als Prop. Die Komponenten eines Hosts sind nicht die Bibliothek, von der sie abgeleitet wurden. Ihre Varianten-Enums wurden umbenannt, ihre Größenskalen unterscheiden sich zwischen Geschwistern, eine Icon-Prop erwartet eine Komponentenreferenz statt eines Elements, eine ReactNode-Prop ist ein benannter Slot statt Children, und drei verschiedene Komponenten teilen sich einen Exportnamen. Nichts davon ist durch Vertrautheit mit React oder der übergeordneten Bibliothek ableitbar, und jeder dieser Punkte ist ein Fehler, den du ausliefern wirst, wenn du die Prop schreibst, die du erwartest, anstatt der Prop, die laut Registry existiert. Dafür sind die inspect-Aufrufe in den Schritten 1 und 2 da, und sie zu überspringen ist der Weg, wie ein plausibel aussehender Mock einen Fehler ausliefert.

Die Registry gibt dir nicht das Grundgerüst des Bildschirms, das Kompositions-Idiom oder das Layout – der Grid-Bibliotheks-Hook-Aufruf, der eine DataGrid antreibt, ein hostspezifisches meta wie { stickyHeader: true }, welchen Wrapper eine Komponente um sich herum erwartet. Das kommt aus den eigenen Stories des Hosts und, auf einem Host mit einem Seiten-/Routen-Generator, aus seinen Beispielvorlagen (Schritt 2). Je reichhaltiger die Vorlagen- und Story-Abdeckung des Hosts ist, desto geringer ist der Anteil der Registry an dem, was du tatsächlich zum Erstellen des Bildschirms benötigt hast – und das ist kein Manko. Die Registry und die eigenen Beispiele des Hosts beantworten unterschiedliche Fragen, und beide sind tragend für die Frage, die sie beantworten.

Referenzen

Öffne diese, wenn der Schritt unten dich darauf verweist, nicht vorbeugend. Auf dem 3a-Weg (schreibe die Story direkt) kann das nie sein: registry status und die Ausgabe von component inspect zusammen mit dem Text dieser Datei sind normalerweise selbsterklärend genug, um den gesamten Bildschirm zu erstellen. Sobald du aber eine brauchst, arbeite mit ihr und nicht aus dem Gedächtnis dieser Datei allein – ihre Details werden hier nicht wiederholt.

Datei	Lies sie, wenn …
references/registry.md	Die Ausgabe von inspect etwas enthält, das du nicht interpretieren kannst – eine undurchsichtige shape: / signature:-Zeile einer Prop, eine undokumentierte Prop, ein Importspezifizierer, der falsch aussieht
references/cli.md	Ein Befehl oder Flag nicht oben abgedeckt ist, die CLI nicht läuft oder du die MCP-Entsprechungen benötigst
references/screen-json.md	Nur wenn du den Screen-JSON-Weg nimmst (3b). Das Format und was es nicht ausdrücken kann
references/errors.md	Sobald ein Befehl einen Fehler oder eine Warnung ausgibt. Jeder Code und seine Behebung
references/implementation.md	Für die Meta-Vorlage in Schritt 3 und vor Schritt 5

Schritt 1. Erstelle die Registry

Yosegi benötigt eine lesbare tsconfig.json vom Host (Props kommen aus den TypeScript-Typen, und das allein reicht). Storybook ist der Ort, an den die Story geht und wo du bestätigst, wie sie rendert – es ist jedoch keine Voraussetzung.

Wenn du Storybook nicht erkennen kannst – kein .storybook/- (oder äquivalentes) Konfigurationsverzeichnis, kein storybook-Skript in der package.json des Hosts, keine index.json, auf die --index verweisen kann – ist das Ergebnis eine einfache React-Komponentendatei anstelle einer Story (screen generate --target component, references/cli.md). Wähle den Ausgabeort oder die Überprüfungsmethode nicht selbst aus: Frage den Benutzer, bevor du etwas baust, (a) wohin die Komponentendatei soll und (b) wie er das Ergebnis bestätigen möchte (z. B. durch Rendern auf einer Test-Route der Host-App). Yosegi schreibt die Überprüfungsoberfläche nicht vor, und das Erraten einer der Antworten verstößt gegen dieselbe Regel wie das Erraten einer Prop. Mit diesen Antworten bleibt das Verfahren unten gleich, mit drei Unterschieden: registry build läuft ohne --index / --storybook-url (du verlierst die Kuratierung, sonst nichts); auf Weg 3a schreibst du die Komponentendatei an den vom Benutzer genannten Ort, und auf 3b übergibst du --target component --out <dieser Ort>.tsx; und die Storybook-Überprüfungen in Schritt 4 werden durch den Typtest des Hosts plus die vom Benutzer genannte Bestätigungsmethode ersetzt.

1. Kannst du die CLI ausführen? npx yosegi (oder pnpm yosegi, yarn yosegi, bunx yosegi) ohne Argumente gibt jeden Befehl aus, sobald @yosegi/yosegi bereits eine Abhängigkeit des Hosts ist – installiere es zuerst, wenn nicht (references/cli.md). Node.js 20 oder neuer, React + TypeScript als Host. Wenn der Befehl stattdessen fehlschlägt, siehe „Wenn die CLI nicht läuft“ in references/cli.md; der nützlichste Schritt ist, <data-dir>/registry.json's builtWithCliPath zu lesen, wenn bereits eine Registry aus einer früheren Sitzung existiert.
2. Lege jetzt ein --data-dir fest und übergib bei jedem Befehl dasselbe. Verwende .yosegi unter dem Paketstamm des Hosts, was auch der Standard ist; die Beispiele unten schreiben es trotzdem aus, weil der Standard deinem aktuellen Arbeitsverzeichnis folgt und ein von woanders ausgeführter Befehl nicht finden wird, was du erstellt hast.
3. Gibt es bereits eine Registry, und ist sie aktuell? Führe zuerst yosegi registry status --data-dir .yosegi aus – es berechnet die Version der Registry aus ihren eigenen aufgezeichneten Eingaben neu und meldet source: current oder source: stale mit dem genauen Neuerstellungsbefehl, anstatt dass du die Kopfzeile von component list selbst überprüfen musst. „Registry nicht gefunden“ bedeutet, dass dies der erste Durchlauf ist. Die Storybook-Index-Hälfte ist eine Best-Effort-Information und kann den Index als nicht erreichbar melden, während die Quellenaussage noch gültig ist – lies diese Hälfte als „konnte nicht überprüft werden“, nicht als „veraltet“ oder „aktuell“, und lass nicht zu, dass ein nicht erreichbarer Dev-Server dich daran hindert, einem current-Quellenurteil zu vertrauen. Baue neu, wenn status „stale“ meldet, wenn etwas REGISTRY_VERSION_MISMATCH ausgegeben hat oder wenn status source: unknown meldet, weil die Registry älter als die aufgezeichneten Eingaben ist (built: not recorded) – es gibt nichts, von dem aus neu berechnet werden kann, also ist das Alter das einzige Signal, das du hast. Baue auch neu, wenn ein Befehl warnt, dass die Registry mit einer anderen Yosegi-Version erstellt wurde als der, die du ausführst: Eine ältere Yosegi kann keine Felder ausgeben, die diese kann (z. B. die Aufrufsignaturen einer Funktions-Prop), und kein anderes Signal zeigt diese Lücke – der Versionsstring, der ein Inhalts-Hash ist, bleibt identisch, also behält eine aus einem unveränderten Host neu erstellte Registry denselben. Die Registry ist ein Schnappschuss, und ein veralteter ist schlimmer als keiner.

yosegi registry build \
  --source "app/components/**/*.tsx" \
  --tsconfig <host>/tsconfig.json \
  --index http://localhost:6006/index.json \
  --storybook-url http://localhost:6006 \
  --report tmp/registry-report.json \
  --data-dir .yosegi

6006 oben ist der Standardwert von Storybook, der nur verwendet wird, weil dies der erste Build ist und dir noch nichts anderes mitgeteilt wurde – es ist nicht unbedingt der Port des Hosts. Überprüfe das package.json-Storybook-Skript des Hosts (oder frage nach) nach dem Port, auf dem es tatsächlich läuft, bevor du dies ausführst. Jeder Neubau nach diesem ersten hat eine bessere Quelle als Raten: Die Kopfzeile von component list gibt eine rebuild:-Zeile aus, die die genaue --storybook-url trägt, mit der die Registry zuletzt erstellt wurde (references/cli.md).

Flags und Standardwerte findest du in references/cli.md. --index ist der Teil mit einer Voraussetzung: Eine Dev-Server-URL bedeutet, dass das Storybook des Hosts bereits laufen muss. Ohne sie verlierst du die Story-abgeleiteten Kategorien und die recommended-Markierungen, sonst nichts.

Lies die Statistiken, die es ausgibt:

• files: 0 → der Glob hat nichts gefunden. Der Befehl wird trotzdem erfolgreich ausgeführt und schreibt eine Registry, die nur die drei synthetischen Primitive enthält, lies „Wrote 3 components” also nicht als Erfolg.
• componentCandidates: 0 bei positiven files, oder withNodeSlots: 0 bei einem hohen anyShapedProps → Der Build ist degradiert, obwohl er erfolgreich war. Ersteres bedeutet, dass der Glob keine React-Komponenten abgedeckt hat; Zweiteres bedeutet, dass @types/react nicht aufgelöst wurde, sodass jede ReactNode-Prop zu json abgeflacht wurde und keine Slots erkannt wurden. Eine Warning:-Zeile nennt in beiden Fällen die Lösung – behebe sie und baue neu, bevor du fortfährst.
• propsUnreadable hoch im Verhältnis zu extractedComponents → die tsconfig ist wahrscheinlich falsch. Behebe es jetzt (references/cli.md, registry metadata); eine Komponente in diesem Zustand lehnt später völlig reale Props ab.

Schritt 2. Jede Komponente nachschlagen, die du verwenden möchtest

Wenn die Beispielvorlage eines Seiten-/Routen-Generators die beste Übereinstimmung für den Bildschirm ist, den du baust, lies sie zuerst oder parallel zu den folgenden Befehlen – sie bestimmt das Grundgerüst und das Kompositions-Idiom, und die Registry bestätigt dann die genauen Props, die die Vorlage offen lässt.

yosegi component list --category app/components/ui --data-dir .yosegi
yosegi component list --query card --data-dir .yosegi
yosegi component inspect "app/components/ui/button#Button" --data-dir .yosegi

Die Registry kann mehrere hundert Einträge umfassen, also grenze mit --category / --query ein, verschaffe dir einen Überblick aus der Zusammenfassung und führe dann inspect für jede Komponente aus, die du schreiben wirst. inspect ist maßgeblich, und dein Framework-Wissen ist es nicht. Lese references/registry.md, um zu verstehen, wie du das, was es dir gibt, lesen musst – die Enum-Optionen, die shape:- und signature:-Zeilen unter einer undurchsichtigen Prop, den Importspezifizierer, den der Host tatsächlich schreibt, und was eine undokumentierte Prop bedeutet.

Bevorzuge Komponenten, die mit recommended markiert sind; sie haben eine eigene Story.

Sammle dann die Konventionen des Hosts. Die Story landet im Repository des Hosts und wird als Code des Hosts überprüft; das Überspringen führt zu einer UI, die funktioniert und trotzdem zurückgeschickt wird.

• Finde den Datenvertrag, falls bereits vorhanden – eine OpenAPI/JSON-Schema-Definition, ein GraphQL-Schema, handgeschriebene TypeScript-Typen für die API-Antwort, welche Form die Datenschicht des Hosts auch immer verwendet. Lese ihn, bevor du Mock-Daten erfindest. Er entscheidet über mehr als nur die Komponenten-Props: welche Felder erforderlich gegenüber nullable sind und was null für ein bestimmtes Feld bedeutet (ein null-Limit kann „unbegrenzt“ bedeuten, nicht „unbekannt“), welche Felder sich gegenseitig ausschließen und – genauso nützlich – was nicht da ist (kein Sortier- oder Suchfeld im Vertrag bedeutet, dass der Bildschirm auch keines erfinden sollte). Dies verwandelt den Mock von einem Look-and-Feel-Vorschlag in etwas, das die tatsächliche Datenform widerspiegelt. Wo er lebt, variiert je nach Host (openapi/schemas/, eine .graphql-Datei, eine generierte types.ts); finde, was für diese Domäne existiert, und folge ihm anstelle einer plausibel aussehenden Vermutung.
• Durchsuche das Routen-/Seitenverzeichnis des Hosts (app/routes/ oder wo auch immer Seiten bereitgestellt werden) nach einem vorhandenen Bildschirm in derselben Domäne. In einem ausgereiften Produkt existiert oft einer, und das Finden kann die Aufgabe völlig neu definieren – zum Beispiel könnte eine vorhandene bookings.calendar._index-Route „einen Buchungsbildschirm erstellen“ in „eine übergreifende Liste gegen den vorhandenen Buchungsablauf vorschlagen“ verwandeln. Dies bestimmt, ob der Mock, um den du gebeten wurdest, überhaupt das Richtige zum Bauen ist, also führe es vor dem folgenden Kontrollpunkt durch und lass es die Fragen formen, die du dort stellst.
• Führe git status aus und überprüfe das Ausgabeverzeichnis, bevor du etwas baust. Ein früherer, nicht festgeschriebener Versuch desselben Bildschirms kann bereits im Arbeitsbaum liegen – häufig nach einem Kontext-Reset und einer erneuten Anfrage. Gleiche ihn ab, anstatt ein Duplikat daneben zu erstellen. Um eine bereits vorhandene Datei neu zu erstellen – ein Host-Generator weigert sich, wenn der Zielpfad existiert, oder ein früherer Versuch muss ersetzt werden – verschiebe sie zur Seite (umbenennen), anstatt sie zu löschen; Löschen steht dir möglicherweise nicht zur Verfügung, und eine Umbenennung räumt den Pfad in beiden Fällen.
• Überprüfe, ob der Host einen Generator für neue Seiten oder Bildschirme hat – einen plop-/hygen-Generator, ein bun add-route-ähnliches Skript, oft dokumentiert in der AGENTS.md des Hosts oder einem package.json-Skript. Auf einem Host mit einem solchen Generator ist das manuelle Schreiben einer neuen Bildschirmdatei von Grund auf falsch: Der Generator klont die genehmigte Vorlage und erzwingt die Datei- und Namenskonventionen, führe ihn also aus, anstatt die Datei selbst zu erstellen. Dies klärt auch die Wahl in Schritt 3 zwischen einer Inline-Tree-Story und einem Seitenmodul plus einer dünnen Wrapper-Story – ein Host mit einem solchen Generator möchte fast immer Letzteres.
• Lese AGENTS.md / CLAUDE.md auf jeder Ebene vom Repository-Stamm bis zum Ausgabeverzeichnis und befolge jedes Dokument, auf das sie verweisen.
• Lese eine oder zwei vorhandene Stories in der Nähe des Ausgabeorts. Zusammengesetzte Beispiele, die mehrere Komponenten kombinieren, sind die, die es nachzuahmen lohnt, für das Seitengerüst, den Abstand und die Komponentenauswahl. Für das Kompositions-Idiom – wie eine Komponente tatsächlich zusammengesetzt wird, nicht nur, welche Props sie nimmt: der Grid-Bibliotheks-Hook-Aufruf, der eine DataGrid antreibt, ein hostspezifisches meta wie { stickyHeader: true }, der Wrapper, den eine Komponente um sich herum erwartet – eine vorhandene Story ist die Quelle der Wahrheit, und die Registry ist es nicht. Die Registry …

[… abgeschnitten für die Übersetzung]

Der vollständige Inhalt ist im Quelltext verfügbar.