Criador de Diagramas HTML

Gere arquivos .html autônomos com um <svg> inline que argumentam visualmente, não apenas exibem informações. Em seguida, tire capturas de tela com Playwright, inspecione o PNG e corrija até ficar limpo.

Arquivos neste Skill

Arquivo	Propósito	Quando ler
`references/color-palette.md`	Todas as cores e estilos de marca: a fonte única da verdade	Antes de cada diagrama
`references/visual-patterns.md`	Esboços de cada padrão de layout (fan-out, timeline, árvore...)	Etapa 2 do Design
`references/starter.html`	Estrutura da página: tokens CSS, classes de texto/formas, marcadores de seta, um exemplo de cada convenção	Copie como início de cada diagrama
`scripts/render.py`	Tira captura de tela do HTML para PNG e verifica a geometria	Execute após cada edição (veja Renderizar e Validar)
`examples/`	Dois diagramas finalizados com seus PNGs	Quando quiser uma referência de densidade e estilo

Para reestilizar cada diagrama para uma marca, edite color-palette.md (e os tokens correspondentes em starter.html). Todo o resto é método universal.

Duas Decisões Já Tomadas (Não Reavaliar Por Diagrama)

1. Tudo é SVG. HTML é apenas a página ao redor.

Caixas, texto, setas e blocos de código residem todos em um único <svg id="diagram">. Não construa caixas a partir de HTML/CSS (divs flexbox/grid) com uma sobreposição SVG para conectores.

Por quê: um diagrama é um problema de geometria, e as setas precisam de coordenadas exatas para ambas as extremidades. Com tudo em SVG, cada nó e cada seta compartilham um sistema de coordenadas que está escrito no arquivo, então você pode calcular um ponto final de seta por aritmética e corrigi-lo editando um número. Com caixas HTML, as posições vêm do mecanismo de layout do navegador: elas não estão na fonte, mudam com fontes e largura da viewport, e os conectores precisam de JavaScript que mede as caixas em tempo de execução. Isso é um segundo programa para depurar, e a viewport do leitor pode diferir daquela que você validou. Os custos de tudo em SVG são reais, mas menores: o texto SVG não quebra (quebre as linhas você mesmo com <tspan>) e sua largura não é conhecida até ser renderizado (o linter mede e relata estouro).

<foreignObject> (HTML dentro de SVG) está desligado por padrão: é o único lugar onde você obteria quebra de texto, mas renderiza inconsistentemente fora de navegadores e o linter não pode verificá-lo. Use-o apenas se o usuário precisar de parágrafos dentro de uma forma.

2. Sem Graphviz ou D2 para layout. Coloque as coordenadas manualmente.

Por quê: a metodologia exige que o layout espelhe o conceito: fan-outs, timelines, ciclos, comparações lado a lado, anotações flutuantes, blocos de código colocados ao lado da etapa que ilustram. Mecanismos de layout automático otimizam para um objetivo diferente (grafos em camadas com poucos cruzamentos de arestas), então eles achatam cada diagrama na mesma hierarquia de cima para baixo, que é exatamente a saída de "caixas uniformes" que este skill existe para evitar. Eles também adicionam uma dependência binária e produzem SVG que é complicado de reestilizar e anotar.

A exceção: um assunto genuinamente em forma de grafo (aproximadamente 15+ nós com muitas ligações cruzadas, como um grafo de dependência) onde os cruzamentos são o principal problema. Lá, execute dot -Tplain (Graphviz) apenas para obter as coordenadas dos nós, então desenhe os nós você mesmo com os estilos e convenções deste skill. Diga que está fazendo isso e por quê.

Filosofia Central

Diagramas devem ARGUMENTAR, não EXIBIR.

Um diagrama não é texto formatado. É um argumento visual que mostra relacionamentos, causalidade e fluxo que as palavras sozinhas não podem expressar. A forma DEVE ser o significado.

O Teste de Isomorfismo: Se você removesse todo o texto, a estrutura sozinha comunicaria o conceito? Se não, redesenhe.

O Teste Educacional: Alguém poderia aprender algo concreto com este diagrama, ou ele apenas rotula caixas? Um bom diagrama ensina — mostra formatos reais, nomes de eventos reais, exemplos concretos.

