BIGboss248/nextjs-wordpress

Habilidade de Prototipagem de UI do Google Stitch e Variantes (stitch-design)

Esta habilidade define o fluxo de trabalho completo para pegar uma especificação de design de componente estabelecida (design-spec.md) e usar o Google Stitch (StitchMCP) para estruturar layouts de tela, gerar variantes espaciais, baixar ativos visuais de alta resolução (capturas de tela JPG e exportações HTML brutas) para o código-fonte e atualizar a especificação de design com benchmarks concretos de layout.

[!IMPORTANT] Pré-requisito de Entrada: Esta habilidade requer uma especificação de design concluída em docs/design/components/[nome da página]/[nome do componente]/design-spec.md (normalmente gerada por component-design). Se nenhuma especificação existir, execute /component-design primeiro.

[!CAUTION] Regra de Segurança para Download Binário: NUNCA use read_url_content para baixar capturas de tela JPG ou exportações HTML do Stitch. read_url_content é apenas para texto e converte respostas para markdown, corrompendo imagens binárias e danificando a estrutura HTML. Todos os downloads DEVEM usar run_command com Invoke-WebRequest do PowerShell. As URLs de download assinadas expiram rapidamente — baixe imediatamente ao receber a resposta do Stitch.

[!TIP] Geração de Imagem Zero Dentro da Habilidade (Regra de Conservação de Tokens): Para conservar tokens, esta habilidade NÃO DEVE invocar generate_image diretamente. Se a tela exigir imagens de fundo personalizadas, ilustrações ou ícones, formule e gere prompts estruturados para o usuário, para que ele mesmo possa gerar e posicionar esses arquivos no projeto.

---

1. Principais Entregas e Visão Geral do Fluxo de Trabalho

flowchart TD
    Start["Invocar /stitch-design<br/>(Alvo: docs/design/components/[pagina]/[componente]/design-spec.md)"] --> Step1["Passo 1: Ingerir Especificação de Design<br/>(Ler design-spec.md e docs/project.json)"]
    Step1 --> Step2["Passo 2: Persistência do Projeto Stitch e Semeadura de Tokens<br/>(Verificar/reutilizar stitch.project_id em docs/project.json, semear sistema de design)"]
    Step2 --> Step3["Passo 3: Geração de Tela e Variante via StitchMCP<br/>(generate_screen_from_text + generate_variants para 1 variante)"]
    Step3 --> Step4["Passo 4: Download Seguro de Ativos Binários<br/>(PowerShell Invoke-WebRequest → stitch/screen.jpg, screen.html, variant-1.jpg, variant-1.html)"]
    Step4 --> Step5["Passo 5: Integração de Benchmark na Especificação de Design<br/>(Inserir stitch/screen.jpg e benchmarks de variante em design-spec.md)"]
    Step5 --> Step6["Passo 6: Verificação por Subagente Independente<br/>(invoke_subagent verifica tamanhos de arquivo, metadados e alinhamento da especificação)"]
    Step6 --> Finish["Protótipos Visuais Prontos<br/>(JPG + HTML do Stitch salvos no código-fonte)"]

Entrega: A Subpasta de Ativos Stitch

Cada execução do Stitch cria ou popula a subpasta stitch/ dentro do diretório de design do componente:

docs/design/components/[nome da página]/[nome do componente]/
├── design-spec.md          # Atualizado com benchmarks do Stitch e capturas de tela incorporadas
└── stitch/                 # Arquivos de design baixados do Google Stitch
    ├── screen.jpg          # Captura de tela JPG gerada pelo Stitch da tela primária
    ├── screen.html         # Exportação HTML bruta gerada pelo Stitch da tela primária
    ├── variant-1.jpg       # Captura de tela JPG gerada pelo Stitch da variante
    ├── variant-1.html      # Exportação HTML bruta gerada pelo Stitch da variante
    └── stitch-meta.json    # ID do projeto Stitch, ID da tela, IDs das variantes e prompt de geração

---

2. Fluxo de Execução Passo a Passo

Passo 1: Ingerir Especificação de Design e Contexto do Projeto

1. Localizar o Componente Alvo:
   • Identifique o caminho do componente: docs/design/components/[nome da página]/[nome do componente]/.
   • Leia design-spec.md para extrair:
     • Resumo executivo, persona e tom emocional.
     • Hierarquia visual (1º, 2º e 3º pontos focais).
     • Grade de layout e comportamentos de breakpoint.
     • Tokens de design (cores, raios, elevação).
     • Pares tipográficos por localidade.
2. Ler Contexto do Projeto:
   • Leia docs/project.json para verificar o sistema de design canônico e buscar uma configuração existente do Stitch.

