whiteboard

O que whiteboard faz?

Transforme uma explicação em um diagrama que o usuário possa ver, guardar e colar em qualquer lugar. Você escreve o código fonte do diagrama; scripts/render.mjs renderiza usando o CLI instalado localmente e informa exatamente o que está errado quando não consegue interpretar.

Fluxo de Trabalho

1. Escolha o tipo e a linguagem do diagrama. Use Mermaid por padrão. Use D2 para diagramas de arquitetura grandes com contêineres aninhados; use PlantUML apenas quando o usuário pedir ou o projeto já o utilizar. Veja references/syntax.md para a sintaxe de cada tipo.

2. Leia antes de desenhar. Quando o diagrama descrever código, leia o código primeiro. Desenhe o que existe, com nomes reais, não uma imagem genérica. Para solicitações de projeto inteiro (arquitetura, fluxo de controle, modelo de dados), siga references/modes.md.

3. Escreva o código fonte e renderize. Envie-o via stdin com um título curto (no máximo 80 caracteres). O título nomeia os arquivos, então reutilize-o ao redesenhar o mesmo diagrama:

   node <skill-dir>/scripts/render.mjs --title "Sequência de checkout" <<'EOF'
   sequenceDiagram
     Browser->>API: POST /checkout
     API->>Payments: charge(card)
     Payments-->>API: ok
     API-->>Browser: 201 Created
   EOF
   

   <skill-dir> é a pasta onde este arquivo está. Adicione --language d2 ou --language plantuml para essas linguagens. No Windows, ou quando heredocs forem complicados, escreva o código fonte em um arquivo temporário e use --file <caminho>.

4. Corrija e execute novamente em caso de falha. Código de saída 1 significa que o renderizador rejeitou o código fonte; a mensagem indica a linha. Corrija essa linha e execute o mesmo comando novamente. Não entregue ao usuário um diagrama que não foi renderizado. Correções comuns estão listadas no final de references/syntax.md.

5. Relate brevemente. Diga o que o diagrama mostra e forneça os caminhos dos arquivos que o script exibiu (por exemplo, diagrams/checkout-sequence.svg). Se o usuário quiser colar em um README, issue ou wiki, forneça o código fonte em um bloco fenced ```mermaid: GitHub, GitLab e Notion renderizam.

Referência do Script

Opção	Uso
--title <texto>	Obrigatório. Nomeia os arquivos: diagrams/<slug>.svg e o código fonte ao lado.
--language <nome>	mermaid (padrão), d2 ou plantuml.
--file <caminho>	Lê o código fonte de um arquivo em vez de stdin.
--out <dir>	Pasta de saída; padrão diagrams na pasta atual.
--png	Gera também um PNG (slides, aplicativos de chat, terminais que mostram imagens).
--theme <nome>	default, neutral, dark ou forest.
--config <arquivo>	Um arquivo de configuração JSON do Mermaid, para cores e fontes da equipe.
--check	Apenas valida; não escreve nada.
--open	Abre o SVG no visualizador padrão do usuário. Use quando o usuário quiser ver o diagrama agora.
--share	Envia o código fonte para um gist secreto do GitHub e imprime o link. Execute apenas após o usuário pedir para compartilhar e concordar com o envio.
--json	Resultado legível por máquina.
--doctor	Verifica Node.js, cada renderizador e o CLI do GitHub, e informa o que instalar.

Códigos de saída: 0 renderizado, 1 código fonte rejeitado (corrija e execute novamente), 2 argumentos inválidos, 3 renderizador não instalado.

Diagramas nunca leem arquivos locais, variáveis de ambiente ou URLs para dentro da imagem:

• Mermaid renderiza em uma página de navegador isolada que não pode carregar nada da rede ou disco. Qualquer sintaxe Mermaid funciona, mas imagens remotas ou locais e recursos CSS ficam em branco; incorpore uma imagem como URL data: se ela precisar aparecer.
• PlantUML: diretivas diferentes das simples (!define, !if, !procedure, !$var, !theme <nome>, !include <stdlib> …), %getenv e similares, e <img:…> são recusadas. Em vez disso, incorpore o conteúdo.
• D2: importações @ são recusadas. Diagramas com ícones, strings multilinha, HTML ou URLs renderizam apenas para SVG, onde permanecem como links.

Apenas se o usuário explicitamente quiser inclusões ou imagens externas, execute novamente com WHITEBOARD_ALLOW_INCLUDES=1.

Redesenhar com o mesmo título mantém os arquivos anteriores em diagrams/.versions/<slug>/<n>/, então iterar em um diagrama nunca perde a versão anterior.

Quando um Renderizador Está Faltando

O código de saída 3 imprime o comando de instalação. Informe ao usuário o que executar e não instale pacotes globais por conta própria a menos que eles peçam:

• Mermaid: npm i -g @mermaid-js/mermaid-cli
• D2: brew install d2, ou veja https://d2lang.com/tour/install
• PlantUML: brew install plantuml ou apt install plantuml (precisa de Java)

Se um renderizador estiver instalado mas não for encontrado (comum em aplicativos desktop que iniciam sem o PATH do shell de login), defina WHITEBOARD_MMDC, WHITEBOARD_D2 ou WHITEBOARD_PLANTUML para seu caminho completo. A renderização do Mermaid usa o navegador e o pacote Mermaid que vêm com mermaid-cli; se o script encontrar mmdc mas não seu pacote, defina WHITEBOARD_MERMAID_CLI_DIR para a pasta @mermaid-js/mermaid-cli. Quando nada puder ser instalado, forneça o código fonte Mermaid em um bloco fenced para que ainda renderize no GitHub, e informe que não foi verificado por um renderizador.

Bons Diagramas

• Uma ideia por diagrama. Divida qualquer coisa com mais de cerca de 15 nós ou 20 mensagens em um diagrama geral mais diagramas de detalhe.
• Rotule cada aresta com o que flui ou acontece (HTTP, publica OrderPlaced, 1..*).
• Use os nomes do código: nomes de classes, módulos e serviços, endpoints reais, tabelas reais.
• Escolha o tipo que corresponde à pergunta: quem chama quem ao longo do tempo → sequência; quais são as partes → arquitetura/fluxograma; como os dados se parecem → ER ou classe; como algo muda ao longo do tempo → estado.
• Mantenha o texto curto dentro dos nós; coloque os detalhes nos rótulos das arestas ou notas.