Avaliação de Profundidade (Faça Isso Primeiro)

Antes de projetar, determine que nível de detalhe este diagrama precisa:

Diagramas Simples/Conceituais

Use formas abstratas quando:

Explicando um modelo mental ou filosofia
O público não precisa de especificações técnicas
O conceito É a abstração (por exemplo, "separação de interesses")

Diagramas Abrangentes/Técnicos

Use exemplos concretos quando:

Diagramando um sistema, protocolo ou arquitetura real
O diagrama será usado para ensinar ou explicar (por exemplo, vídeo do YouTube)
O público precisa entender como as coisas realmente se parecem
Você está mostrando como múltiplas tecnologias se integram

Para diagramas técnicos, você DEVE incluir artefatos de evidência (veja abaixo).

Mandato de Pesquisa (Para Diagramas Técnicos)

Antes de desenhar qualquer coisa técnica, pesquise as especificações reais.

Se você está diagramando um protocolo, API ou framework:

Consulte os formatos JSON/dados reais
Encontre os nomes de eventos reais, nomes de métodos ou endpoints de API
Entenda como as peças realmente se conectam
Use terminologia real, não placeholders genéricos

Ruim: "Protocolo" → "Frontend" Bom: "AG-UI transmite eventos (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)" → "CopilotKit renderiza via createA2UIMessageRenderer()"

Pesquisa torna os diagramas precisos E educacionais.

Artefatos de Evidência

Artefatos de evidência são exemplos concretos que provam que seu diagrama é preciso e ajudam os espectadores a aprender. Inclua-os em diagramas técnicos.

Tipos de artefatos de evidência (escolha o que é relevante para seu diagrama):

Tipo de Artefato	Quando Usar	Como Renderizar
Trechos de código	APIs, integrações, detalhes de implementação	Retângulo escuro + texto com cores de sintaxe (veja paleta de cores para cores de artefatos de evidência)
Exemplos de dados/JSON	Formatos de dados, esquemas, payloads	Retângulo escuro + texto colorido (veja paleta de cores)
Sequências de eventos/etapas	Protocolos, fluxos de trabalho, ciclos de vida	Padrão de timeline (linha + pontos + rótulos)
Mockups de UI	Mostrando saída/resultados reais	Retângulos aninhados imitando UI real
Conteúdo de entrada real	Mostrando o que ENTRA em um sistema	Retângulo com conteúdo de amostra visível
Nomes de API/métodos	Chamadas de função reais, endpoints	Use nomes reais da documentação, não placeholders

Exemplo: Para um diagrama sobre um protocolo de streaming, você pode mostrar:

Os nomes de eventos reais da especificação (não apenas "Evento 1", "Evento 2")
Um trecho de código mostrando como conectar
Como os dados transmitidos realmente se parecem

Exemplo: Para um diagrama sobre um pipeline de transformação de dados:

Mostre dados de entrada de amostra (formato real, não "Entrada")
Mostre dados de saída de amostra (formato real, não "Saída")
Mostre estados intermediários se relevante

O princípio chave: mostre como as coisas realmente se parecem, não apenas como são chamadas.

Arquitetura de Múltiplos Zoom

Diagramas abrangentes operam em múltiplos níveis de zoom simultaneamente. Pense nisso como um mapa que mostra tanto as fronteiras do país quanto os nomes das ruas.

Nível 1: Fluxo Resumido

Uma visão geral simplificada mostrando todo o pipeline ou processo de relance. Frequentemente colocado no topo ou na parte inferior do diagrama.

Exemplo: Entrada → Processamento → Saída ou Cliente → Servidor → Banco de Dados

Nível 2: Limites de Seção

Regiões rotuladas que agrupam componentes relacionados. Elas criam "salas" visuais que ajudam os espectadores a entender o que pertence junto.

Exemplo: Agrupamento por responsabilidade (Backend / Frontend), por fase (Configuração / Execução / Limpeza) ou por equipe (Usuário / Sistema / Externo)

Nível 3: Detalhe Dentro das Seções

