Guia de solicitação do Agente de modernização de experiência prompting-guide

A migração segue um fluxo de trabalho de sete etapas:

1. O agente remove a página de origem.
2. Identifica a estrutura da seção.
3. Ele executa a análise de criação.
4. Ele mapeia o conteúdo para variantes de bloco.
5. Ele gera marcação.
6. Ele cria infraestrutura de importação.
7. Ele visualiza o resultado.

O agente analisa as páginas usando uma hierarquia de dois níveis:

• Primeiro, identifica os limites da seção (alterações no plano de fundo, deslocamentos de espaçamento)
• Em seguida, identifica as sequências de conteúdo em cada seção.

A análise de criação segue o Modelo de David.

• para cada sequência de conteúdo, ele verifica primeiro "Um autor pode criar isso digitando normalmente?"
• O conteúdo padrão (cabeçalhos, parágrafos, listas, imagens integradas) é preferível aos blocos.

O agente tenta reutilizar blocos existentes da biblioteca de blocos do repositório antes de criar outros novos.

• Quando o conteúdo não pode ser mapeado para um bloco existente, ele cria novas variantes de bloco.
• Você pode solicitar alterações, solicitar novas variantes ou ajustar mapeamentos interativamente.

As variantes de bloco são rastreadas com metadados.

• Ao migrar várias páginas, o agente carrega as variantes personalizadas existentes primeiro e as reutiliza quando o estilo é compatível (limite de similaridade de 70% com base na finalidade, nas cores, na tipografia, no espaçamento e no layout).

O cabeçalho, a navegação e o rodapé são excluídos da migração de página. Elas são tratadas por habilidades específicas.

Cada migração cria uma infraestrutura de importação (modelos de página, analisadores de blocos, transformadores) para importações futuras em massa.

• Isso inclui modelos de página (estrutura de seção), transformadores (limpeza DOM em todo o site) e analisadores (conversão de HTML em tabela específica de bloco).

• Ele não infere modelos do zero.

• Não há suporte para a combinação de modelos em uma única execução.

Normalmente, esse prompt é chamado automaticamente como a primeira etapa da migração da página.

O conteúdo oculto via CSS também é capturado se presente no DOM.

Imagens carregadas lentamente e conteúdo renderizado do lado do cliente são tratados ao rolar pela página no Chromium headless e permitir que os scripts sejam executados.

Imagens WebP/AVIF/SVG são convertidas em PNG para compatibilidade.

Os metadados são extraídos, incluindo título, descrição, tags Open Graph, dados estruturados JSON-LD e URL canônico.

As imagens no DOM são fixas.

• background-image é convertido em img.
• Os elementos da figura estão desenrolados
• srcset é resolvido como src
• URLs relativos são convertidos em absolutos
• O SVG em linha para é convertido em arquivos img.

Caminhos de documentos limpos são gerados (minúsculas sem extensão .html).

As seguintes saídas são produzidas:

• screenshot.png
• cleaned.html (sem scripts/estilos)
• metadata.json
• Pasta images/ com cópias locais

Os usuários podem perguntar sobre dimensões de captura de tela e solicitar tamanhos específicos de dispositivos (dispositivos móveis, desktop) para extração de conteúdo.

Extrair conteúdo em vários pontos de interrupção aumenta o tempo de processamento.

A migração do projeto tem duas fases:

1. A Fase 1 (em todo o site) extrai o seguinte para styles/styles.css:

   • Paleta de cores global e cores de ênfase
   • Sistema de tipografia (fontes, tamanhos, pesos)
   • Sistema de espaçamento (preenchimento, margens, espaços)
   • Planos de fundo da seção (claro, escuro, colorido)
   • Estilos básicos de componentes (botões, links, imagens)
   • Saídas para

2. A Fase 2 migra estilos de bloco individuais e cria CSS específico de bloco no /blocks/{name}/{name}.css.

O estilo de bloco (fase 2) requer que o design em todo o site (fase 1) seja concluído primeiro.

• O sistema de design global fornece propriedades personalizadas de CSS que bloqueiam a referência.

Tempo estimado:

• Fase 1: 5 a 10 minutos
• Fase 2: 10 a 15 minutos

As solicitações ambíguas são padronizadas para concluir a migração (ambas as fases).

A crítica de bloco compara um bloco migrado com sua origem original e aplica iterativamente correções CSS até que uma similaridade visual de 85% seja alcançada ou três iterações sejam concluídas.

A habilidade exige que o bloco seja criado primeiro pela migração de página.

Uma crítica de bloco segue um fluxo de trabalho de seis etapas:

