Paidax01/web-to-design-md

Website para DESIGN.md

Visão Geral

Use esta skill para transformar um site real em um documento design.md ou DESIGN.md reutilizável, além de uma prévia HTML complementar.

O objetivo não é clonar o site. O objetivo é inspecioná-lo profundamente o suficiente para que outro agente possa recriar a mesma linguagem de design, tom de conteúdo e sensação de interação sem precisar ver o site original.

A prévia HTML é uma superfície de revisão prática. Ela deve traduzir o markdown em um painel de design visualizável para que o usuário possa inspecionar paleta, tipografia, espaçamento, dicas de componentes e o código-fonte markdown bruto sem reabrir o site.

Regra Universal do Navegador

Esta skill deve sempre usar agent-browser primeiro.

• Use agent-browser open, agent-browser wait e especialmente agent-browser eval como o fluxo de trabalho de extração principal.
• Não comece verificando em qual aplicativo ou plataforma o usuário está.
• Não faça ramificação de lógica com base em se o usuário está usando Codex, Trae, Claude, Cursor ou outro host.
• Não comece verificando se a pasta do projeto atual contém Playwright, Chrome CLI ou um pacote de navegador local.
• Se agent-browser não estiver disponível, ajude o usuário a instalá-lo ou expô-lo no PATH e continue com o mesmo fluxo de trabalho.
• Não mude silenciosamente para Playwright, Chrome CLI ou extração baseada em captura de tela, a menos que o usuário peça explicitamente por um fallback separado.

Estilo de Trabalho

Trabalhe primeiro com navegador e com evidências.

• Prefira agent-browser em vez de buscas HTML brutas. Um site ativo geralmente esconde comportamentos importantes por trás de hidratação, estado de rolagem, estado de hover ou alterações de layout responsivo.
• Trate agent-browser eval como a camada de extração principal. As principais evidências devem vir da estrutura DOM, HTML renderizado, estilos computados, variáveis CSS, regras de folha de estilo legíveis e estados de interação coletados dentro do ambiente de execução do navegador.
• Não use capturas de tela como fonte de evidência padrão. Quando agent-browser eval ou um caminho equivalente de avaliação de página estiver disponível, use DOM, estilos computados, variáveis CSS, regras de folha de estilo legíveis e texto extraído como evidência principal.
• Use capturas de tela apenas como uma verificação cruzada opcional de último recurso quando as evidências DOM forem insuficientes ou quando o usuário pedir explicitamente por uma verificação visual.
• Não recorra silenciosamente ao Playwright ou Chrome CLI. Se agent-browser não estiver disponível, detecte isso explicitamente e ajude o usuário a instalá-lo ou expô-lo.
• Trate arquivos de código-fonte estáticos como evidência de apoio, não como a principal fonte de verdade.
• Traduza detalhes técnicos em linguagem de design. Não despeje CSS cegamente; sintetize-o em algo que um agente possa realmente usar.
• Diferencie fatos observados de inferências. Se algo for um julgamento ou uma regra provável, em vez de um valor diretamente observado, rotule-o claramente.
• Trate a prévia HTML como parte da entrega padrão, não como um extra opcional, a menos que o usuário opte explicitamente por não incluí-la.

Pré-verificação

1. Normalize o destino em uma ou mais URLs.
2. Verifique se agent-browser já está utilizável.
3. Se agent-browser estiver faltando, use scripts/check-browser-tooling.mjs e, em seguida, ajude o usuário a instalar ou expor agent-browser.
4. Não inspecione a pasta atual em busca de executáveis Playwright, Chrome CLI ou navegadores locais como caminho principal.
5. Não recorra silenciosamente ao Playwright ou Chrome CLI, a menos que o usuário peça explicitamente por esse fallback.
6. Defina como padrão o arquivo de saída markdown como DESIGN.md.
7. Defina como padrão o arquivo de prévia complementar com o mesmo nome base mais -preview.html, por exemplo, DESIGN-preview.html ou design-preview.html.
8. Se o usuário pedir explicitamente por design.md, um nome de arquivo personalizado ou uma pasta personalizada, atenda exatamente a isso e mantenha a prévia HTML ao lado, a menos que o usuário peça o contrário.
9. Se várias URLs forem fornecidas, inspecione cada uma independentemente e, em seguida, sintetize um sistema de design compartilhado apenas quando a linguagem visual for claramente consistente entre as páginas.

