Prototipado UI con Google Stitch y Variantes (stitch-design)

Skill de Prototipado UI y Variantes con Google Stitch (stitch-design)

Este skill define el flujo de trabajo completo para tomar una especificación de diseño de componente (design-spec.md) y usar Google Stitch (StitchMCP) para estructurar layouts de pantalla, generar variantes espaciales, descargar activos visuales de alta resolución (capturas JPG y exportaciones HTML en bruto) dentro del código fuente, y actualizar la especificación de diseño con benchmarks concretos de layout.

[!IMPORTANTE] Prerrequisito de entrada: Este skill requiere una especificación de diseño completada en docs/design/components/[nombre de página]/[nombre de componente]/design-spec.md (generada típicamente por component-design). Si no existe ninguna especificación, ejecute primero /component-design.

[!PRECAUCIÓN] Regla de descarga binaria segura: NUNCA use read_url_content para descargar capturas JPG o exportaciones HTML de Stitch. read_url_content es solo texto y convierte las respuestas a markdown, corrompiendo imágenes binarias y alterando la estructura HTML. Todas las descargas DEBEN usar run_command con PowerShell Invoke-WebRequest -Uri <url> -OutFile <path>. Las URLs de descarga firmadas caducan rápidamente: descargue inmediatamente al recibir la respuesta de Stitch.

[!SUGERENCIA] Cero generación de imágenes dentro del skill (Regla de conservación de tokens): Para conservar tokens, este skill NO DEBE invocar generate_image directamente. Si la pantalla requiere imágenes de fondo personalizadas, ilustraciones o iconos, formule y emita indicaciones estructuradas al usuario para que las genere y las coloque en los archivos del proyecto.

---

1. Entregables principales y resumen del flujo de trabajo

flowchart TD
    Start["Invocar /stitch-design<br/>(Objetivo: docs/design/components/[página]/[componente]/design-spec.md)"] --> Step1["Paso 1: Ingresar especificación de diseño<br/>(Leer design-spec.md y docs/project.json)"]
    Step1 --> Step2["Paso 2: Persistencia del proyecto Stitch y siembra de tokens<br/>(Verificar/reutilizar stitch.project_id en docs/project.json, sembrar sistema de diseño)"]
    Step2 --> Step3["Paso 3: Generación de pantalla y variante mediante StitchMCP<br/>(generate_screen_from_text + generate_variants para 1 variante)"]
    Step3 --> Step4["Paso 4: Descarga segura de activos binarios<br/>(PowerShell Invoke-WebRequest → stitch/screen.jpg, screen.html, variant-1.jpg, variant-1.html)"]
    Step4 --> Step5["Paso 5: Integración de benchmarks en la especificación de diseño<br/>(Insertar stitch/screen.jpg y benchmarks de variante en design-spec.md)"]
    Step5 --> Step6["Paso 6: Verificación con subagente independiente<br/>(invoke_subagent verifica tamaños de archivo, metadatos y alineación con la especificación)"]
    Step6 --> Finish["Prototipos visuales listos<br/>(JPG + HTML de Stitch guardados en el código fuente)"]

Entregable: La subcarpeta de activos Stitch

Cada ejecución de Stitch crea o puebla la subcarpeta stitch/ dentro del directorio de diseño del componente:

docs/design/components/[nombre de página]/[nombre de componente]/
├── design-spec.md          # Actualizada con benchmarks de Stitch y capturas incrustadas
└── stitch/                 # Archivos de diseño descargados de Google Stitch
    ├── screen.jpg          # Captura JPG generada por Stitch de la pantalla principal
    ├── screen.html         # Exportación HTML en bruto generada por Stitch de la pantalla principal
    ├── variant-1.jpg       # Captura JPG generada por Stitch de la variante
    ├── variant-1.html      # Exportación HTML en bruto generada por Stitch de la variante
    └── stitch-meta.json    # ID del proyecto Stitch, ID de pantalla, IDs de variantes y prompt de generación

---

2. Flujo de ejecución paso a paso

Paso 1: Ingresar especificación de diseño y contexto del proyecto

1. Localizar el componente objetivo:
   • Identificar la ruta del componente: docs/design/components/[nombre de página]/[nombre de componente]/.
   • Leer design-spec.md para extraer:
     • Resumen ejecutivo, persona y tono emocional.
     • Jerarquía visual (1º, 2º y 3º puntos focales).
     • Cuadrícula de layout y comportamientos de punto de ruptura.
     • Tokens de diseño (colores, radios, elevación).
     • Combinaciones tipográficas por configuración regional.
2. Leer el contexto del proyecto:
   • Leer docs/project.json para verificar el sistema de diseño canónico y buscar una configuración existente de Stitch.

---

Paso 2: Persistencia del proyecto Google Stitch y siembra del sistema de diseño (StitchMCP)