Artefatos de evidência, trechos de código e exemplos concretos dentro de cada seção. É aqui que reside o valor educacional.

Exemplo: Dentro de uma seção "Backend", você pode mostrar o formato de resposta da API real, não apenas uma caixa rotulada "Resposta da API"

Para diagramas abrangentes, busque incluir todos os três níveis. O resumo fornece contexto, as seções organizam e os detalhes ensinam.

Ruim vs Bom

Ruim (Exibindo)	Bom (Argumentando)
5 caixas iguais com rótulos	Cada conceito tem uma forma que espelha seu comportamento
Layout de grade de cartões	Estrutura visual corresponde à estrutura conceitual
Ícones decorando texto	Formas que SÃO o significado
Mesmo contêiner para tudo	Vocabulário visual distinto por conceito
Tudo em uma caixa	Texto flutuante com contêineres seletivos

Simples vs Abrangente (Saiba Qual Você Precisa)

Diagrama Simples	Diagrama Abrangente
Rótulos genéricos: "Entrada" → "Processo" → "Saída"	Específico: mostra como a entrada/saída realmente se parecem
Caixas nomeadas: "API", "Banco de Dados", "Cliente"	Caixas nomeadas + exemplos de requisições/respostas reais
Rótulo "Eventos" ou "Mensagens"	Timeline com nomes de eventos/mensagens reais da especificação
Retângulo "UI" ou "Painel"	Mockup mostrando elementos de UI e conteúdo reais
~30 segundos para explicar	~2-3 minutos de conteúdo de ensino
Espectador aprende a estrutura	Espectador aprende a estrutura E os detalhes

Diagramas simples são bons para conceitos abstratos, visões gerais rápidas ou quando o público já conhece os detalhes. Diagramas abrangentes são necessários para arquiteturas técnicas, tutoriais, conteúdo educacional ou quando você quer que o diagrama em si ensine.

Texto em Contêiner vs. Texto Flutuante

Nem todo texto precisa de uma forma ao seu redor. Padrão é texto flutuante. Adicione contêineres apenas quando servirem a um propósito.

Use um Contêiner Quando...	Use Texto Flutuante Quando...
É o ponto focal de uma seção	É um rótulo ou descrição
Precisa de agrupamento visual com outros elementos	É detalhe de suporte ou metadado
Setas precisam se conectar a ele	Descreve algo próximo
A forma em si carrega significado (diamante de decisão, etc.)	A tipografia sozinha cria hierarquia suficiente
Representa uma "coisa" distinta no sistema	É um título de seção, subtítulo ou anotação

Tipografia como hierarquia: Use tamanho de fonte, peso e cor para criar hierarquia visual sem caixas. Um título de 28px não precisa de um retângulo ao redor.

O teste do contêiner: Para cada elemento em caixa, pergunte "Isso funcionaria como texto flutuante?" Se sim, remova o contêiner.

Processo de Design (Faça Isso ANTES de Escrever SVG)

Etapa 0: Avalie a Profundidade Necessária

Antes de qualquer outra coisa, determine se isso precisa ser:

Simples/Conceitual: Formas abstratas, rótulos, relacionamentos (modelos mentais, filosofias)
Abrangente/Técnico: Exemplos concretos, trechos de código, dados reais (sistemas, arquiteturas, tutoriais)

Se abrangente: Faça pesquisa primeiro. Consulte especificações, formatos, nomes de eventos, APIs reais.

Etapa 1: Entenda Profundamente

Leia o conteúdo. Para cada conceito, pergunte:

O que este conceito FAZ? (não o que ELE É)
Que relacionamentos existem entre os conceitos?
Qual é a transformação ou fluxo central?
O que alguém precisaria VER para entender isso? (não apenas ler sobre)

Etapa 2: Mapeie Conceitos para Padrões

Para cada conceito, encontre o padrão visual que espelha seu comportamento. Esboços e notas de uso para cada padrão estão em references/visual-patterns.md.