---

Passo 2: Persistência do Projeto Google Stitch e Semeadura do Sistema de Design (StitchMCP)

[!IMPORTANT] Regra de Um Único Projeto por Repositório (Zero Projetos Duplicados): Cada repositório deve manter exatamente um contêiner de projeto Google Stitch compartilhado para todos os seus designs de componentes e telas. NUNCA crie múltiplos projetos Stitch para o mesmo repositório.

1. Verificar docs/project.json Primeiro:
   • Inspecione docs/project.json em busca de um objeto "stitch" existente com project_id.
2. Reutilizar Projeto Existente:
   • Se stitch.project_id existir, SEMPRE reutilize esse projectId diretamente para toda estruturação de telas, variantes e atualizações do sistema de design. Não chame create_project.
3. Criar e Imediatamente Persistir (Apenas se Ausente):
   • Se nenhum stitch.project_id existir em docs/project.json:
     • Chame call_mcp_tool no StitchMCP com list_projects para verificar se já existe um projeto com o título do repositório.
     • Se nenhum existir, chame create_project com title: "[Título do Projeto] Design System & Components".
     • IMEDIATAMENTE persista as propriedades do projeto em docs/project.json sob "stitch":

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

4. Semear Tokens de Design:
   • Forneça o sistema de design canônico do projeto (de docs/project.json) ao Stitch via upload_design_md ou create_design_system_from_design_md para estabelecer consistência global de cores, fontes e raios.

---

Passo 3: Geração de Tela e Variante via StitchMCP

1. Sintetizar Prompt de Design Detalhado:
   • Combine o propósito do componente, persona do usuário, tom emocional e requisitos de layout de design-spec.md.
   • Especifique explicitamente os tokens visuais: tela de fundo, cartões de superfície, destaque primário, destaque secundário, cores de estado e tipografia de docs/project.json.
   • Especifique o viewport alvo: deviceType: "DESKTOP" (ou "MOBILE" / "TABLET" se o componente for mobile-first).
2. Gerar Tela Primária:
   • Chame generate_screen_from_text no StitchMCP:
     • projectId: ID do projeto Stitch ativo.
     • prompt: Prompt de design sintetizado.
     • deviceType: "DESKTOP".
   • Extraia o ID da tela gerada e o nome do recurso (formato: projects/{projectId}/screens/{screenId}).
3. Gerar Uma Variante:
   • Chame generate_variants no StitchMCP usando o ID da tela gerada para produzir uma variante espacial/visual do arquivo de especificação (por exemplo, explorando uma densidade de layout alternativa, cartão vs. sangria total, ou fluxo visual assimétrico).
   • Registre o ID da tela da variante.

---

Passo 4: Protocolo de Download Seguro de Ativos Binários

[!CAUTION] PowerShell Invoke-WebRequest Obrigatório: Execute cada comando de download como uma operação única e discreta. Verifique se cada arquivo baixado possui tamanho diferente de zero (> 10KB para JPGs).

1. Garantir que o Diretório Exista:
   • Diretório alvo: docs/design/components/[nome da página]/[nome do componente]/stitch/.
2. Baixar JPG da Tela Primária:
   • Extraia screenshot.downloadUrl da resposta da tela primária.
   • Execute:

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

3. Baixar HTML da Tela Primária:
   • Extraia htmlCode.downloadUrl da resposta da tela primária.
   • Execute:

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

4. Baixar JPG da Variante 1:
   • Extraia screenshot.downloadUrl da resposta da variante.
   • Execute:

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

5. Baixar HTML da Variante 1:
   • Extraia htmlCode.downloadUrl da resposta da variante.
   • Execute:

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

6. Salvar Metadados do Stitch (stitch-meta.json):
   • Escreva docs/design/components/[pagina]/[componente]/stitch/stitch-meta.json:

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

---

Passo 5: Integração de Benchmark na Especificação de Design

Atualize docs/design/components/[nome da página]/[nome do componente]/design-spec.md com os resultados do Stitch:

1. Incorporar Tela Primária e Variante do Stitch:

   ## Arquitetura de Layout e Benchmarks do Google Stitch
   
   ### Design da Tela Primária
   ![Design da Tela Primária](stitch/screen.jpg)
   
   ### Exploração da Variante 1
   ![Design da Variante 1](stitch/variant-1.jpg)
   

2. Documentar Observações da Arquitetura de Layout:
   • Anote a grade espacial, peso visual, ritmo de espaços em branco e hierarquia tipográfica demonstrados nas telas do Stitch.
   • Compare a tela primária com a Variante 1, destacando os pontos fortes de cada composição.

---