[!IMPORTANTE] Regla de un único proyecto por repositorio (Cero proyectos duplicados): Cada repositorio debe mantener exactamente un contenedor de proyecto Google Stitch compartido para todos sus componentes y diseños de pantalla. NUNCA cree múltiples proyectos Stitch para el mismo repositorio.

1. Verificar docs/project.json primero:
   • Inspeccionar docs/project.json en busca de un objeto "stitch" existente con project_id.
2. Reutilizar proyecto existente:
   • Si existe stitch.project_id, SIEMPRE reutilizar ese projectId directamente para toda la estructuración de pantallas, variantes y actualizaciones del sistema de diseño. No llamar a create_project.
3. Crear y persistir inmediatamente (Solo si está ausente):
   • Si no hay stitch.project_id en docs/project.json:
     • Llamar a call_mcp_tool en StitchMCP con list_projects para verificar si ya existe un proyecto que coincida con el título del repositorio.
     • Si no existe ninguno, llamar a create_project con title: "[Título del Proyecto] Sistema de diseño y componentes".
     • PERSISTIR INMEDIATAMENTE las propiedades del proyecto en docs/project.json bajo "stitch":

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

4. Sembrar tokens de diseño:
   • Proporcionar el sistema de diseño canónico del proyecto (desde docs/project.json) a Stitch mediante upload_design_md o create_design_system_from_design_md para establecer consistencia global de color, fuente y radio.

---

Paso 3: Generación de pantalla y variante mediante StitchMCP

1. Sintetizar un prompt de diseño detallado:
   • Combinar el propósito del componente, la persona de usuario, el tono emocional y los requisitos de layout de design-spec.md.
   • Especificar explícitamente los tokens visuales: lienzo de fondo, tarjetas de superficie, acento primario, acento secundario, colores de estado y tipografía de docs/project.json.
   • Especificar el viewport objetivo: deviceType: "DESKTOP" (o "MOBILE" / "TABLET" si se apunta a un componente mobile-first).
2. Generar la pantalla principal:
   • Llamar a generate_screen_from_text en StitchMCP:
     • projectId: ID del proyecto Stitch activo.
     • prompt: Prompt de diseño sintetizado.
     • deviceType: "DESKTOP".
   • Extraer el ID de pantalla generado y el nombre del recurso (formato: projects/{projectId}/screens/{screenId}).
3. Generar una variante:
   • Llamar a generate_variants en StitchMCP usando el ID de pantalla generado para producir una variante espacial/visual del archivo de especificación de diseño (por ejemplo, explorar una densidad de layout alternativa, tarjeta vs. sangría completa, o flujo visual asimétrico).
   • Registrar el ID de pantalla de la variante.

---

Paso 4: Protocolo de descarga segura de activos binarios

[!PRECAUCIÓN] Se requiere PowerShell Invoke-WebRequest: Ejecutar cada comando de descarga como una operación única discreta. Verificar que cada archivo descargado tenga un tamaño de bytes distinto de cero (> 10KB para JPGs).

1. Asegurar que el directorio existe:
   • Directorio objetivo: docs/design/components/[nombre de página]/[nombre de componente]/stitch/.
2. Descargar JPG de la pantalla principal:
   • Extraer screenshot.downloadUrl de la respuesta de la pantalla principal.
   • Ejecutar:

     powershell -Command "Invoke-WebRequest -Uri '<screenshot.downloadUrl>' -OutFile 'docs/design/components/[página]/[componente]/stitch/screen.jpg'"
     

3. Descargar HTML de la pantalla principal:
   • Extraer htmlCode.downloadUrl de la respuesta de la pantalla principal.
   • Ejecutar:

     powershell -Command "Invoke-WebRequest -Uri '<htmlCode.downloadUrl>' -OutFile 'docs/design/components/[página]/[componente]/stitch/screen.html'"
     

4. Descargar JPG de la variante 1:
   • Extraer screenshot.downloadUrl de la respuesta de la variante.
   • Ejecutar:

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

5. Descargar HTML de la variante 1:
   • Extraer htmlCode.downloadUrl de la respuesta de la variante.
   • Ejecutar:

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

6. Guardar metadatos de Stitch (stitch-meta.json):
   • Escribir docs/design/components/[página]/[componente]/stitch/stitch-meta.json:

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

---

Paso 5: Integración de benchmarks en la especificación de diseño

Actualizar docs/design/components/[nombre de página]/[nombre de componente]/design-spec.md con los resultados de Stitch:

1. Incrustar la pantalla principal de Stitch y la variante:

   ## Arquitectura de layout y benchmarks de Google Stitch
   
   ### Diseño de pantalla principal
   ![Diseño de pantalla principal](stitch/screen.jpg)
   
   ### Exploración de variante 1
   ![Diseño de variante 1](stitch/variant-1.jpg)
   

