kvyatkovskys/swiftui-component-preview

SwiftUI-Komponentenvorschau

Erstellen Sie eine Komponentendarstellung aus einer kleinen, deterministischen SwiftUI-Fixture. Erfordert macOS 14 oder höher und Xcode 15 oder höher (Swift 5.9+); Swift 6 ist nicht erforderlich. Für das Projekt-Onboarding, die HTML-Galerie und den Live-Builder wird zusätzlich Python 3.8 oder höher (nur Standardbibliothek) benötigt. Wählen Sie PNGs für die statische Inspektion, die Galerie für Bildvergleiche oder ein natives Fenster für echte Fixture-Interaktionen. Diese Hilfsmittel bieten kein Xcode Canvas oder Hot Reload.

Ausgabe auswählen

Legen Sie die Ausgabe fest, bevor Sie etwas erstellen, in dieser Reihenfolge:

1. Explizites Wort. Wenn die Anfrage oder die Argumente der Fertigkeit mit png, gallery oder live beginnen oder diese benennen (auch „Screenshot“, „Rendern“ für PNG; „Fenster“, „Interaktiv“ für Live), verwenden Sie dieses.

2. Absicht der Anfrage.

   Der Benutzer möchte	Ausgabe
   sehen, wie es aussieht, Layout, Abstände, Text, einen Zustand, ein Gebietsschema überprüfen	PNG
   hell und dunkel vergleichen, oder gerahmt und ungerahmt, nebeneinander oder durch Umschalten	Galerie
   klicken, tippen, umschalten, navigieren, ein Sheet oder einen Alert öffnen, einen Ablauf überprüfen	Live-Fenster

   Wenn eine Anfrage mehr als eine Zeile betrifft, gewinnt die Interaktion: Alles, was erst nach einem Klick oder einer Eingabe erscheint, benötigt das Live-Fenster.

3. Gesamter Bildschirm oder Ablauf, kein Signal. Wenn das Ziel ein gesamter Bildschirm oder ein mehrstufiger Ablauf ist und keine der obigen Regeln zutrifft, wie bei „Vorschau des Checkout-Bildschirms“, stellen Sie eine Frage, die PNG, Galerie und Live-Fenster anbietet.

4. Standard. Für eine einzelne Komponente ohne Signal erzeugen Sie ein helles PNG mit der Größe fit. Es ist die schnellste Ausgabe und die einzige, die Sie selbst inspizieren können. Fügen Sie dann eine Zeile hinzu, die die anderen beiden Ausgaben anbietet.

Die Regeln 1, 2 und 4 werden ohne Nachfragen ausgeführt. Wenn mehrere Ausgaben angefordert werden, erzeugen Sie alle aus derselben Konfiguration. Speichern Sie die Auswahl nicht in .swiftui-preview/config.json: Sie gehört zur Anfrage, nicht zum Projekt.

Erste Verwendung in einem Projekt

<skill-directory> in den folgenden Befehlen ist das Verzeichnis, das diese SKILL.md enthält; lösen Sie es vom installierten Speicherort auf. Claude Code gibt es als Basisverzeichnis der Fertigkeit an, wenn sie geladen wird (${CLAUDE_SKILL_DIR}); in Codex und anderen Agenten verwenden Sie den Pfad, von dem diese Datei gelesen wurde. Es sind keine entwicklerspezifischen Pfade oder Einstellungen erforderlich. Verwenden Sie das aktuelle Projektstammverzeichnis des Benutzers und führen Sie eine schreibgeschützte Erkennung durch:

python3 "<skill-directory>/scripts/bootstrap.py" discover --root "<project-root>"

Die Erkennung meldet SwiftPM-Manifeste, Xcode-Projekte/Workspaces, SwiftUI-Quellen, das Vorhandensein von #Preview und textuelle Plattformhinweise. Sie wertet niemals Manifeste aus, führt Plugins aus, erstellt oder ändert das Projekt. Verschachtelte Abhängigkeits-/Build-Verzeichnisse und Symlinks werden übersprungen. Fehlende Plattformmetadaten bedeuten „unbekannt“, nicht „nicht unterstützt“. Verwenden Sie die Anfrage und die erkannten Pfade, um das beabsichtigte Projekt und die Komponente auszuwählen. Fragen Sie nur nach einer Auswahl, wenn diese wirklich mehrdeutig bleibt; mehrere Marker allein erfordern keine Frage, wenn die angeforderte Quelle klar ist.