Inicialização de Ferramentas de Navegador

Trate a configuração de ferramentas de navegador como parte da skill, não como uma tarefa separada do usuário.

Detecção

Verifique nesta ordem:

• se agent-browser já pode ser chamado
• se não, se pode ser instalado ou exposto imediatamente

O script de verificação incluído relata:

• se node e npm estão disponíveis
• se agent-browser pode ser chamado
• qual ferramenta deve ser usada em seguida
• se a instalação é recomendada

Instalação Padrão

Se agent-browser não estiver disponível, ajude o usuário a instalá-lo ou expô-lo no PATH e verifique com agent-browser --help antes de usar a skill.

Comportamento de Instalação

• Explique que a instalação é necessária para que a skill possa usar agent-browser de forma consistente.
• Se a primeira tentativa de instalação falhar devido a restrições de rede ou sandbox, solicite a aprovação necessária e tente novamente.
• Se a instalação for bem-sucedida, continue diretamente para a análise do site na mesma rodada.
• Se a instalação falhar, informe claramente ao usuário o que está faltando e pare, em vez de mudar silenciosamente para um extrator diferente.
• Não rebaixe silenciosamente para raspagem HTML estática apenas porque as ferramentas estão ausentes.

Passagens de Extração Obrigatórias

Use a lista de verificação em references/website-reading-checklist.md quando precisar de um lembrete mais detalhado do que inspecionar.

1. Escopo da Página

• Identifique o propósito da página.
• Identifique se a página é de marketing, produto, painel de controle, documentação, e-commerce, editorial ou mista.
• Identifique as seções visíveis importantes de cima para baixo.
• Observe quaisquer áreas bloqueadas ou inacessíveis em vez de inventá-las.

2. Capture a Linha de Base

• Inspecione a página no desktop primeiro.
• Inspecione também no tablet e no celular quando o layout mudar materialmente.
• Role a página inteira lentamente antes de escrever qualquer coisa para não perder animações atrasadas, UI fixa ou revelação progressiva.
• Capture evidências de código do lado do navegador enquanto a página está ativa: HTML renderizado, outerHTML de nós-chave, variáveis CSS raiz, regras de folha de estilo legíveis e estilos computados para componentes representativos.
• Prefira chamadas diretas agent-browser eval ou um script wrapper orientado por agent-browser em vez de mudar para outra pilha de navegador.
• Use scripts/extract-browser-evidence.mjs apenas quando o usuário quiser explicitamente um artefato JSON gerado por shell, mantendo-se ainda no agent-browser.
• Não pause para captura de tela durante a passagem padrão. Use a avaliação de página para extrair a estrutura e os estilos diretamente da página em execução.

2.1 Fluxo de Trabalho de Eval Preferido

Quando agent-browser eval ou um caminho equivalente de avaliação de navegador estiver disponível, siga esta ordem:

1. abra a página
2. aguarde o carregamento e a hidratação
3. role a página para acionar conteúdo preguiçoso e mudanças de estado fixo
4. extraia HTML renderizado para nós representativos
5. extraia estilos computados para cabeçalhos, botões, cartões, navegação e wrappers de seção
6. extraia variáveis CSS raiz e regras de folha de estilo legíveis
7. extraia trechos de texto visíveis e cópia de CTA
8. investigue estados de hover, ativo, fixo ou expandido por meio de mudanças no DOM ou estilos computados

Não substitua as etapas 4 a 8 por capturas de tela.