2. Documentar observaciones de la arquitectura de layout:
   • Anotar la cuadrícula espacial, el peso visual, el ritmo de espacios en blanco y la jerarquía tipográfica demostrados en las pantallas de Stitch.
   • Comparar la pantalla principal con la variante 1, destacando las fortalezas de cada composición.

---

Paso 6: Indicaciones de activos visuales (si aplica)

[!NOTA] Si al inspeccionar los layouts de Stitch se revela la necesidad de activos visuales personalizados (por ejemplo, fondos ambientales, iconos personalizados o diagramas), NO llamar a generate_image. Emitir indicaciones estructuradas al usuario:

### Activo visual recomendado: [Nombre del activo]
- **Ruta de archivo objetivo:** `docs/design/components/[página]/[componente]/[nombre_archivo].png`
- **Relación de aspecto recomendada:** `16:9` o `1:1`
- **Prompt de generación:**
  > "[Prompt detallado que describe el activo visual que coincide con el layout de Stitch]"

---

Paso 7: Bucle de verificación con subagente independiente (invoke_subagent)

[!IMPORTANTE] Protocolo de revisión por subagente: Siempre verificar los activos descargados y las actualizaciones de la especificación mediante un subagente independiente antes de informar la finalización.

1. Iniciar el subagente de verificación

Llamar a invoke_subagent con:

• TypeName: "self"
• Role: "Auditor de activos y descargas de Stitch"
• Model: "inherit"
• Prompt:

Eres un auditor independiente de activos de Stitch. Tu trabajo es verificar que los activos de Google Stitch se hayan descargado limpiamente y se hayan integrado en el directorio del componente.

DIRECTORIO DEL COMPONENTE OBJETIVO:
docs/design/components/[nombre de página]/[nombre de componente]/

Entregables a auditar:
1. docs/design/components/[nombre de página]/[nombre de componente]/stitch/screen.jpg (debe existir, bytes distintos de cero)
2. docs/design/components/[nombre de página]/[nombre de componente]/stitch/screen.html (debe existir, HTML en bruto)
3. docs/design/components/[nombre de página]/[nombre de componente]/stitch/variant-1.jpg (debe existir, bytes distintos de cero)
4. docs/design/components/[nombre de página]/[nombre de componente]/stitch/variant-1.html (debe existir, HTML en bruto)
5. docs/design/components/[nombre de página]/[nombre de componente]/stitch/stitch-meta.json (JSON válido con projectId, screenId, generationPrompt, variantIds)
6. docs/design/components/[nombre de página]/[nombre de componente]/design-spec.md (debe incrustar stitch/screen.jpg y stitch/variant-1.jpg)

Auditar según estos criterios estrictos:
1. Integridad de archivos binarios: Confirmar que screen.jpg y variant-1.jpg no están vacíos ni corruptos (tamaño > 10KB).
2. Integridad HTML: Confirmar que screen.html y variant-1.html son archivos HTML válidos y no markdown corrupto.
3. Integridad de metadatos: Confirmar que stitch-meta.json tiene campos válidos.
4. Integración en la especificación: Confirmar que design-spec.md contiene los enlaces a las capturas incrustadas y las notas de benchmark de layout de Stitch.
5. Conservación de tokens: Confirmar que NO se llamó a generate_image directamente.

Responder en este formato exacto:
VEREDICTO: APROBADO | PROBLEMAS_ENCONTRADOS

PROBLEMAS (si los hay):
- UBICACIÓN: {archivo:línea o sección}
- PROBLEMA: {qué no cumple o está roto}
- SOLUCIÓN: {instrucción concreta para solucionar}

RESUMEN: {breve evaluación general}

2. Evaluar la revisión y resolver

Si se encuentran PROBLEMAS_ENCONTRADOS, resolverlos inmediatamente (por ejemplo, volviendo a descargar cualquier activo fallido o corrigiendo los metadatos) antes de completar la ejecución.

---

3. Lista de verificación de ejecución

Antes de completar la ejecución, verificar:

• Se ingirió design-spec.md desde docs/design/components/[página]/[componente]/.
• Se verificó/reutilizó el ID del proyecto Stitch de docs/project.json (o se creó y persistió inmediatamente).
• Se sembraron los tokens de diseño en Stitch mediante upload_design_md o create_design_system_from_design_md.
• Se generó la pantalla principal mediante generate_screen_from_text.
• Se generó exactamente una variante mediante generate_variants.
• Todos los activos se descargaron usando PowerShell Invoke-WebRequest -OutFile (cero uso de read_url_content).
• screen.jpg, screen.html, variant-1.jpg, variant-1.html están guardados en stitch/ con tamaños distintos de cero.
• stitch/stitch-meta.json se guardó con metadatos completos.
• design-spec.md se actualizó con capturas incrustadas y benchmarks de layout de Stitch.
• NO se llamó a generate_image directamente; se emitieron prompts de imagen al usuario si era necesario.
• Se invocó la auditoría del subagente independiente mediante invoke_subagent y se superó.