BIGboss248/nextjs-wordpress

Google Stitch UI Prototyping & Varianten-Fähigkeit (stitch-design)

Diese Fähigkeit definiert den vollständigen Workflow für die Verwendung einer etablierten Komponenten-Designspezifikation (design-spec.md) mit Google Stitch (StitchMCP) – zum Erstellen von Screen-Layouts, Generieren von räumlichen Varianten, Herunterladen hochauflösender visueller Assets (JPG-Screenshots und rohe HTML-Exporte) in das Code-Repository und Aktualisieren der Designspezifikation mit konkreten Layout-Benchmarks.

[!IMPORTANT] Eingabevoraussetzung: Diese Fähigkeit erfordert eine abgeschlossene Designspezifikation unter docs/design/components/[Seitenname]/[Komponentenname]/design-spec.md (normalerweise generiert von component-design). Wenn keine Spezifikation existiert, führen Sie zuerst /component-design aus.

[!CAUTION] Sicherheitsregel für binäre Downloads: Verwenden Sie NIEMALS read_url_content, um Stitch JPG-Screenshots oder HTML-Exporte herunterzuladen. read_url_content ist ein reiner Text-Reader und konvertiert Antworten in Markdown, was binäre Bilder beschädigt und die HTML-Struktur verstümmelt. Alle Downloads MÜSSEN run_command mit PowerShell Invoke-WebRequest -Uri <url> -OutFile <pfad> verwenden. Signierte Download-URLs laufen schnell ab – laden Sie sofort nach Erhalt der Stitch-Antwort herunter.

[!TIP] Keine In-Skill-Bildgenerierung (Token-Sparregel): Um Tokens zu schonen, darf diese Fähigkeit generate_image NICHT direkt aufrufen. Wenn der Bildschirm benutzerdefinierte Hintergrundbilder, Illustrationen oder Symbole erfordert, formulieren und geben Sie dem Benutzer strukturierte Prompts aus, damit diese generiert und in den Projektdateien platziert werden können.

---

1. Kernlieferungen & Workflow-Übersicht

flowchart TD
    Start["Aufruf /stitch-design<br/>(Ziel: docs/design/components/[seite]/[komponente]/design-spec.md)"] --> Schritt1["Schritt 1: Designspezifikation einlesen<br/>(Lese design-spec.md & docs/project.json)"]
    Schritt1 --> Schritt2["Schritt 2: Stitch-Projekt-Persistenz & Token-Seeding<br/>(Prüfe/Wiederverwende stitch.project_id in docs/project.json, seede Designsystem)"]
    Schritt2 --> Schritt3["Schritt 3: Screen & Variantengenerierung via StitchMCP<br/>(generate_screen_from_text + generate_variants für 1 Variante)"]
    Schritt3 --> Schritt4["Schritt 4: Binärsicherer Asset-Download<br/>(PowerShell Invoke-WebRequest → stitch/screen.jpg, screen.html, variant-1.jpg, variant-1.html)"]
    Schritt4 --> Schritt5["Schritt 5: Design-Spec-Benchmark-Integration<br/>(Einbettung von stitch/screen.jpg & Varianten-Benchmarks in design-spec.md)"]
    Schritt5 --> Schritt6["Schritt 6: Unabhängige Sub-Agenten-Verifikation<br/>(invoke_subagent prüft Dateigrößen, Metadaten und Spezifikationskonformität)"]
    Schritt6 --> Fertig["Visuelle Prototypen bereit<br/>(Stitch JPG + HTML im Code-Repository gespeichert)"]

Lieferumfang: Der Stitch-Assets-Unterordner

Jeder Stitch-Durchlauf erstellt oder aktualisiert den Unterordner stitch/ im Designverzeichnis der Komponente:

docs/design/components/[Seitenname]/[Komponentenname]/
├── design-spec.md          # Aktualisiert mit Stitch-Benchmarks & eingebetteten Screenshots
└── stitch/                 # Heruntergeladene Google Stitch-Designdateien
    ├── screen.jpg          # Von Stitch generierter JPG-Screenshot des primären Bildschirms
    ├── screen.html         # Von Stitch generierter roher HTML-Export des primären Bildschirms
    ├── variant-1.jpg       # Von Stitch generierter JPG-Screenshot der Variante
    ├── variant-1.html      # Von Stitch generierter roher HTML-Export der Variante
    └── stitch-meta.json    # Stitch-Projekt-ID, Screen-ID, Varianten-IDs und Generierungs-Prompt

