Flowy, Habilidade de Diagramas Nativa de IA
Flowy gera arquivos HTML autônomos que renderizam diagramas SVG interativos. Cada arquivo inclui CSS, JavaScript e dados do diagrama incorporados, sem dependências. Basta dar um duplo clique para abrir em qualquer navegador.
Locais dos Arquivos
- Diagramas:
docs/diagrams/*.html(ex.:docs/diagrams/upload-flow.html). Crie a pasta no primeiro uso; ela pode ainda não existir. Se um projeto já mantiver diagramas em outro local, siga a convenção desse projeto. - Modelo HTML:
${CLAUDE_SKILL_DIR}/references/html-template.html, o renderizador canônico e o único arquivo de referência que esta habilidade fornece. O caminho resolve para a própria pasta desta habilidade, onde quer que ela esteja instalada (plugin, pessoal ou projeto), então não depende do projeto atual.
Deliberadamente não há arquivo de esquema, pasta de exemplos ou editor visual. Versões
anteriores desta habilidade apontavam para flowy/schema.ts, flowy/examples/,
flowy/editor.html e um repositório Flowy no disco. Nada disso existe, os caminhos
estavam desatualizados e segui-los era perda de tempo. O modelo HTML acima é a
fonte da verdade para a estrutura; leia-o antes de escrever um diagrama.
Pré-voo
Antes de criar ou editar um diagrama Flowy:
- Leia
${CLAUDE_SKILL_DIR}/references/html-template.htmlpara ter o código do renderizador atual - Liste diagramas existentes em
docs/diagrams/para evitar conflitos de nomenclatura - Se estiver atualizando um diagrama existente, leia-o primeiro e extraia o objeto
DIAGRAM
Esquema
Cada diagrama é um objeto JavaScript com três campos:
{
meta: { title, description, type, tags[], created, updated },
nodes: [...],
edges: [...]
}
meta
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
| title | string | sim | Título legível por humanos |
| description | string | não | O que o diagrama mostra |
| type | string | sim | "flowchart" ou "ui-mockup" |
| tags | string[] | não | Para organização |
| created | string | não | Data ISO (YYYY-MM-DD) |
| updated | string | não | Data ISO, defina como hoje ao criar/atualizar |
nodes
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
| id | string | sim | único, snake_case (ex.: "step1_upload") |
| type | string | sim | "box", "circle", "diamond", "note", "group" |
| label | string | sim | Texto principal exibido na forma |
| sublabel | string | não | Texto secundário mostrado no tooltip ao passar o mouse |
| position | { x, y } | sim | Canto superior esquerdo em pixels |
| size | { width, height } | sim | Dimensões em pixels |
| style | object | não | Veja os campos de estilo do nó abaixo |
| group | string | não | id do nó de grupo pai (apenas agrupamento visual) |
Campos de estilo do nó: fill, stroke, strokeWidth, color (texto), fontSize, borderRadius, opacity
edges
| Campo | Tipo | Obrigatório | Notas |
|---|---|---|---|
| id | string | sim | único (ex.: "e_upload_to_extract") |
| source | string | sim | id do nó de origem |
| target | string | sim | id do nó de destino |
| label | string | não | texto na seta (ex.: "sim", "erro") |
| sourceHandle | string | não | "top", "right", "bottom" (padrão), "left" |
| targetHandle | string | não | "top" (padrão), "right", "bottom", "left" |
| style | object | não | Veja os campos de estilo da aresta abaixo |
Campos de estilo da aresta: stroke, strokeWidth, strokeDasharray, markerEnd
Regras de Renderização de Nós
| Tipo | Elemento SVG | Detalhes |
|---|---|---|
| box | <rect> | Cantos arredondados via rx/ry de borderRadius. Padrão: 8px |
| circle | <ellipse> | cx = x + width/2, cy = y + height/2, rx = width/2, ry = height/2 |
| diamond | <polygon> | 4 pontos: centro-superior, centro-direito, centro-inferior, centro-esquerdo |
| note | <path> | Retângulo com canto dobrado (superior-direito). Tamanho da dobra: 12px |
| group | <rect> | Borda tracejada (stroke-dasharray: 6,3). Renderizado ATRÁS de todos os outros nós. Rótulo no canto superior esquerdo. Baixa opacidade |
Regras de Renderização de Arestas
- Calcule o ponto de origem: centro do lado do identificador especificado do nó de origem (padrão: inferior)
- Calcule o ponto de destino: centro do lado do identificador especificado do nó de destino (padrão: superior)
- Desenhe uma curva bezier cúbica (comando
C) com pontos de controle deslocados em 50px na direção do identificador - Adicione uma ponta de seta usando uma definição SVG
<marker> - Se
strokeDasharrayestiver definido, renderize como linha tracejada - Se
labelexistir, renderize no ponto médio da curva bezier com um pequeno retângulo de fundo branco atrás dele
Regras de Layout
Direção do Fluxo
- Fluxogramas: De cima para baixo (padrão)
- Mockups de UI: De cima para baixo dentro de um contêiner de grupo, anotações à direita
Espaçamento
- Mínimo de 70px vertical entre centros dos nós
- Mínimo de 60px horizontal entre nós paralelos
- Preenchimento do grupo: 40px dentro dos limites do grupo
Losangos de Decisão
- Ramo esquerdo = caminho principal / sim
- Ramo direito = caminho secundário / não / erro
Notas de Erro/Aviso
- Coloque à DIREITA do fluxo principal
- Conecte com arestas vermelhas tracejadas (
strokeDasharray: "6,3", stroke:#991b1b)
Tamanhos Padrão
| Tipo | Largura | Altura |
|---|---|---|
| box | 200 | 50 |
| circle | 90 | 40 |
| diamond | 120 | 60 |
| note | 180 | 44 |
Paleta de Cores
| Propósito | Preenchimento | Traçado | Texto |
|---|---|---|---|
| Ações | #ffffff | #2d6a4f | #1f2937 |
| Ações primárias | #d1fae5 | #065f46 | #065f46 |
| Decisões | #fef3c7 | #92400e | #1f2937 |
| Erros | #fee2e2 | #991b1b | #991b1b |
| Terminais | #40916c | #2d6a4f | #ffffff |
| Grupos | #f5f5f2 | #e6e4df | #374151 |
| Informação/secundário | #dbeafe | #1e40af | #1e40af |
| Arestas padrão | , | #6b7280 | , |
Estrutura do Arquivo HTML
Cada arquivo HTML Flowy segue esta estrutura. Leia a referência do modelo HTML para o código completo e funcional.
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{título do diagrama}</title>
<style>
/* Todo CSS inline, barra de ferramentas, tela, tooltips, destaques de seleção */
</style>
</head>
<body>
<div id="toolbar">
<!-- [Ajustar] [-] 100% [+] Título selo [Baixar JSON] -->
</div>
<div id="canvas-wrap">
<svg id="canvas">
<defs><!-- marcadores de ponta de seta --></defs>
<g id="diagram-root"></g>
</svg>
</div>
<div id="tooltip"></div>
<script>
const DIAGRAM = { meta: {...}, nodes: [...], edges: [...] };
// Código de renderização + interatividade
</script>
</body>
</html>
Barra de Ferramentas
- Fixa no topo, 48px de altura, fundo branco, borda inferior
- Esquerda: Botão Ajustar à Tela, diminuir zoom, % de zoom, aumentar zoom
- Centro: Título do diagrama (negrito) + selo de tipo (pílula cinza)
- Direita: Botão Baixar JSON (azul)
Interatividade (tudo JS puro)
- Zoom: A roda do mouse escala o viewBox do SVG. Faixa: 0,2x a 5x. Zoom em direção à posição do cursor.
- Pan: Arraste com o clique no canvas vazio para transladar o viewBox.
- Passar o mouse: Ao passar o mouse sobre um nó, seu
sublabelé exibido em um tooltip perto do cursor. - Clique: Clicar em um nó o destaca (borda azul) e todas as arestas conectadas. Clique no espaço vazio para desmarcar.
- Ajustar à Tela: O botão calcula a caixa delimitadora de todos os nós e define o viewBox com 60px de preenchimento.
- Baixar JSON: Serializa o objeto
DIAGRAMcomo JSON formatado e dispara o download do arquivo.
Criando um Novo Diagrama
Quando o usuário pedir um novo fluxograma ou mockup de UI:
- Leia o template: Leia o arquivo de referência do modelo HTML para obter o código do renderizador atual
- Analise a solicitação: Identifique nós (etapas, decisões, erros) e arestas (conexões)
- Atribua posições usando as regras de layout (grade de cima para baixo, espaçamento padrão)
- Aplique cores usando a paleta de cores (terminais = verde, decisões = âmbar, erros = vermelho, etc.)
- Gere o arquivo HTML completo: Copie a estrutura do modelo, substitua o objeto
DIAGRAMpelos novos dados - Salve em
docs/diagrams/{nome-em-kebab-case}.html - Informe ao usuário: "Abra
docs/diagrams/{nome}.htmlno seu navegador para visualizar o diagrama."
Nomenclatura de Arquivos
- Local:
docs/diagrams/{nome}.html - Formato:
kebab-case.html(ex.:docs/diagrams/upload-flow.html,docs/diagrams/checkout-screen.html) - Defina
meta.updatedpara a data ISO de hoje
Atualizando um Diagrama Existente
Quando o usuário pedir para modificar um diagrama:
- Leia o arquivo HTML existente
- Extraia o objeto
DIAGRAMdo bloco<script> - Modifique os nós/arestas conforme solicitado
- Atualize
meta.updatedpara a data de hoje - Regenere o arquivo HTML completo com os dados atualizados (releia o template para o renderizador mais recente)
- Salve de volta no mesmo caminho
Lendo um Diagrama
Quando solicitado a analisar ou descrever um diagrama:
- Leia o arquivo HTML
- Encontre o bloco
const DIAGRAM = { ... }; - Liste os nós por tipo e rótulo
- Trace as arestas para descrever o fluxo em linguagem natural
- Destaque os pontos de decisão e seus ramos
Exemplos
"Crie um fluxograma para o fluxo de login"
Ação: Criar docs/diagrams/login-flow.html com:
start(círculo, verde) →enter_credentials(caixa) →validate(losango, âmbar)validate→ sim/esquerda →dashboard(círculo, verde)validate→ não/direita →show_error(nota, vermelha) → seta tracejada de volta paraenter_credentials
"Atualize o mockup de configurações para adicionar uma opção de modo escuro"
Ação: Leia docs/diagrams/settings-screen.html, extraia DIAGRAM, adicione um novo nó de caixa "section_dark_mode" com rótulo "Modo Escuro" posicionado após a seção Tema, atualize meta.updated, regenerar o HTML.
"Adicione tratamento de erros à etapa 3 do fluxo de upload"
Ação: Leia o HTML, encontre a etapa 3 no array de nós, adicione um nó de nota de erro à direita, adicione uma aresta vermelha tracejada da etapa 3 para a nota de erro, regenerar.
Restrições Importantes
- Zero dependências: Sem npm, sem links CDN, sem scripts/estilos externos
- Funciona offline: Deve renderizar sem acesso à internet
- Arquivo único: Cada diagrama é UM arquivo
.html - Nativo do navegador: Apenas HTML5 padrão, CSS3, SVG e JavaScript ES6+ puro
- Amigável para LLM: O JSON do DIAGRAMA deve ser formatado de forma limpa, não minificado
Automatutenção
Se você descobrir um padrão útil ao criar diagramas, um novo truque de layout, uma cor que funciona bem para um propósito específico, uma melhoria de renderização, atualize este arquivo de habilidade para incluí-lo. Mantenha a habilidade precisa e acionável.