1. Ele captura o bloco original da página de origem usando um seletor XPath.
2. Ele inicializa a sessão crítica.
3. Ele inspeciona o bloco original (capturas de tela, estilos, HTML).
4. Ele inspeciona o bloco migrado.
5. Ele compara elementos e gera uma pontuação de similaridade com correções CSS.
6. Ela aplica correções e inspeciona novamente até que o target de 85% seja atingido.

Cada iteração exibe um relatório de crítica completo com todas as diferenças, aplica todas as correções CSS (priorizadas por impacto visual), verifica na pré-visualização, inspeciona novamente e mostra métricas de melhoria.

Use a crítica de bloco após a migração de design ser concluída.

A crítica de página realiza uma comparação visual de página inteira entre a página original e a migrada, iterando até atingir uma meta de similaridade de 85% ou três iterações serem concluídas.

Uma crítica de página tem um fluxo de trabalho de cinco etapas:

1. Inicializa uma sessão crítica.
2. Ele inspeciona todos os elementos na página original.
3. Ele inspeciona todos os elementos na página migrada.
4. Ele compara e gera uma pontuação de similaridade com correções CSS priorizadas.
5. Ela aplica correções e inspeciona novamente até que o target de 85% seja atingido.

Uma crítica de página precisa do URL da página de origem e do caminho migrado (por exemplo, "/about") como entrada.

Use críticas de página ao validar a fidelidade geral da página ou ao validar vários blocos simultaneamente.

Use a crítica de bloco para validação focalizada em componentes específicos.

Recomenda-se o seguinte workflow:

1. Migrar uma página.
2. Aplicar um design.
3. Executar uma crítica de bloco nos blocos principais
4. Execute uma crítica de página de aplicativo para validação completa.

Essa habilidade migra um bloco de cada vez, não páginas inteiras ou arquivos Figma completos.

Para obter melhores resultados:

• Selecione o bloco específico que deseja migrar no Figma e copie seu link (com node-id) ou nome.
• Forneça o parâmetro node-id na URL para direcionar o bloco exato.

Quando você executa essa habilidade, as seguintes etapas são executadas automaticamente no ambiente hospedado:

1. Descoberta de estrutura de bloco — O agente lê o nó Figma para compreender camadas e componentes.
2. Extração de estilo global — O agente extrai cores, tipografia e espaçamento para styles/styles.css como propriedades personalizadas de CSS (tokens de design).
3. Criação de estilo específico de bloco — O agente cria propriedades personalizadas CSS adicionais específicas para o bloco que está sendo migrado.
4. Mapeamento para blocos existentes — O agente identifica o bloco correspondente mais próximo na biblioteca de blocos do projeto e cria uma variante personalizada.
5. Geração de CSS — o agente grava estilos que fazem referência às propriedades personalizadas de CSS extraídas, garantindo a consistência do design.
6. Download de ativos — o agente salva imagens e ícones do Figma no espaço de trabalho do ambiente hospedado.
7. Geração de conteúdo do Edge Delivery Services — O agente cria o arquivo de Markdown seguindo a estrutura de bloco do EDS
8. Validação de saída — o agente pré-visualiza o resultado e executa uma comparação visual com o design original do Figma.

A habilidade lê primeiro os metadados (etapa 1) para entender a estrutura e, em seguida, extrai o contexto detalhado do design (etapas 2 a 5).

• Essa abordagem em fases evita problemas com arquivos Figma grandes ou complexos.

Essa habilidade tem uma abordagem de estilo.

• Todos os estilos são extraídos como propriedades personalizadas de CSS (tokens de design) antes que qualquer CSS seja gravado.
• Isso garante que o bloco migrado permaneça consistente com seu sistema de design.

O prompt requer a URL do Figma (com fileKey e node-id opcional) ou uma chave de arquivo do Figma diretamente como entrada.

A navegação do Edge Delivery Services impõe uma estrutura de três seções (executada por header.js):

1. Marca (seção 1): link para o logotipo e marca primária
2. Seções (seção 2): menu de navegação principal com menus suspensos opcionais
3. Ferramentas (seção 3): links de utilitários (inscrição, logon, carrinho)

O conteúdo de navegação reside em nav.md no diretório raiz.

Seções são separadas por marcadores (---).

Itens em negrito (**Text**) com listas aninhadas criam menus suspensos.

Os links na navegação podem ser renderizados como botões devido ao comportamento de quebra automática da Criação de documento.

• O bloco de cabeçalho inclui código para retirar classes de botão de links de navegação.

