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.

As imagens do Dynamic Media e do Scene7 são detectadas na origem e preservadas como URLs do DM, em vez de importadas como representações estáticas, de modo que as transformações responsivas e instantâneas permanecem intactas. Isso se aplica às migrações da Criação de documentos e do AEM Sites/Universal Editor.

• 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) gera styles/brand.css e styles/styles.css:

   • brand.css contém tokens de design como propriedades personalizadas de CSS (fontes, cores, espaçamento, tamanhos de cabeçalho).
   • styles.css importa brand.css e aplica os tokens ao conteúdo padrão (cabeçalhos, parágrafos, botões, links, fundos de seção).
   • Se seu projeto já tiver um brand.css, peça ao agente para usá-lo em vez de extrair da origem.

2. A Fase 2 estiliza blocos individuais em paralelo e cria CSS específico de bloco em /blocks/{name}/{name}.css, fazendo referência aos tokens de brand.css.

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

A Fase 2 atinge 80 a 90% de fidelidade de estilo em nível de bloco em uma única passagem.

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 correções até que uma similaridade 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.

A crítica detecta e corrige problemas de conteúdo/estruturais e problemas de estilo:

• Conteúdo/estrutural: cabeçalhos, parágrafos, links, contagem de linhas/células da tabela incorreta — corrigido com a atualização dos analisadores e a reimportação.
• Estilo: diferenças de CSS em cores, espaçamento, tipografia, layout — corrigidas atualizando o bloco CSS.

A cascata de correção é executada em ordem: estilos globais → transformadores de seção → analisadores de conteúdo/estruturais → bloquear CSS. Cada camada é reimportada e reavaliada antes de passar para a próxima.

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

A crítica do site valida todos os blocos em todos os modelos migrados usando subagentes paralelos, um por modelo.

Aplica a mesma cascata de correção que a crítica de bloco (estilos globais → transformadores de seção → analisadores de conteúdo/estruturais → bloco CSS), mas em todas as páginas simultaneamente.

As correções são desduplicadas — se o mesmo problema aparecer em várias páginas usando o mesmo bloco, a correção será aplicada uma vez.

Se brand.css ainda não existir, a crítica é executada no modo somente estrutura de conteúdo (corrigindo analisadores e transformadores sem estilo).

A crítica do site é a abordagem recomendada após a migração do design para projetos de várias páginas.

Recomenda-se o seguinte workflow:

1. Migrar páginas (únicas ou em massa).
2. Executar migração de design.
3. Execute critique site para validar e corrigir automaticamente as lacunas restantes em todos os modelos.

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 Edge Delivery Services
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.