Se o conceito...	Use este padrão
Gera múltiplas saídas	Fan-out (setas radiais do centro)
Combina entradas em uma	Convergência (funil, setas se fundindo)
Tem hierarquia/aninhamento	Árvore (linhas + texto flutuante)
É uma sequência de etapas	Timeline (linha + pontos + rótulos flutuantes)
Loop ou melhoria contínua	Espiral/Ciclo (seta retornando ao início)
É um estado ou contexto abstrato	Nuvem (elipses sobrepostas)
Transforma entrada em saída	Linha de montagem (antes → processo → depois)
Compara duas coisas	Lado a lado (paralelo com contraste)
Separa em fases	Lacuna/Pausa (separação visual entre seções)

Etapa 3: Garanta Variedade

Para diagramas com múltiplos conceitos: cada conceito principal deve usar um padrão visual diferente. Sem cartões ou grades uniformes.

Etapa 4: Esboce o Fluxo

Antes de escrever marcação, rastreie mentalmente como o olho se move através do diagrama. Deve haver uma história visual clara.

Etapa 5: Construa o HTML/SVG

Só agora escreva o arquivo, começando de references/starter.html. Organize em uma grade de 20px e anote as coordenadas chave (colunas, linhas, centros dos nós) antes de colocar qualquer coisa. Veja abaixo como lidar com diagramas grandes.

Etapa 6: Renderize e Valide (OBRIGATÓRIO)

Após escrever o arquivo, você DEVE executar o loop de renderização, visualização e correção até que o diagrama pareça correto. Isso não é opcional — veja a seção Renderizar e Validar abaixo para o processo completo.

Estratégia para Diagramas Grandes / Abrangentes

Para diagramas abrangentes ou técnicos, construa o SVG uma seção de cada vez. Não escreva o arquivo inteiro de uma vez. Um diagrama abrangente pode exceder o limite de saída por resposta, e mesmo quando cabe, uma seção por passagem dá a cada seção atenção real.

O Fluxo de Trabalho Seção por Seção

Fase 1: Construa cada seção

Crie o arquivo a partir de references/starter.html: defina o <title>, o viewBox, e adicione a primeira seção.
Adicione uma seção por edição, cada uma em seu próprio <g id="sec-...">. Pense no layout desta seção, seu espaçamento e como ela se conecta ao que já está lá.
Use ids descritivos (data-node="trigger", id="sec-backend") para que as arestas entre seções sejam legíveis: data-from="trigger" data-to="router".
Mantenha um plano de coordenadas em um comentário HTML no topo do svg (x das colunas, y das linhas, limites das seções). Cada seção posterior e cada aresta leem dele, e é assim que você corrige o espaçamento sem adivinhar.

Fase 2: Revise o todo

Leia o arquivo completo e verifique:

Cada data-from/data-to nomeia um data-node que existe?
O espaçamento é equilibrado, ou algumas seções estão apertadas enquanto outras estão esparsas?
O viewBox contém tudo, com ~40px de margem?

Fase 3: Renderize e valide (abaixo).

Limites de Seção

Use barras horizontais ou verticais com um subtítulo para marcar as fronteiras das seções. Isso cria "salas" que ajudam os espectadores a navegar em diagramas complexos. As barras das seções devem ser sutis (stroke claro, sem preenchimento) e o subtítulo deve ser texto flutuante posicionado dentro ou próximo à barra.

Exemplo:

<line x1="100" y1="y" x2="800" y2="y" stroke="#ccc" stroke-width="1" />
<text x="110" y="y-10" font-family="..." font-size="14" fill="#666">Fase 2: Processamento</text>

Renderizar e Validar (Obrigatório)

Após escrever o HTML, você DEVE executar o seguinte ciclo até que o diagrama esteja correto:

Execute python scripts/render.py diagram-name.html (isso tira uma captura de tela como diagram-name.png e executa verificações geométricas)
Abra diagram-name.png (ou examine a saída do console para relatórios de validação)
Se problemas forem detectados (estouro de texto, colisões de geometria, aparência incorreta):
- Edite o HTML para corrigir
- Repita a partir da Etapa 1

O script verifica:

Estouro de texto SVG (texto que excede os limites esperados)
Colisões de caixa delimitadora (elementos sobrepostos)
Referências de arestas órfãs (data-from/data-to que não correspondem a nenhum data-node)
Integridade geral do layout