Lesen Sie die ausgewählte tatsächliche Quelle, ihre vorhandene #Preview-Konstruktion und die notwendigen lokalen Definitionen, bevor Sie ein Fixture erstellen. Der Skill-Agent führt diese Anpassung als Teil der ersten Vorschauanfrage durch; bleiben Sie nicht bei Anweisungen stehen, die dem Benutzer sagen, er solle es manuell anpassen, wenn Sie es sicher tun können. Behalten Sie die echte Ansichtshierarchie, Steuerelemente, Stile und Eingaben der Komponente bei. Extrahieren Sie die Wertansicht und fügen Sie erforderliche lokale Definitionen hinzu, wobei Sie Serviceabhängigkeiten durch synthetische Werte und lokale Aktionen ersetzen. Ersetzen Sie die angeforderte Komponente nicht durch einen ähnlich aussehenden Bildschirm, eine generische Demo oder das gebündelte Beispiel. Die Beispiele veranschaulichen nur die Fixture-API.

Speichern Sie das angepasste Fixture innerhalb des Benutzerprojekts, zum Beispiel .swiftui-preview/fixtures/StatusCard.swift. Kopieren Sie niemals den Projektquellcode in die gemeinsam genutzte installierte Fertigkeit. Fügen Sie kein @main, keinen App-Delegaten, keinen Produktions-Kompositions-Root, kein #Preview-Makro und keine Produktionsdienste ein. configure, run und refresh durchsuchen das Fixture als Text und lehnen es ab, wenn @main, #Preview oder import UIKit irgendwo erscheint, einschließlich Kommentaren; halten Sie diese Zeichenfolgen auch aus Kommentaren heraus. Der Fehler benennt das gefundene Token und seine Zeile. Überprüfen Sie das gesamte Fixture, bevor Sie es ausführen: Ausführbarer Swift-Code wird mit normalen Rechten des Aufrufers ausgeführt; dieser Helfer ist keine Sandbox. Konfigurations-Hashes können keine visuelle Wiedergabetreue oder Abwesenheit von Nebenwirkungen gewährleisten.

Wenn explizite UIKit- oder iOS-APIs die Komponente mit macOS inkompatibel machen, verwenden Sie einen verfügbaren iOS-Simulator/Xcode Canvas Workflow oder melden Sie die genaue nicht unterstützte Abhängigkeit. Der generische macOS-Host führt kein UIKit aus. Wenn Module, Assets oder String-Kataloge nicht sicher in den Einzeldateivertrag angepasst werden können, verwenden Sie einen verfügbaren projektspezifischen Workflow oder geben Sie die konkrete Einschränkung an. Verlinken Sie die Produktions-App nicht stillschweigend, führen Sie ihren Lebenszyklus nicht aus und ändern Sie ihre Build-Konfiguration nicht.

Nachdem Sie das echte Fixture vorbereitet und überprüft haben, speichern Sie die ausgewählten Pfade (relativ zum Projektstamm):

python3 "<skill-directory>/scripts/bootstrap.py" configure --root "<project-root>" \
  --project "Package.swift" --source "Sources/StatusCard.swift" \
  --fixture ".swiftui-preview/fixtures/StatusCard.swift" --component StatusCard

--project akzeptiert auch ein relatives .xcodeproj oder .xcworkspace-Verzeichnis; init ist ein Alias für configure. Fügen Sie --live-fixture "<relativer Pfad>" hinzu, um ein separates zustandsbehaftetes Fixture für Live-Builds zu registrieren (siehe references/live.md). Die versionierte .swiftui-preview/config.json speichert nur relative Pfade, den Komponentennamen, die Plattform macos und SHA-256-Hashes der ausgewählten Quelle und des angepassten Fixtures. Sie wird mit dem Projekt verschoben und kann vom Benutzer committet werden; führen Sie keine Git-Aktionen aus, es sei denn, sie werden angefordert. Eine bestehende Konfiguration bleibt erhalten, es sei denn, sie wird nach Überprüfung und Anpassung explizit mit configure --replace ersetzt. Ausgewählte Pfade und Konfiguration müssen innerhalb des Stammverzeichnisses existieren, ohne Symlinks oder Pfad-Traversal.

