drawio-visuais-skill

Skill de Visuais Drawio

Crie, reconstrua e edite arquivos Draw.io nativos e editáveis pelo usuário sem servidor, MCP, template fixo, Scene IR ou renderizador personalizado.

Padrão para objetos, não módulos de texto

Para um novo fluxo explicativo — um processo, pipeline, swimlane, ciclo de vida de solicitação ou fluxo de arquitetura — use objetos editáveis reconhecíveis e alterações visíveis por padrão. Uma solicitação simples como "desenhe o fluxo de trabalho" ativa esta regra; o usuário não precisa pedir por gráficos "pictóricos", "concretos" ou "ilustrados". Escolha o tipo de diagrama separadamente deste tratamento visual.

Antes de posicionar nós, identifique o que se move, o que muda e quem age. Em seguida, escolha uma silhueta, conteúdos significativos ou uma pequena cena de objeto para cada objeto de negócio principal e estágio de processamento: uma fila tem cartões de tarefa separados e entrada/saída; um parser mostra um documento se transformando em partes extraídas; um reembolso distingue fundos pendentes de devolvidos. Desenhe essas partes nativas primeiro, depois adicione nomes/ações curtos. Uma série de retângulos contendo nomes de etapa falha neste padrão, mesmo quando os rótulos são breves e o layout é limpo. Racks de servidor repetidos, emojis ou um ícone não relacionado em um cartão de prosa não substituem o significado visível. Leia visual-storytelling.md antes de criar esses fluxos.

Comece com os gráficos incluídos: consulte o índice de componentes, leia o XML .drawio relevante em assets/components/ e escolha se reutilizará seus descendentes nativos, adaptará/combinará suas partes ou usará sua construção como referência para gerar um novo objeto nativo. Combine objetos de navegador, documento, mensagem, fila, trabalhador, armazenamento, chunks, tabela, vetores, revisão, decisão e notificação conforme a tarefa exigir. Por exemplo, componha navegador + documento → armazenamento, depois uma mensagem separada → fila → trabalhador; não apenas escreva esses nomes dentro de retângulos. Os 12 iniciadores são uma biblioteca de sementes extensível, não um template completo ou limite de capacidade; ao gerar um objeto adicional, pegue emprestadas ideias de construção relevantes, como silhueta, conteúdos significativos, marcas de status, aninhamento e portas de conexão, depois adapte-as ao domínio. Não imponha a paleta de amostra do iniciador nem force uma cópia exata.

Linguagem de componente integrada: ao adicionar, gerar ou manter ativos reutilizáveis em assets/components/, mantenha cada legenda, nome de campo, valor de texto ilustrativo, status, nome de página e dica de ferramenta em inglês. Números, fórmulas e símbolos podem permanecer como estão. Esta é uma regra de criação de biblioteca: diagramas gerados para usuários ainda seguem o idioma solicitado/de origem, com texto inicial adaptado de acordo.

Exceções seguem a tarefa, não a conveniência: preserve reconstrução fiel, o escopo de uma edição local, uma solicitação explícita apenas-texto/caixa-mínima e notação formal necessária. Compartimentos de classe/ER, lifelines de sequência, símbolos de decisão/fork/join e limites de estado carregam semântica real; mantenha-os. Uma solicitação genérica por um "fluxograma", um diagrama "simples", iniciadores ausentes ou a disponibilidade de Mermaid não é uma exceção. Explique estados com alterações visíveis de objeto quando compatível; não substitua relacionamentos formais por imagens. Esses padrões se aplicam a todas as páginas e sobrevivem a mudanças de orientação/tipo.

Regras principais