3. Extraia o Sistema de Design

Capture as regras reutilizáveis, não apenas a superfície específica da página:

• cores e suas funções
• variantes de tema claro e escuro quando o site as suporta
• hierarquia tipográfica
• ritmo de espaçamento e comportamento de grade
• linguagem de raio de canto
• tratamento de borda
• sombras e camadas de superfície
• estilo de imagem
• estilo de ícone
• estilo de movimento e transição
• densidade e filosofia de espaço em branco
• convenções de folha de estilo e variáveis CSS quando observáveis
• padrões DOM que explicam como componentes repetidos são realmente estruturados

4. Extraia Componentes e Estados

Inspecione os principais padrões repetidos:

• navegação
• barras de anúncio
• blocos de herói
• botões e links
• cartões
• selos
• formulários e entradas
• abas ou pílulas
• acordeões
• tabelas
• rodapés

Para cada componente importante, inspecione os estados visíveis que importam:

• padrão
• hover
• ativo ou selecionado
• focado (se visível)
• desabilitado (se visível)
• variantes roladas ou fixas
• estados abertos ou expandidos
• variantes de modo claro e modo escuro quando o site suporta troca de tema

5. Extraia Comportamento de Interação

Não pare nos visuais estáticos.

Documente:

• o que muda na rolagem
• o que muda no hover
• o que muda no clique
• o que muda quando o usuário alterna entre modo claro e escuro
• o que é animado para aparecer
• se carrosséis, abas ou barras laterais fixas são orientados por clique, rolagem ou tempo
• quão rápido o movimento parece e se é sutil, nítido, cinematográfico, divertido ou contido
• quais estados CSS ou DOM mudam durante essas interações quando observáveis no navegador

6. Extraia Conteúdo e Voz da Marca

Capture o tom que molda o design:

• estilo de título
• fraseologia de CTA
• densidade de frases
• enquadramento do produto
• sinais de confiança
• padrões de nomenclatura de recursos
• se o texto é técnico, divertido, premium, direto, acadêmico ou conversacional

Isso é importante porque um bom DESIGN.md deve orientar tanto os visuais quanto o estilo de apresentação.

6.1 Varredura de Modo de Tema

Se o site suportar troca de aparência:

• acione a alternância de modo claro e escuro diretamente no navegador
• extraia evidências de DOM e estilos computados para ambos os modos
• documente quais tokens invertem versus quais acentos permanecem estáveis
• observe se imagens, sombras, bordas, cartões e blocos de código mudam de tratamento entre os modos
• carregue ambos os modos no markdown final e na prévia HTML

Contrato de Saída

Escreva o documento final usando a estrutura em assets/DESIGN.template.md.

Após o markdown ser escrito, gere uma prévia HTML complementar usando scripts/render-design-preview.mjs quando possível.

Quando as ferramentas de navegador estiverem disponíveis, prefira uma passagem de extração de DOM e estilo antes de escrever. A ordem de evidência esperada é:

1. HTML renderizado e estrutura de nó-chave
2. estilos computados e variáveis CSS
3. diffs de estado de interação
4. verificação cruzada de captura de tela opcional apenas se o usuário pedir explicitamente ou se as evidências DOM forem ambíguas

Se a página suportar temas claro e escuro, o contrato de saída também exige:

1. documentação explícita de Modos de Tema no DESIGN.md
2. notas de token separadas para modo claro e modo escuro quando diferirem materialmente
3. um bloco de resumo de tema claro/escuro visível na prévia HTML complementar

O documento deve conter geralmente estas seções:

1. Tema Visual e Atmosfera
2. Paleta de Cores e Funções
3. Regras Tipográficas
4. Estilizações de Componentes
5. Princípios de Layout
6. Profundidade e Elevação
7. O que Fazer e o que Não Fazer
8. Comportamento Responsivo
9. Guia de Prompt do Agente