Nachdem configure erfolgreich war, erzeugen Sie die erste Vorschau mit run, wie unten beschrieben. Die direkten Helfer in späteren Abschnitten sind für einmalige Fixtures gedacht, die keine gespeicherte Konfiguration haben.

Nachfolgende Vorschauen

Wenn eine Konfiguration existiert, überprüfen Sie sie und verwenden Sie run. Es validiert das Schema, die Pfade und Hashes, bevor es einen bekannten Helfer mit festen Argumentpositionen aufruft:

python3 "<skill-directory>/scripts/bootstrap.py" run --root "<project-root>" \
  --mode render --output "/absolute/task-output/card.png" \
  --width 480 --height 320 --locale en_US --theme light --frame

Verwenden Sie --mode gallery mit einer .html-Ausgabe oder --mode live mit einer neuen .app-Ausgabe. --theme und --frame gelten nur für Renderings; Galerien enthalten alle Varianten und Live-Vorschauen haben native Steuerelemente. Das Ausgabeübergeordnete Verzeichnis muss existieren; bootstrap lehnt vorhandene Ausgaben ab, anstatt sie zu ersetzen – im Gegensatz zu den direkten Helfern render.sh und gallery.sh; wählen Sie zum erneuten Rendern einen neuen Dateinamen oder entfernen Sie zuerst das alte aufgabenbezogene Artefakt. Relative Ausgabepfade werden vom Projektstamm aus aufgelöst. --mode live erstellt nur; Start- und Inspektionsregeln finden Sie in references/live.md.

Geänderte Quell- oder Fixture-Hashes stoppen die Ausführung. Überprüfen Sie die tatsächliche Komponente erneut, aktualisieren Sie das Fixture und führen Sie dann configure --replace mit den ausgewählten Pfaden aus, oder refresh, wenn ein Live-Fenster iteriert wird. Überprüfen Sie auch Änderungen an unterstützenden Definitionen/Ressourcen: Hashes decken die primäre Quelle und das eigenständige Fixture ab, nicht den gesamten Abhängigkeitsgraphen. Das Wechseln von Komponenten folgt dem Anpassungsworkflow der ersten Verwendung, bevor die Konfiguration ersetzt wird. Bewahren Sie Benutzeränderungen an vorhandenen Fixtures.

Fixture-Vertrag und direkte Helfer

Der Renderer kompiliert eine eigenständige Swift-Datei zusammen mit ihrem Helfer. Ihr Einstiegspunkt ist:

import SwiftUI

@MainActor
enum PreviewFixture {
    static func makeView() -> some View {
        Text("Beispiel")
    }
}

Die Helfer kompilieren im Swift-6-Sprachmodus mit striktem Concurrency, wenn der Compiler dies unterstützt, andernfalls im Swift-5-Modus. Wenn ein aus einem Swift-5-Projekt angepasstes Fixture nur aufgrund von Concurrency-Diagnosen (Sendable, Actor-Isolation) fehlschlägt, schreiben Sie die Komponente nicht um, um diese zu erfüllen: Übergeben Sie --swift-version 5 an run oder refresh, oder setzen Sie PREVIEW_SWIFT_VERSION=5 für die direkten Helfer, und sagen Sie, dass die Vorschau im Swift-5-Modus erstellt wurde.

Verwenden Sie synthetische Daten und einen festen Anfangszustand. Verwenden Sie träge Aktionen für statische Renderings; Live-Fixtures können ansichtsbezogene Zustandsänderungen, Validierung und Navigation implementieren. Fügen Sie die erforderlichen lokalen Ansichtstypen der Komponente in das Fixture ein; bewahren Sie echte SwiftUI-Steuerelemente wie Form, TextField, SecureField und Toggle. Halten Sie Credential-Stores, Netzwerkaufrufe, Persistenz und Arbeit, die die Ansicht überdauert, aus dem Fixture heraus; ein Live-Fixture kann einen Dienst mit einer kurzen In-Memory-Verzögerung simulieren.