---

2. Schritt-für-Schritt-Ausführungsworkflow

Schritt 1: Designspezifikation & Projektkontext einlesen

1. Zielkomponente lokalisieren:
   • Identifizieren Sie den Komponentenpfad: docs/design/components/[Seitenname]/[Komponentenname]/.
   • Lesen Sie design-spec.md, um Folgendes zu extrahieren:
     • Zusammenfassung, Persona und emotionale Tonalität.
     • Visuelle Hierarchie (1., 2. und 3. Blickfang).
     • Layout-Raster und Breakpoint-Verhalten.
     • Design-Tokens (Farben, Radien, Schatten).
     • Pro-lokale Typografie-Paarungen.
2. Projektkontext lesen:
   • Lesen Sie docs/project.json, um das kanonische Designsystem zu überprüfen und nach bestehender Stitch-Konfiguration zu suchen.

---

Schritt 2: Google Stitch-Projekt-Persistenz & Designsystem-Seeding (StitchMCP)

[!IMPORTANT] Ein-Projekt-pro-Repository-Regel (Keine Duplikate): Jedes Repository muss genau einen gemeinsamen Google Stitch-Projektcontainer für alle seine Komponenten- und Bildschirmdesigns verwalten. Erstellen Sie NIEMALS mehrere Stitch-Projekte für dasselbe Repository.

1. Zuerst docs/project.json prüfen:
   • Durchsuchen Sie docs/project.json nach einem vorhandenen "stitch"-Objekt mit project_id.
2. Vorhandenes Projekt wiederverwenden:
   • Wenn stitch.project_id existiert, verwenden Sie diese projectId IMMER direkt für alle Screen-Scaffoldings, Varianten und Designsystem-Aktualisierungen. Rufen Sie create_project NICHT auf.
3. Erstellen und sofort persistieren (nur wenn nicht vorhanden):
   • Wenn keine stitch.project_id in docs/project.json existiert:
     • Rufen Sie call_mcp_tool auf StitchMCP mit list_projects auf, um zu prüfen, ob ein Projekt mit dem Repository-Titel bereits existiert.
     • Wenn keines existiert, rufen Sie create_project mit title: "[Projekttitel] Designsystem & Komponenten" auf.
     • Persistieren Sie die Projekteigenschaften SOFORT in docs/project.json unter "stitch":

       "stitch": {
         "project_id": "<projectId>",
         "project_name": "projects/<projectId>",
         "title": "<title>"
       }
       

4. Design-Tokens seeden:
   • Übergeben Sie das kanonische Designsystem des Projekts (aus docs/project.json) an Stitch via upload_design_md oder create_design_system_from_design_md, um globale Farb-, Schrift- und Radiuskonsistenz herzustellen.

---

Schritt 3: Screen- und Variantengenerierung via StitchMCP

1. Detaillierten Design-Prompt synthetisieren:
   • Kombinieren Sie den Komponentenzweck, die Benutzer-Persona, die emotionale Tonalität und die Layout-Anforderungen aus design-spec.md.
   • Geben Sie explizit visuelle Tokens an: Hintergrund-Canvas, Oberflächenkarten, primäre Akzentfarbe, sekundäre Akzentfarbe, Statusfarben und Typografie aus docs/project.json.
   • Geben Sie das Ziel-Viewport an: deviceType: "DESKTOP" (oder "MOBILE" / "TABLET", wenn eine Mobile-First-Komponente anvisiert wird).
2. Primären Bildschirm generieren:
   • Rufen Sie generate_screen_from_text auf StitchMCP auf:
     • projectId: Aktive Stitch-Projekt-ID.
     • prompt: Synthetisierter Design-Prompt.
     • deviceType: "DESKTOP".
   • Extrahieren Sie die generierte Screen-ID und den Ressourcennamen (Format: projects/{projectId}/screens/{screenId}).
3. Eine Variante generieren:
   • Rufen Sie generate_variants auf StitchMCP mit der generierten Screen-ID auf, um eine räumliche/visuelle Variante der Designspezifikationsdatei zu erstellen (z. B. alternative Layoutdichte, Karte vs. Full-Bleed oder asymmetrischer visueller Fluss).
   • Notieren Sie die Varianten-Screen-ID.

---

Schritt 4: Binärsicheres Asset-Download-Protokoll