Adicione apêndices opcionais apenas quando agregarem valor real:

• Padrões de Interação
• Padrões de Conteúdo e Mensagens
• Páginas Observadas
• Notas de Evidência

Dentro dessas seções, prefira subseções mais ricas no estilo Stitch quando o site as suportar:

• Características Principais
• Primário, Interativo, Escala Neutra, Superfície e Sobreposição, Sombras e Profundidade
• Família de Fontes, Hierarquia, Princípios
• Botões, Cartões e Contêineres, Entradas e Formulários, Navegação, Tratamento de Imagem, Componentes Distintivos
• Sistema de Espaçamento, Grade e Contêiner, Filosofia de Espaço em Branco, Escala de Raio de Borda
• Pontos de Quebra, Alvos de Toque, Estratégia de Colapso
• Referência Rápida de Cores, Exemplos de Prompts de Componentes, Guia de Iteração

Não mantenha o documento no nível de um resumo de alto nível se o site expuser evidências suficientes para ser mais preciso.

Contrato de Prévia HTML

Gere um arquivo HTML ao lado do markdown por padrão.

A prévia deve:

• usar o DESIGN.md final como sua fonte de verdade, em vez de um resumo mantido separadamente
• usar um modelo de shell de pré-visualização fixo, não uma estrutura HTML recém-inventada a cada execução
• exibir as regras visuais mais úteis à esquerda, por exemplo, visão geral, paleta, tipografia, espaçamento, raio, botões, cartões, profundidade e notas responsivas
• manter a fonte markdown visível em um painel dedicado para que o usuário possa inspecionar ou copiar o documento original rapidamente
• parecer um painel de design polido, em vez de uma renderização markdown simples
• usar os tokens de design extraídos quando prático, para que a própria prévia reflita o sistema documentado

Use assets/design-preview-shell.template.html como o shell padrão quando disponível. Trate esse modelo como infraestrutura estável e apenas preencha os tokens e conteúdo documentados nele, a menos que o usuário peça explicitamente por uma nova direção de layout.

Quando o usuário fornecer uma referência visual para o layout, siga-a com precisão suficiente para que o HTML seja reconhecivelmente da mesma família, embora ainda seja gerado a partir dos dados do markdown.

Regras de Síntese

Ao escrever o arquivo final:

• Prefira nomes semânticos em vez de rótulos de token brutos.
• Inclua valores hexadecimais exatos quando a precisão da cor for importante.
• Traduza raio, espaçamento, sombras e escalas tipográficas em linguagem simples que outro agente possa usar imediatamente.
• Mantenha o documento opinativo e utilizável; evite grandes despejos de dados.
• Explique funções, não apenas a aparência.
• Agrupe padrões recorrentes em um sistema.
• Preserve nuances. Se o site misturar dois modos visuais, descreva ambos e quando cada um aparece.
• Prefira detalhes numéricos precisos quando observáveis: valores hexadecimais exatos, tamanhos de fonte, alturas de linha, espaçamento entre letras, valores de raio, unidades de espaçamento e fórmulas de sombra de múltiplas camadas.
• Adicione uma breve filosofia ou justificativa quando um padrão for central para a identidade do site, por exemplo, "sombra como borda" ou "compressão como identidade".
• Inclua dicas de implementação específicas do componente quando ajudarem outro agente a construir uma UI correspondente sem ver o site de origem.
• Inclua exemplos prontos para prompt no Guia de Prompt do Agente para pelo menos padrões de herói, cartão, botão ou navegação em sites substanciais.
• Quando alguns valores forem inferidos em vez de observados, mantenha-os claramente rotulados, mas ainda assim úteis.

Bom:

• "Ações primárias usam um azul elétrico frio #3B82F6"
• "O site usa um sistema de espaçamento de 8 pontos"
• "Cartões têm sombra 0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1)"

Ruim:

• "A cor primária é azul"
• "O espaçamento é uniforme"
• "Cartões têm sombras"