• Trate o arquivo .drawio atual como a fonte de verdade interna editável. Por padrão, entregue apenas imagens PNG por página e uma visualização HTML; mantenha arquivos nativos em um diretório de trabalho interno, fora do diretório de entrega, e não os vincule na entrega. Entregue arquivos nativos, SVG, PDF ou outros formatos apenas quando solicitado explicitamente.
• Nunca sobrescreva uma entrada. Cada gravação mecânica deve usar um novo caminho de saída, incluindo arquivos de trabalho internos.
• Não imponha um tema, lista de formas, tipo de diagrama, grade de coordenadas ou receita de layout.
• Siga o tipo de diagrama, notação e orientação especificados pelo usuário. Quando não especificados, escolha a apresentação que melhor responde à pergunta real da tarefa, incluindo formas UML e não UML; não padronize toda solicitação para um fluxograma ou swimlane. Use diagram-selection.md ao escolher ou alterar substancialmente a apresentação.
• Aplique o padrão objeto-primeiro acima a novos fluxos explicativos; símbolos de controle padrão e iniciadores de componente reutilizáveis o suportam sem impor um catálogo de ícones fixo.
• Para fluxogramas verticais, execute o caminho principal de cima para baixo, coloque ramos paralelos lado a lado, rotule saídas de losangos de decisão e agrupe verificações de suporte em uma caixa tracejada cinza claro com um propósito em linguagem simples.
• Quando um motor central coordena módulos externos, coloque o núcleo no centro, agrupe entradas e trabalhadores de cada lado e use setas numeradas com rótulos de ação para guiar o leitor através de uma tarefa. Quando relevante, roteie feedback acima do núcleo, coloque decisões humanas e canais de notificação abaixo dele e mostre um fluxo de trabalho de exemplo ao longo da parte inferior. Escolha cores adequadas ao assunto.
• Mantenha formas, estênceis, estilos, geometria, waypoints, camadas, grupos e metadados de wrapper arbitrários do Draw.io nativo.
• Prefira uma tela ou contêiner maior em vez de nós, rótulos ou corredores de roteamento comprimidos. Um arquivo livre de colisões não é necessariamente espaçoso, legível ou bem composto.
• Reserve espaço para rótulos de conector antes de posicionar nós adjacentes. Rótulos longos devem caber entre as formas conectadas com folga visível, ou usar quebras de linha explícitas/outra posição clara de rótulo. Resolva riscos de rótulo-ponto-final e verifique os limites reais de texto renderizado antes de marcar um diagrama como pronto; veja folga de rótulo de conector.
• Para conteúdo recém-criado ou substancialmente redesenhado, defina flowAnimation=1 nativo em arestas de fluxo semântico direcionado por padrão, incluindo fluxos normais, secundários, de dados, de exceção e de repetição. Mantenha referências, anotações, contenção, agrupamento e relacionamentos puramente estruturais estáticos. Deixe a intenção explícita do usuário substituir esta política.
• Preserve estilos de animação não relacionados durante uma edição local, a menos que a normalização de animação seja solicitada. Se o movimento obscurecer a hierarquia, torne fluxos semânticos de prioridade mais baixa estáticos durante a QA renderizada, em vez de alterar sua topologia.
• Trate a animação de conector como um efeito visual, nunca como roteamento ou prevenção de colisão.
• Use a CLI fornecida apenas para inspecionar, consultar, corrigir, validar, verificar layout/topologia, orquestrar exportação Desktop/Web, HTML complementar, CRUD de página, listagem de versão, publicar e restaurar. Ela não cria, faz layout ou implementa um renderizador; render delega ao Draw.io Desktop, web-svg-bridge delega uma página selecionada ao Draw.io Web oficial e a visualização HTML delega ao visualizador remoto oficial.
• Trate <base>-vNNN como uma versão de entrega lógica compartilhada por suas imagens e HTML, não por cada gravação interna. O versionamento nativo permanece interno, a menos que a entrega da fonte seja solicitada. Por padrão, uma alteração aprovada pelo usuário consome no máximo uma nova versão irmã.
• Mantenha todo --page-index público da CLI baseado em zero, correspondendo ao index retornado por inspect. Prefira IDs de página estáveis para trabalho de várias páginas.
• Limite cada documento a 15 páginas. A CLI rejeita documentos existentes maiores e adições além desse limite com PAGE_COUNT_LIMIT; nunca trunque páginas para satisfazê-lo.
• Não habilite este Skill junto com o Skill oficial drawio@drawio; este Skill já carrega o mesmo caminho nativo de criação Mermaid/XML.

Escolha a apresentação

Separe o tipo de diagrama da ferramenta de criação. Escolha pelo que o leitor precisa entender: progressão, responsabilidades, interações, estados, estrutura, implantação, movimentação de dados ou comparação. Um diagrama fornecido, formato explícito ou edição local solicitada restringe essa escolha. Quando o usuário a deixa em aberto, faça a escolha autonomamente, explique brevemente quando útil e prossiga; não faça o usuário selecionar de um catálogo. Leia diagram-selection.md para o guia questão-para-forma e tradeoffs.

Aplique o tratamento visual padrão ou a exceção explícita da tarefa em todas as páginas e revisões. Não adicione uma página complementar de texto simples como substituto para uma explicação baseada em objetos.

Em seguida, escolha objetos e notação apropriados para essa apresentação. Ilustrações concretas podem explicar payloads e transformações, enquanto símbolos formais UML, ER e outros estabelecidos devem manter suas convenções semânticas. Não trate toda caixa rotulada de classe, estado ou esquema como um defeito de fluxo pesado em texto.

Escolha o fluxo de trabalho