[!CAUTION] PowerShell Invoke-WebRequest erforderlich: Führen Sie jeden Download-Befehl als diskreten Einzelvorgang aus. Überprüfen Sie, dass jede heruntergeladene Datei eine Größe ungleich Null hat (> 10 KB für JPGs).

1. Verzeichnis sicherstellen:
   • Zielverzeichnis: docs/design/components/[Seitenname]/[Komponentenname]/stitch/.
2. Primären Screen-JPG herunterladen:
   • Extrahieren Sie screenshot.downloadUrl aus der Antwort des primären Bildschirms.
   • Führen Sie aus:

     powershell -Command "Invoke-WebRequest -Uri '<screenshot.downloadUrl>' -OutFile 'docs/design/components/[seite]/[komponente]/stitch/screen.jpg'"
     

3. Primären Screen-HTML herunterladen:
   • Extrahieren Sie htmlCode.downloadUrl aus der Antwort des primären Bildschirms.
   • Führen Sie aus:

     powershell -Command "Invoke-WebRequest -Uri '<htmlCode.downloadUrl>' -OutFile 'docs/design/components/[seite]/[komponente]/stitch/screen.html'"
     

4. Variant-1-JPG herunterladen:
   • Extrahieren Sie screenshot.downloadUrl aus der Antwort der Variante.
   • Führen Sie aus:

     powershell -Command "Invoke-WebRequest -Uri '<variant.screenshot.downloadUrl>' -OutFile 'docs/design/components/[seite]/[komponente]/stitch/variant-1.jpg'"
     

5. Variant-1-HTML herunterladen:
   • Extrahieren Sie htmlCode.downloadUrl aus der Antwort der Variante.
   • Führen Sie aus:

     powershell -Command "Invoke-WebRequest -Uri '<variant.htmlCode.downloadUrl>' -OutFile 'docs/design/components/[seite]/[komponente]/stitch/variant-1.html'"
     

6. Stitch-Metadaten speichern (stitch-meta.json):
   • Schreiben Sie docs/design/components/[seite]/[komponente]/stitch/stitch-meta.json:

     {
       "projectId": "<stitchProjektId>",
       "screenId": "<screenId>",
       "screenName": "projects/<projectId>/screens/<screenId>",
       "deviceType": "DESKTOP",
       "generationPrompt": "<synthetisierterPrompt>",
       "variantIds": ["<variantScreenId1>"]
     }
     

---

Schritt 5: Design-Spec-Benchmark-Integration

Aktualisieren Sie docs/design/components/[Seitenname]/[Komponentenname]/design-spec.md mit den Stitch-Ergebnissen:

1. Stitch-Primärbildschirm und Variante einbetten:

   ## Google Stitch Layout-Architektur & Benchmarks
   
   ### Primäres Bildschirmdesign
   ![Primäres Bildschirmdesign](stitch/screen.jpg)
   
   ### Variante 1 – Erkundung
   ![Varianten-1-Design](stitch/variant-1.jpg)
   

2. Layout-Architektur-Beobachtungen dokumentieren:
   • Notieren Sie das räumliche Raster, das visuelle Gewicht, den Weißraum-Rhythmus und die Typografie-Hierarchie, die in den Stitch-Screens demonstriert werden.
   • Vergleichen Sie den primären Bildschirm mit Variante 1 und heben Sie die Stärken jeder Komposition hervor.

---

Schritt 6: Visuelle Asset-Prompts (falls zutreffend)

[!NOTE] Wenn die Inspektion der Stitch-Layouts den Bedarf an maßgeschneiderten visuellen Assets (z. B. Umgebungshintergründe, benutzerdefinierte Symbole oder Diagramme) offenbart, rufen Sie generate_image NICHT auf. Geben Sie dem Benutzer stattdessen strukturierte Prompts aus:

### Empfohlenes visuelles Asset: [Asset-Name]
- **Zieldateipfad:** `docs/design/components/[seite]/[komponente]/[dateiname].png`
- **Empfohlenes Seitenverhältnis:** `16:9` oder `1:1`
- **Generierungs-Prompt:**
  > "[Detaillierter Prompt, der das zum Stitch-Layout passende visuelle Asset beschreibt]"

---

Schritt 7: Unabhängige Sub-Agenten-Verifikationsschleife (invoke_subagent)

[!IMPORTANT] Sub-Agenten-Review-Protokoll: Überprüfen Sie heruntergeladene Assets und Spezifikationsaktualisierungen immer über einen unabhängigen Sub-Agenten, bevor Sie den Abschluss melden.

