Prototypage UI Google Stitch & Génération de Variantes (stitch-…

Compétence de Prototypage UI & Génération de Variantes Google Stitch (stitch-design)

Cette compétence définit le workflow complet pour prendre une spécification de conception de composant établie (design-spec.md) et utiliser Google Stitch (StitchMCP) pour échafauder des mises en page d'écran, générer des variantes spatiales, télécharger des assets visuels haute résolution (captures JPG et exports HTML bruts) dans la base de code, et mettre à jour la spécification de conception avec des benchmarks de mise en page concrets.

[!IMPORTANT] Prérequis d'entrée : Cette compétence nécessite une spécification de conception complète à docs/design/components/[nom de page]/[nom du composant]/design-spec.md (généralement générée par component-design). Si aucune spécification n'existe, exécutez d'abord /component-design.

[!CAUTION] Règle de sécurité pour le téléchargement binaire : N'utilisez JAMAIS read_url_content pour télécharger des captures JPG Stitch ou des exports HTML. read_url_content est uniquement textuel et convertit les réponses en markdown, corrompant les images binaires et déformant la structure HTML. Tous les téléchargements DOIVENT utiliser run_command avec PowerShell Invoke-WebRequest -Uri <url> -OutFile <path>. Les URL de téléchargement signées expirent rapidement—téléchargez immédiatement après avoir reçu la réponse Stitch.

[!TIP] Aucune génération d'image dans la compétence (Règle de conservation des tokens) : Pour économiser les tokens, cette compétence NE DOIT PAS invoquer generate_image directement. Si l'écran nécessite des images de fond personnalisées, des illustrations ou des icônes, formulez et émettez des prompts structurés à l'utilisateur afin qu'il puisse les générer et les placer dans les fichiers du projet.

---

1. Livrables principaux et aperçu du workflow

flowchart TD
    Start["Invoquer /stitch-design<br/>(Cible : docs/design/components/[page]/[composant]/design-spec.md)"] --> Step1["Étape 1 : Ingérer la spécification de conception<br/>(Lire design-spec.md et docs/project.json)"]
    Step1 --> Step2["Étape 2 : Persistance du projet Stitch et injection de tokens<br/>(Vérifier/réutiliser stitch.project_id dans docs/project.json, injecter le design system)"]
    Step2 --> Step3["Étape 3 : Génération d'écran et de variante via StitchMCP<br/>(generate_screen_from_text + generate_variants pour 1 variante)"]
    Step3 --> Step4["Étape 4 : Téléchargement binaire-sûr des assets<br/>(PowerShell Invoke-WebRequest → stitch/screen.jpg, screen.html, variant-1.jpg, variant-1.html)"]
    Step4 --> Step5["Étape 5 : Intégration des benchmarks dans la spec de conception<br/>(Intégrer stitch/screen.jpg et les benchmarks de variante dans design-spec.md)"]
    Step5 --> Step6["Étape 6 : Vérification par sous-agent indépendant<br/>(invoke_subagent vérifie les tailles de fichiers, les métadonnées et la conformité de la spécification)"]
    Step6 --> Finish["Prototypes visuels prêts<br/>(JPG + HTML Stitch sauvegardés dans la base de code)"]

Livrable : Le sous-dossier des assets Stitch

Chaque exécution de Stitch crée ou remplit le sous-dossier stitch/ dans le répertoire de conception du composant :

docs/design/components/[nom de page]/[nom du composant]/
├── design-spec.md          # Mis à jour avec les benchmarks Stitch et les captures d'écran intégrées
└── stitch/                 # Fichiers de conception Google Stitch téléchargés
    ├── screen.jpg          # Capture JPG Stitch de l'écran principal
    ├── screen.html         # Export HTML brut Stitch de l'écran principal
    ├── variant-1.jpg       # Capture JPG Stitch de la variante
    ├── variant-1.html      # Export HTML brut Stitch de la variante
    └── stitch-meta.json    # ID du projet Stitch, ID de l'écran, IDs des variantes et prompt de génération

---

2. Workflow d'exécution étape par étape

Étape 1 : Ingérer la spécification de conception et le contexte du projet

1. Localiser le composant cible :
   • Identifier le chemin du composant : docs/design/components/[nom de page]/[nom du composant]/.
   • Lire design-spec.md pour extraire :
     • Résumé exécutif, persona et ton émotionnel.
     • Hiérarchie visuelle (1er, 2e et 3e points focaux).
     • Grille de mise en page et comportements aux points de rupture.
     • Tokens de conception (couleurs, rayons, élévation).
     • Appairages typographiques par locale.
2. Lire le contexte du projet :
   • Lire docs/project.json pour vérifier le design system canonique et rechercher une configuration Stitch existante.

---

Étape 2 : Persistance du projet Google Stitch et injection du design system (StitchMCP)

[!IMPORTANT] Règle d'un seul projet par dépôt (zéro projet en double) : Chaque dépôt doit maintenir exactement un conteneur de projet Google Stitch partagé pour tous ses composants et conceptions d'écran. Ne créez JAMAIS plusieurs projets Stitch pour le même dépôt.

1. Vérifier d'abord docs/project.json :
   • Inspecter docs/project.json pour un objet "stitch" existant avec project_id.
2. Réutiliser le projet existant :
   • Si stitch.project_id existe, réutilisez TOUJOURS ce projectId directement pour tous les échafaudages d'écran, variantes et mises à jour du design system. N'appelez PAS create_project.
3. Créer et persister immédiatement (uniquement si absent) :
   • Si aucun stitch.project_id n'existe dans docs/project.json :
     • Appeler call_mcp_tool sur StitchMCP avec list_projects pour vérifier si un projet correspondant au titre du dépôt existe déjà.
     • Si aucun n'existe, appeler create_project avec title: "[Titre du projet] Design System & Components".
     • Persister IMMÉDIATEMENT les propriétés du projet dans docs/project.json sous "stitch" :

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

4. Injecter les tokens de conception :
   • Fournir le design system canonique du projet (depuis docs/project.json) à Stitch via upload_design_md ou create_design_system_from_design_md pour établir une cohérence globale des couleurs, polices et rayons.

---

Étape 3 : Génération d'écran et de variante via StitchMCP

1. Synthétiser un prompt de conception détaillé :
   • Combiner le but du composant, le persona utilisateur, le ton émotionnel et les exigences de mise en page de design-spec.md.
   • Spécifier explicitement les tokens visuels : toile de fond, cartes de surface, accent principal, accent secondaire, couleurs d'état et typographie de docs/project.json.
   • Spécifier la zone d'affichage cible : deviceType: "DESKTOP" (ou "MOBILE" / "TABLET" si le composant est mobile-first).
2. Générer l'écran principal :
   • Appeler generate_screen_from_text sur StitchMCP :
     • projectId : ID du projet Stitch actif.
     • prompt : Prompt de conception synthétisé.
     • deviceType : "DESKTOP".
   • Extraire l'ID de l'écran généré et le nom de la ressource (format : projects/{projectId}/screens/{screenId}).
3. Générer une variante :
   • Appeler generate_variants sur StitchMCP en utilisant l'ID de l'écran généré pour produire une variante spatiale/visuelle du fichier de spécification de conception (par exemple, explorer une densité de mise en page alternative, carte vs. pleine largeur, ou flux visuel asymétrique).
   • Enregistrer l'ID de l'écran de la variante.

---

Étape 4 : Protocole de téléchargement binaire-sûr des assets

[!CAUTION] PowerShell Invoke-WebRequest requis : Exécutez chaque commande de téléchargement comme une opération unique discrète. Vérifiez que chaque fichier téléchargé a une taille non nulle (> 10 Ko pour les JPG).

1. S'assurer que le répertoire existe :
   • Répertoire cible : docs/design/components/[nom de page]/[nom du composant]/stitch/.
2. Télécharger le JPG de l'écran principal :
   • Extraire screenshot.downloadUrl de la réponse de l'écran principal.
   • Exécuter :

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

3. Télécharger le HTML de l'écran principal :
   • Extraire htmlCode.downloadUrl de la réponse de l'écran principal.
   • Exécuter :

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

4. Télécharger le JPG de la variante 1 :
   • Extraire screenshot.downloadUrl de la réponse de la variante.
   • Exécuter :

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

5. Télécharger le HTML de la variante 1 :
   • Extraire htmlCode.downloadUrl de la réponse de la variante.
   • Exécuter :

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

6. Sauvegarder les métadonnées Stitch (stitch-meta.json) :
   • Écrire docs/design/components/[page]/[composant]/stitch/stitch-meta.json :

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

---

Étape 5 : Intégration des benchmarks dans la spécification de conception

Mettre à jour docs/design/components/[nom de page]/[nom du composant]/design-spec.md avec les résultats Stitch :

1. Intégrer l'écran principal et la variante Stitch :

   ## Architecture de mise en page et benchmarks Google Stitch
   
   ### Conception de l'écran principal
   ![Conception de l'écran principal](stitch/screen.jpg)
   
   ### Exploration de la variante 1
   ![Conception de la variante 1](stitch/variant-1.jpg)
   

2. Documenter les observations sur l'architecture de mise en page :
   • Noter la grille spatiale, le poids visuel, le rythme des espaces blancs et la hiérarchie typographique démontrés dans les écrans Stitch.
   • Comparer l'écran principal avec la variante 1, en soulignant les forces de chaque composition.

---

Étape 6 : Prompts d'assets visuels (le cas échéant)

[!NOTE] Si l'inspection des mises en page Stitch révèle un besoin d'assets visuels sur mesure (par exemple, arrière-plans d'ambiance, icônes personnalisées ou diagrammes), n'appelez PAS generate_image. Émettez des prompts structurés à l'utilisateur :

### Asset visuel recommandé : [Nom de l'asset]
- **Chemin du fichier cible :** `docs/design/components/[page]/[composant]/[nom_fichier].png`
- **Ratio d'aspect recommandé :** `16:9` ou `1:1`
- **Prompt de génération :**
  > "[Prompt détaillé décrivant l'asset visuel correspondant à la mise en page Stitch]"

---

Étape 7 : Boucle de vérification par sous-agent indépendant (invoke_subagent)

[!IMPORTANT] Protocole de révision par sous-agent : Vérifiez toujours les assets téléchargés et les mises à jour de spécification via un sous-agent indépendant avant de signaler la fin de l'exécution.

1. Lancer le sous-agent de vérification

Appeler invoke_subagent avec :

• TypeName : "self"
• Role : "Auditeur des assets et téléchargements Stitch"
• Model : "inherit"
• Prompt :

Vous êtes un auditeur indépendant des assets Stitch. Votre travail consiste à vérifier que les assets Google Stitch ont été téléchargés proprement et intégrés dans le répertoire du composant.

RÉPERTOIRE DU COMPOSANT CIBLE :
docs/design/components/[nom de page]/[nom du composant]/

Livrables à auditer :
1. docs/design/components/[nom de page]/[nom du composant]/stitch/screen.jpg (doit exister, octets non nuls)
2. docs/design/components/[nom de page]/[nom du composant]/stitch/screen.html (doit exister, HTML brut)
3. docs/design/components/[nom de page]/[nom du composant]/stitch/variant-1.jpg (doit exister, octets non nuls)
4. docs/design/components/[nom de page]/[nom du composant]/stitch/variant-1.html (doit exister, HTML brut)
5. docs/design/components/[nom de page]/[nom du composant]/stitch/stitch-meta.json (JSON valide avec projectId, screenId, generationPrompt, variantIds)
6. docs/design/components/[nom de page]/[nom du composant]/design-spec.md (doit intégrer stitch/screen.jpg et stitch/variant-1.jpg)

Auditer selon ces critères stricts :
1. Intégrité des fichiers binaires : Confirmer que screen.jpg et variant-1.jpg ne sont pas vides ou corrompus (taille > 10 Ko).
2. Intégrité du HTML : Confirmer que screen.html et variant-1.html sont des fichiers HTML valides et non du markdown corrompu.
3. Intégrité des métadonnées : Confirmer que stitch-meta.json a des champs valides.
4. Intégration dans la spécification : Confirmer que design-spec.md contient les liens de capture d'écran intégrés et les notes de benchmark de mise en page Stitch.
5. Conservation des tokens : Confirmer que generate_image n'a PAS été appelé directement.

Répondre dans ce format exact :
VERDICT : PASS | ISSUES_FOUND

ISSUS (le cas échéant) :
- EMPLACEMENT : {fichier:ligne ou section}
- PROBLÈME : {ce qui n'est pas conforme ou cassé}
- CORRECTION : {instruction concrète pour corriger}

RÉSUMÉ : {brève évaluation globale}

2. Évaluer la révision et résoudre les problèmes

Si ISSUES_FOUND, résolvez-les immédiatement (par exemple, en retéléchargeant tout asset défaillant ou en corrigeant les métadonnées) avant de terminer l'exécution.

---

3. Liste de vérification de l'exécution

Avant de terminer l'exécution, vérifier :

• design-spec.md a été ingéré depuis docs/design/components/[page]/[composant]/.
• L'ID du projet Stitch a été vérifié/réutilisé depuis docs/project.json (ou créé et immédiatement persisté).
• Les tokens de conception ont été injectés dans Stitch via upload_design_md ou create_design_system_from_design_md.
• L'écran principal a été généré via generate_screen_from_text.
• Exactement une variante a été générée via generate_variants.
• Tous les assets ont été téléchargés en utilisant PowerShell Invoke-WebRequest -OutFile (zéro utilisation de read_url_content).
• screen.jpg, screen.html, variant-1.jpg, variant-1.html sont sauvegardés dans stitch/ avec des tailles non nulles.
• stitch/stitch-meta.json a été sauvegardé avec des métadonnées complètes.
• design-spec.md a été mis à jour avec les captures d'écran intégrées et les benchmarks de mise en page Stitch.
• generate_image n'a PAS été appelé directement ; des prompts d'image ont été émis pour l'utilisateur si nécessaire.
• L'audit par sous-agent indépendant a été invoqué via invoke_subagent et a réussi.