Nota: A renderização requer Playwright (pip install playwright && playwright install chromium). Se o Playwright não estiver disponível, o script informará e você precisará instalar.

A validação não é opcional. Pular a validação resulta em diagramas com problemas de layout invisíveis que falham na transmissão do argumento visual.

Padrões de Layout (Em Detalhe)

Consulte references/visual-patterns.md para esboços detalhados e exemplos de cada padrão listado na Etapa 2. Cada padrão inclui:

Um esboço conceitual
Quando usá-lo (e quando evitá-lo)
Dicas de implementação SVG
Exemplos de diagramas reais que usam o padrão

Nota Rápida: Não force um padrão em um conceito onde ele não se encaixa. O padrão deve surgir naturalmente do comportamento do conceito.

Paleta de Cores

Consulte references/color-palette.md para a fonte única da verdade sobre cores e estilos. Ela define:

Cores primárias e de destaque
Cores de fundo para diferentes tipos de contêiner (seções, artefatos de evidência, etc.)
Cores de texto para legibilidade
Cores de seta e conector
Estilos de sombra e borda

Para reestilizar para uma marca diferente, edite apenas este arquivo e atualize os tokens CSS correspondentes em starter.html. A estrutura geral do diagrama não precisa ser alterada.

Referência do `starter.html`

O arquivo references/starter.html contém:

Tokens CSS completos (importados de color-palette.md)
Classes para texto (título, subtítulo, corpo, código)
Classes para formas (retângulo, círculo, diamante, etc.)
Marcadores de seta (triângulo, círculo, etc.)
Um exemplo de cada convenção (um nó, uma seta, um trecho de código, etc.)

Sempre comece copiando este arquivo. Ele garante que todo diagrama use tokens de estilo consistentes e siga as convenções que a ferramenta de validação espera.

Fluxo de Trabalho: Resumo

Avalie a Profundidade: Simples ou Abrangente? Se abrangente, pesquise primeiro.
Entenda e Mapeie: Entenda os conceitos, mapeie para padrões visuais.
Esboce e Planeje: Rastreie visualmente o fluxo, anote as coordenadas.
Construa (Seção por Seção): Construa seções do SVG uma de cada vez a partir de starter.html.
Conecte e Revise: Certifique-se de que as arestas correspondem e o layout está equilibrado.
Renderize e Valide: Execute o ciclo de captura de tela/validação até que esteja limpo.
Entregue: O .html autônomo é o artefato final — pode ser aberto em qualquer navegador.

Boas Práticas

Nomes de ids: Use nomes descritivos para id e data-node/data-from/data-to. Evite node1, node2.
Comentários: Adicione um comentário HTML no topo do SVG com a grade de coordenadas (x das colunas, y das linhas).
Espaçamento: Use 20px como unidade base (grade). Margem mínima de 40px dentro do viewBox.
Textos: Quebre textos longos manualmente com <tspan>. Para mais de ~3 linhas, considere usar <foreignObject> (com aviso).
Arestas: Sempre use data-from e data-to que correspondam a data-node existentes. Isso permite verificação automática.
Aparência: Antes de entregar, verifique se o diagrama é compreensível sem texto (Teste de Isomorfismo).

Solução de Problemas

Problema	Causa Provável	Solução
Texto cortado/estouro	Texto muito longo para o espaço	Quebre em `<tspan>` ou aumente o espaço
Setas atingindo o lugar errado	Coordenadas `x2`/`y2` incorretas	Verifique coordenadas no plano
Arestas órfãs	`data-from` ou `data-to` não corresponde a nenhum `data-node`	Verifique a ortografia/ids
ViewBox muito pequeno	Layout muito maior que o esperado	Aumente viewBox, adicione margem
Captura de tela mostra layout quebrado	CSS ou SVG inválido	Valide o HTML, verifique as tags de fechamento

Exemplo de Uso:

# Crie um diagrama de arquitetura
cp references/starter.html meu-diagrama.html
# Edite meu-diagrama.html: adicione seções, nós, arestas
# Renderize e valide
python scripts/render.py meu-diagrama.html
# Veja meu-diagrama.png; repita se necessário

Perguntar na sua IA favorita

Documentação