1. Verifikations-Sub-Agenten starten

Rufen Sie invoke_subagent auf mit:

• TypeName: "self"
• Role: "Stitch-Asset- & Download-Prüfer"
• Model: "inherit"
• Prompt:

Sie sind ein unabhängiger Stitch-Asset-Prüfer. Ihre Aufgabe ist es zu überprüfen, ob die Google Stitch-Assets sauber heruntergeladen und in das Komponentenverzeichnis integriert wurden.

ZIEL-KOMPONENTENVERZEICHNIS:
docs/design/components/[Seitenname]/[Komponentenname]/

Zu prüfende Lieferungen:
1. docs/design/components/[Seitenname]/[Komponentenname]/stitch/screen.jpg (muss existieren, Bytes ungleich Null)
2. docs/design/components/[Seitenname]/[Komponentenname]/stitch/screen.html (muss existieren, rohes HTML)
3. docs/design/components/[Seitenname]/[Komponentenname]/stitch/variant-1.jpg (muss existieren, Bytes ungleich Null)
4. docs/design/components/[Seitenname]/[Komponentenname]/stitch/variant-1.html (muss existieren, rohes HTML)
5. docs/design/components/[Seitenname]/[Komponentenname]/stitch/stitch-meta.json (gültiges JSON mit projectId, screenId, generationPrompt, variantIds)
6. docs/design/components/[Seitenname]/[Komponentenname]/design-spec.md (muss stitch/screen.jpg und stitch/variant-1.jpg einbetten)

Prüfen Sie anhand dieser strengen Kriterien:
1. Binärdatei-Integrität: Bestätigen Sie, dass screen.jpg und variant-1.jpg nicht leer oder beschädigt sind (Größe > 10 KB).
2. HTML-Integrität: Bestätigen Sie, dass screen.html und variant-1.html gültige HTML-Dateien und kein beschädigtes Markdown sind.
3. Metadaten-Integrität: Bestätigen Sie, dass stitch-meta.json gültige Felder enthält.
4. Spezifikationsintegration: Bestätigen Sie, dass design-spec.md die eingebetteten Screenshot-Links und Stitch-Layout-Benchmark-Notizen enthält.
5. Token-Schonung: Bestätigen Sie, dass generate_image NICHT direkt aufgerufen wurde.

Antworten Sie in diesem exakten Format:
URTEIL: BESTANDEN | PROBLEME_GEFUNDEN

PROBLEME (falls vorhanden):
- ORT: {datei:zeile oder abschnitt}
- PROBLEM: {was nicht konform oder defekt ist}
- BEHEBUNG: {konkrete Anweisung zur Behebung}

ZUSAMMENFASSUNG: {kurze Gesamtbewertung}

2. Review auswerten und beheben

Wenn PROBLEME_GEFUNDEN, beheben Sie diese sofort (z. B. durch erneutes Herunterladen fehlgeschlagener Assets oder Korrektur der Metadaten), bevor Sie die Ausführung abschließen.

---

3. Checkliste zur Ausführungsverifizierung

Überprüfen Sie vor Abschluss der Ausführung:

• design-spec.md wurde aus docs/design/components/[seite]/[komponente]/ eingelesen.
• Stitch-Projekt-ID wurde aus docs/project.json verifiziert/wiederverwendet (oder erstellt und sofort persistiert).
• Design-Tokens wurden via upload_design_md oder create_design_system_from_design_md in Stitch geseedet.
• Primärer Bildschirm wurde via generate_screen_from_text generiert.
• Genau eine Variante wurde via generate_variants generiert.
• Alle Assets wurden mit PowerShell Invoke-WebRequest -OutFile heruntergeladen (keine Verwendung von read_url_content).
• screen.jpg, screen.html, variant-1.jpg, variant-1.html sind in stitch/ mit Größen ungleich Null gespeichert.
• stitch/stitch-meta.json wurde mit vollständigen Metadaten gespeichert.
• design-spec.md wurde mit eingebetteten Screenshots und Stitch-Layout-Benchmarks aktualisiert.
• generate_image wurde NICHT direkt aufgerufen; bei Bedarf wurden Bild-Prompts für den Benutzer ausgegeben.
• Unabhängige Sub-Agenten-Prüfung wurde via invoke_subagent aufgerufen und bestanden.