Passo 6: Prompts de Ativos Visuais (Se Aplicável)

[!NOTE] Se ao inspecionar os layouts do Stitch surgir a necessidade de ativos visuais personalizados (por exemplo, fundos ambientes, ícones personalizados ou diagramas), NÃO chame generate_image. Gere prompts estruturados para o usuário:

### Ativo Visual Recomendado: [Nome do Ativo]
- **Caminho do Arquivo Alvo:** `docs/design/components/[pagina]/[componente]/[nome-do-arquivo].png`
- **Proporção Recomendada:** `16:9` ou `1:1`
- **Prompt de Geração:**
  > "[Prompt detalhado descrevendo o ativo visual que corresponde ao layout do Stitch]"

---

Passo 7: Laço de Verificação por Subagente Independente (invoke_subagent)

[!IMPORTANT] Protocolo de Revisão por Subagente: Sempre verifique os ativos baixados e as atualizações da especificação por meio de um subagente independente antes de relatar a conclusão.

1. Criar Subagente de Verificação

Chame invoke_subagent com:

• TypeName: "self"
• Role: "Stitch Asset & Download Auditor"
• Model: "inherit"
• Prompt:

Você é um Auditor de Ativos Stitch independente. Seu trabalho é verificar se os ativos do Google Stitch foram baixados corretamente e integrados ao diretório do componente.

DIRETÓRIO ALVO DO COMPONENTE:
docs/design/components/[nome da página]/[nome do componente]/

Entregas para Auditar:
1. docs/design/components/[nome da página]/[nome do componente]/stitch/screen.jpg (deve existir, bytes não nulos)
2. docs/design/components/[nome da página]/[nome do componente]/stitch/screen.html (deve existir, HTML bruto)
3. docs/design/components/[nome da página]/[nome do componente]/stitch/variant-1.jpg (deve existir, bytes não nulos)
4. docs/design/components/[nome da página]/[nome do componente]/stitch/variant-1.html (deve existir, HTML bruto)
5. docs/design/components/[nome da página]/[nome do componente]/stitch/stitch-meta.json (JSON válido com projectId, screenId, generationPrompt, variantIds)
6. docs/design/components/[nome da página]/[nome do componente]/design-spec.md (deve incorporar stitch/screen.jpg e stitch/variant-1.jpg)

Audite com base nestes critérios rigorosos:
1. Integridade do Arquivo Binário: Confirme que screen.jpg e variant-1.jpg não estão vazios ou corrompidos (tamanho > 10KB).
2. Integridade do HTML: Confirme que screen.html e variant-1.html são arquivos HTML válidos e não markdown corrompido.
3. Integridade dos Metadados: Confirme que stitch-meta.json possui campos válidos.
4. Integração da Especificação: Confirme que design-spec.md contém os links das capturas de tela incorporadas e anotações de benchmark do layout Stitch.
5. Conservação de Tokens: Confirme que generate_image NÃO foi chamado diretamente.

Responda neste formato exato:
VEREDITO: APROVADO | PROBLEMAS_ENCONTRADOS

PROBLEMAS (se houver):
- LOCALIZAÇÃO: {arquivo:linha ou seção}
- PROBLEMA: {o que está não conforme ou quebrado}
- CORREÇÃO: {instrução concreta para corrigir}

RESUMO: {breve avaliação geral}

2. Avaliar Revisão e Resolver

Se PROBLEMAS_ENCONTRADOS, resolva imediatamente (por exemplo, baixando novamente qualquer ativo com falha ou corrigindo metadados) antes de concluir a execução.

---

3. Lista de Verificação de Execução

Antes de concluir a execução, verifique:

• design-spec.md foi ingerido de docs/design/components/[pagina]/[componente]/.
• O ID do projeto Stitch foi verificado/reutilizado de docs/project.json (ou criado e imediatamente persistido).
• Os tokens de design foram semeados no Stitch via upload_design_md ou create_design_system_from_design_md.
• A tela primária foi gerada via generate_screen_from_text.
• Exatamente uma variante foi gerada via generate_variants.
• Todos os ativos foram baixados usando PowerShell Invoke-WebRequest -OutFile (zero uso de read_url_content).
• screen.jpg, screen.html, variant-1.jpg, variant-1.html estão salvos em stitch/ com tamanhos diferentes de zero.
• stitch/stitch-meta.json foi salvo com metadados completos.
• design-spec.md foi atualizado com capturas de tela incorporadas e benchmarks de layout do Stitch.
• generate_image NÃO foi chamado diretamente; prompts de imagem foram fornecidos ao usuário, se necessário.
• A auditoria independente do subagente foi invocada via invoke_subagent e foi aprovada.