Wenn das Projekt bereits #Preview-Fixtures hat, verwenden Sie deren Ansichtskonstruktion und Eingaben wieder. Kompilieren Sie das #Preview-Makro oder eine @main App nicht in diesem eigenständigen Fixture. Ändern Sie die Projektkonfiguration nicht, nur um eine Komponente zu rendern.

Derselbe Fixture-Vertrag funktioniert projektübergreifend für SwiftUI-Komponenten, die für macOS kompilieren. Nur-UIKit-Komponenten erfordern einen iOS-Simulator-Workflow. Die Helfer verlinken nicht automatisch beliebige Projektmodule oder kompilieren/kopieren Assets und String-Kataloge. Extrahieren Sie eine eigenständige Wertansicht, wo dies praktikabel ist. Wenn die Komponente Projektmodule oder Bundles benötigt, erklären Sie, dass dieser eigenständige Befehl einen explizit angepassten Build benötigt; behaupten Sie nicht, dass die Gebietsschema-Injektion fehlende Übersetzungen oder Ressourcen liefert.

Rendern und Inspizieren

Verwenden Sie Pfade, die zur aktuellen Aufgabe passen. Lösen Sie das Skill-Verzeichnis vom Speicherort dieser Fertigkeit auf, setzen Sie jeden Pfad in Anführungszeichen und erstellen Sie zuerst das übergeordnete Ausgabeverzeichnis. Führen Sie aus:

bash "<skill-directory>/scripts/render.sh" \
  "/absolute/path/Fixture.swift" "/absolute/path/component-hell.png" \
  480 320 hell en_US

Argumente sind Fixture, Ausgabe-PNG, Inhaltsbreite, Inhalt Höhe, Erscheinungsbild (hell oder dunkel) und Gebietsschema-Bezeichner. Breite und Höhe sind ganze Zahlen von 1 bis 4096, gerendert mit einem Pixel pro Punkt, oder fit. Eine vorhandene Ausgabedatei wird atomar ersetzt; wählen Sie aufgabenbezogene Pfade. Wiederholen Sie mit dunkel und einem anderen Dateinamen, wenn ein Erscheinungsbildvergleich nützlich ist. Das Gebietsschema setzt nur die SwiftUI-Umgebung; wählen Sie die RTL-Layout-Richtung explizit in einem Fixture, wenn dies Teil des Tests ist.

Auswahl des Viewports. Dimensionieren Sie es auf die Komponente, nicht auf die Beispielzahlen. Für einen Vollbildschirm verwenden Sie die Ziel-Fenster- oder Gerätegröße in Punkten. Für eine Zeile, Karte oder ein Steuerelement übergeben Sie die Breite des echten Containers und fit für die Höhe, z. B. 390 fit; der Renderer misst die ideale Größe des Fixtures auf jeder angepassten Achse und gibt render: angepasste Inhaltsgröße BxH auf stderr aus. fit fit eignet sich für intrinsisch dimensionierte Steuerelemente, aber Ansichten, die um Spacer, maxWidth: .infinity oder ScrollView herum aufgebaut sind, schrumpfen auf einer angepassten Achse auf ihr Minimum, also geben Sie diesen eine Zahl. run --mode render akzeptiert --width fit und --height fit; Galerie und Live benötigen Zahlen, also verwenden Sie die dort gemeldete Größe wieder.

Fügen Sie --frame nur hinzu, wenn es angefordert oder für die Präsentation nützlich ist. Es fügt eine dekorative Titelleiste und einen umgebenden Abstand außerhalb des festen Inhalts-Viewports hinzu: Die Ausgabeabmessungen werden zu Breite + 48 mal Höhe + 88. Die Ampeln sind gezeichnete Formen. Es erstellt kein echtes Fenster und validiert keine native Fensteroptik.