Solicitação	Fluxo de trabalho
Explicar um processo, pipeline, swimlane, ciclo de vida ou fluxo de arquitetura	Evidência/propriedade → visual-storytelling → construções de objeto/estado → XML nativo direto → QA do renderizador oficial
Criar um diagrama estrutural formal ou diagrama explicitamente de caixa mínima	Preservar notação/conteúdo → Mermaid se mantiver a representação pretendida e Desktop estiver disponível; caso contrário, XML nativo
Criar com formas/estilos/posições personalizados	XML nativo direto → .drawio
Criar a partir de PDF ou texto	Ler fonte → extrair estrutura suportada → escolher representação usando os mesmos padrões → XML nativo ou Mermaid adequado
Reconstruir a partir de uma imagem	Inspecionar na resolução original → células nativas editáveis → comparação de visualização opcional
Verificar conflitos visuais	check-layout → Desktop render → inspecionar imagem → pequena correção → rerenderizar; recorrer ao HTML do Visualizador
Verificar um fluxo de negócios	check-topology com inícios, terminais e arestas necessárias conhecidas
Visualizar sem Desktop	preview → .html complementar com contagem/nomes de página visíveis usando o visualizador remoto oficial
Exportar SVG sem Desktop	Preferir uma sessão de loopback web_svg_session.py; reter web-svg-bridge → commit-web-svg para recuperação manual
Exportar ou aplicar um layout solicitado	Criar .drawio primeiro → CLI do Draw.io Desktop
Editar, alvo desconhecido	inspect → query → patch
Editar, página e ID de célula conhecidos	query → patch
Editar, resultado CLI confiável recente já tem revisão e alvo	patch
Adicionar, renomear ou excluir uma página	inspect → page add/rename/delete
Listar ou restaurar uma versão de arquivo	versions ou versions → inspect old → restore
Publicar um arquivo de trabalho concluído	inspect working → publish
Visualizar uma ou mais células conhecidas	query
Verificar um arquivo de forma independente	validate

Leia references/authoring.md para criação, visualização, detecção de Desktop, layout e exportação. Leia references/web-svg-export.md apenas quando Desktop não estiver disponível e SVGs solicitados explicitamente precisarem ser exportados através do Draw.io Web oficial. Leia references/layout-authoring.md ao criar um diagrama congestionado, manter consistência visual entre páginas, interpretar check-layout ou realizar QA visual renderizado. Leia references/topology.md quando um processo, ciclo de vida ou caminho de solicitação precisar ser conectado. Leia references/source-to-diagram.md quando a fonte for PDF, texto ou uma imagem. Leia references/drawio-xml.md apenas para criação direta de XML. Leia references/patch-contract.md antes de construir uma correção. Leia references/versioning.md para comandos de página e histórico imutável.

Planeje uma entrega lógica

• Antes de escrever, mapeie cada alteração solicitada para sua página/célula, saídas de decisão necessárias, restrições críticas de início/terminal/aresta, efeitos colaterais ou caminhos de erro, terminologia e todas as páginas afetadas.
• Para novos documentos de várias páginas, defina funções visuais no nível do documento antes de criar e reutilize fundações de página, tipografia, estilos de componente repetidos e estilização de relacionamento entre páginas. Ao adicionar ou editar conteúdo, herde a convenção do documento existente dentro do escopo solicitado. Siga consistência visual do documento para seleção de funções, exceções intencionais e aceitação entre páginas.
• Para uma edição atômica que não precisa de correção posterior de topologia, layout ou visual, escreva diretamente para uma nova versão nativa interna.
• Para edições de várias páginas ou qualquer tarefa que provavelmente precise de correção de QA, crie um diretório temporário de propriedade do Agente e escreva working-01.drawio, working-02.drawio e assim por diante. Complete todas as edições e verificações solicitadas lá; publish é opcional para um snapshot final interno ou entrega nativa explicitamente solicitada.
• Gere o HTML de entrega e os PNGs por página a partir do mesmo snapshot nativo final verificado; um .drawio publicado não é obrigatório. Para HTML voltado ao usuário, incorpore uma renderização verificada de cada página com preview --fallback-png (repita na ordem das páginas). Verifique o HTML entregue com o Visualizador Remoto bloqueado, incluindo em largura estreita. Uma renderização online bem-sucedida sozinha não verifica a visualização do destinatário. Se nenhuma renderização oficial estiver disponível, rotule o HTML como apenas online e divulgue a limitação. Visualizações temporárias são artefatos de QA, não entregas.
• Após verificar imagens e HTML autocontidos, remova apenas arquivos de QA descartáveis criados por esta tarefa; mantenha o snapshot nativo final internamente para edições posteriores. Nunca limpe versões formais existentes sem autorização explícita do usuário.

Criar

1. Leia references/authoring.md e escolha a representação antes de escolher uma sintaxe. Para um novo fluxo explicativo, use o padrão objeto-primeiro e XML nativo direto; a disponibilidade do Desktop altera a exportação, não o requisito visual. Use Mermaid apenas quando ela mantiver a semântica/representação escolhida, como um diagrama estrutural formal ou diagrama explicitamente de caixa mínima. Detecte Desktop para conversão/exportação.
2. Escolha uma base descritiva em minúsculas com hífen, reserve <base>-v001 para a entrega inicial de imagem/HTML e mantenha seu snapshot .drawio interno

…

[truncado para tradução]