O agente segue o CDD (Content-Driven Development, desenvolvimento orientado por conteúdo), um processo obrigatório para todo o desenvolvimento de Edge Delivery Services.

• Ele perguntará sobre modelos de conteúdo e testará o conteúdo antes de gravar o código.

A filosofia da CDD é que as necessidades do autor vêm antes das necessidades do desenvolvedor.

• Os modelos de conteúdo devem ser intuitivos para os autores, mesmo que isso signifique um código de decoração mais complexo.

A criação do conteúdo de teste primeiro fornece:

• Capacidade de teste imediato
• Links de validação de PR para verificações de PSI
• Documentação dinâmica para autores
• Detecção de casos de borda que falham das abordagens code-first

O agente procurará blocos semelhantes na Coleção de Blocos e na Parte do Bloco antes da implementação, para encontrar padrões e códigos reutilizáveis.

Ignorar o CDD somente para ajustes comuns somente em CSS (mas ainda identificar o conteúdo do teste para validação).

O Edge Delivery Services tem quatro tipos de modelo canônico:

• Independente: elementos visuais/narrativos distintos (herói, citação de bloqueio)
  • Tabela única com conteúdo de bloco
• Coleção: conteúdo semiestruturado repetitivo (cartões, carrossel)
  • Tabela com padrão de linha de repetição
• Configuração: conteúdo dinâmico ou orientado por API onde os controles de configuração são exibidos (listagem de blog, resultados de pesquisa)
  • Tabela com linhas de configuração de valor-chave.
• Bloqueado Automaticamente: estruturas complexas que os autores criam como seções/conteúdo padrão, então são transformadas (guias, incorporações do YouTube)

Há um limite de quatro células por linha.

• Agrupar elementos relacionados em células.

Prefira variantes de bloco a células de configuração para diferenças de estilo.

Siga a Lei do Postel: seja flexível quanto à estrutura de entrada.

• Um bloco herói deve funcionar independentemente de o conteúdo estar em uma célula, dividido em duas células ou em linhas separadas.

Normalmente, essa habilidade é chamada automaticamente pelo Desenvolvimento orientado por conteúdo durante a criação do bloco.

A Coleção de Blocos é mantida pela Adobe e testada para práticas recomendadas, modelagem de conteúdo excelente, alto desempenho e acessibilidade.

• É limitado aos blocos comumente necessários. Comece aqui.

O Bloco de Partes é conduzido pela comunidade e oferece uma variedade mais ampla, incluindo abordagens experimentais.

• Ele também inclui plug-ins do sidekick, ferramentas de build (webpack, vite, sass) e integrações.
• Use quando a Coleção de blocos não tiver o que você precisa.

Pense em nomes alternativos ao pesquisar

• Perguntas frequentes = Accordion
• Galeria = carrossel/apresentação de slides
• Navegação = menu/cabeçalho

A Parte do Bloco só retorna entradas aprovadas/com curadoria.

Os testes seguem uma filosofia de "valor vs. custo", na qual você cria e mantém testes quando o valor excede o custo.

• Testes de guardião (testes de unidade) são para utilitários lógicos pesados, processamento de dados, integrações de API. Elas são rápidas, fáceis de manter e capturam regressões no código reutilizado.
• Testes de descarte (testes de navegador) são para transformações DOM e validação visual. Use para validar a implementação, capturar capturas de tela para revisão de PR e, em seguida, descartar.

Os testes de descarte entram em test/tmp/ e testam o conteúdo em drafts/tmp/ (ambos gerados por gig).

Antes de abrir uma PR, verifique se:

• Os testes existentes foram bem-sucedidos
• Testes de unidade são escritos para a nova lógica
• Validação do navegador concluída
• Todas as variantes são testadas
• O comportamento responsivo é verificado
• Passes para listas

Problemas comuns têm padrões conhecidos:

• Imagens mostrando "sobre:error": geralmente falta a chamada createOptimizedPicture no bloco JS, ou chamada antes da reestruturação de DOM
• Blocos não renderizados: verifique o formato do nome do bloco no Markdown e verifique se o bloco tem arquivos .js e .css em blocks/.
• O CSS não está carregando: verifique os caminhos do arquivo, verifique se o arquivo CSS existe e verifique a guia Rede no navegador.
• As alterações não aparecem: a sincronização de código leva de 3 a 5 segundos. Experimente atualizar permanentemente (Ctrl+Shift+R).

O agente verifica sistematicamente cada camada:

1. Arquivos do Source
2. Saída renderizada
3. Código de bloco
4. Console do navegador

O agente pode verificar visualizações locais em http://localhost:3000.