Überprüfen Sie das generierte Bild mit dem verfügbaren lokalen Bildbetrachter, bevor Sie visuelle Ergebnisse melden. Wenn Inhalt fehlt oder abgeschnitten ist, überprüfen Sie zuerst das Layout und den Viewport des Fixtures. Stoppen Sie Komponenten, die ein Fenster, einen App-Lebenszyklus oder nicht verfügbare Ressourcen benötigen, und erklären Sie dies, anstatt die Produktions-App stillschweigend zu starten.

Galerie und Live-Fenster

Zwei weitere Ausgaben verwenden denselben Fixture-Vertrag. Lesen Sie die verlinkte Referenz vollständig, bevor Sie eine davon produzieren; jede hat Regeln zu Ausgabepfaden, Start und was als verifiziert gilt.

• HTML-Theme-Galerie, wenn der Benutzer hell/dunkel vergleichen oder den dekorativen Rahmen umschalten möchte: run --mode gallery, oder direkt scripts/gallery.sh. Siehe references/gallery.md.
• Live natives Fenster, für echte Schaltflächen, Texteingabe, Fokus und Navigation: run --mode live, oder direkt scripts/live.sh. Es erstellt eine .app und startet sie nicht. Ein statisches Fixture mit trägen Aktionen zeigt nichts, wenn darauf geklickt wird; references/live.md erklärt, wann ein separates zustandsbehaftetes Fixture mit configure --live-fixture hinzugefügt werden muss. Ein geöffnetes Fenster übernimmt niemals Codeänderungen: Nach dem Aktualisieren des Fixtures erstellt refresh die App unter demselben Pfad neu, schließt das alte Fenster und öffnet es erneut (gleiche Referenz).

Ergebnis präsentieren

Überprüfen Sie jedes Artefakt selbst, bevor Sie es zeigen, und präsentieren Sie es dann mit dem, was der aktuelle Agent bietet. Verwenden Sie die tatsächlich in der Sitzung verfügbaren Werkzeuge; gehen Sie nicht davon aus, dass eines aus dieser Liste existiert.

Ausgabepfad. Verwenden Sie ein aufgabenbezogenes Verzeichnis. Wenn der Client nur Dateien innerhalb des Projekts anzeigen kann, schreiben Sie nach <project-root>/.swiftui-preview/artifacts/ (erstellen Sie es zuerst) und führen Sie darauf keine Git-Aktionen aus, es sei denn, sie werden angefordert.

Claude Code.

• PNG: Lesen Sie die Datei mit dem Read-Tool, um das Bild zu inspizieren. Um es anzuzeigen, verwenden Sie das dateipräsentierende oder Vorschau-Tool der Sitzung, falls vorhanden; andernfalls geben Sie den absoluten Pfad als Link an und führen Sie open "/absolute/path/component-hell.png" aus, wenn der Benutzer darum gebeten hat, es zu sehen. Inline-Markdown-Bilder werden in einem Terminal nicht gerendert.
• HTML-Galerie: Öffnen Sie sie in einem verfügbaren Browser oder Vorschau-Tool über ihre file://-URL, oder führen Sie open "/absolute/path/component-gallery.html" aus. Testen Sie die Theme- und Rahmensteuerelemente über ein Browser-Tool, bevor Sie sie als verifiziert melden; ohne ein solches Tool sagen Sie, dass die Steuerelemente nicht getestet wurden.
• Live-App: Führen Sie open "/absolute/path/SwiftUI Preview.app" aus, wenn das Starten Teil der Anfrage ist; refresh öffnet die App selbst, sofern nicht --no-launch übergeben wird. Überprüfen Sie die Interaktivität durch die verfügbaren Desktop-Automatisierungstools der Sitzung, bevor Sie behaupten, dass sie funktioniert; ohne solche Tools erklären Sie, dass die Interaktionen nicht programmatisch getestet wurden.

Nächstes

Der Benutzer kann nun eine bestimmte Komponente mit einem Pfad oder einer Beschreibung anfordern. Setzen Sie die Erkennung und Anpassung aus dem Abschnitt „Erste Verwendung in einem Projekt“ ein. Wenn die Konfiguration bereits existiert, überspringen Sie die Erkennung, überprüfen Sie die Hashes und verwenden Sie run.