A maioria dos diagramas técnicos é criada usando um de dois extremos: motores de auto-layout ou ferramentas de posicionamento absoluto. Ferramentas de auto-layout como Mermaid, Graphviz e D2 permitem que você declare entidades e conexões, mas o software decide onde elas ficarão [1]. Por outro lado, ferramentas como Figma, Excalidraw e draw.io oferecem controle total sobre o posicionamento, mas cada edição em um diagrama complexo exige a movimentação manual e lenta de elementos [1].
O Reladraw introduz um meio-termo. É uma linguagem de texto para diagramas onde você descreve onde as coisas ficam usando termos relativos em vez de coordenadas [1]. Em vez de tentar adivinhar como um algoritmo renderizará um fluxo ou arrastar caixas manualmente por uma tela, você define a disposição em linguagem simples [S1, S3].
Como Funciona o Posicionamento Relativo
No reladraw, cada posição é declarada em relação a outro elemento [1]. Não existem coordenadas na linguagem em nenhuma forma [3]. Em vez disso, você usa instruções direcionais para vincular nós uns aos outros [2].
Por exemplo, um nó pode ser colocado above (acima), below (abaixo), left of (à esquerda de) ou right of (à direita de) outro nó [2]. Você também pode usar direções combinadas, como above-left of (acima e à esquerda de), ou usar level with (alinhado com) para garantir que dois elementos compartilhem a mesma linha central [2]. Para lidar com agrupamentos mais complexos, você pode colocar um elemento right of A and B (à direita de A e B), o que o alinha em relação à caixa que engloba ambos os elementos [2].
As distâncias no reladraw são tratadas como espaços mínimos, e não como medidas exatas [3]. Um espaço nunca é um número exato; em vez disso, os elementos ficam o mais próximos possível, conforme permitido pelas instruções [3]. Se você colocar um nó between (entre) dois outros, ele os afastará exatamente o necessário para caber [3]. Se esse nó central for excluído, os elementos restantes se aproximam automaticamente [3].
Melhorando a Diagramação por Agentes de IA
As ferramentas de diagramação tradicionais criam um “ponto cego” para agentes de IA. Quando um agente gera código Mermaid, ele está tentando adivinhar um layout que um algoritmo definirá posteriormente [1]. O agente não consegue ver o SVG resultante, o que significa que ele precisa renderizar a imagem e analisá-la para encontrar erros, criando um processo de ida e volta lento [3].
Com ferramentas baseadas em pixels, o problema é diferente. Um agente precisa reconstruir a imagem inteira a partir de uma lista de números antes de decidir quais coordenadas alterar para mover um único serviço [1].
O Reladraw resolve isso colocando a disposição diretamente no arquivo de origem como frases [1]. Isso permite que um agente possa:
- Confirmar a intenção relendo a fonte para verificar se um banco de dados está
under(sob) uma API [S1, S3]. - Alterar a imagem simplesmente editando a frase que define uma posição [1].
- Evitar a necessidade de interpretar sistemas de coordenadas complexos [1].
No entanto, como a ferramenta resolve a renderização final a partir dessas instruções, um agente não consegue confirmar certos resultados apenas via texto [3]. Ele não consegue saber se uma string de texto longa extrapolou seu nó ou se dois clusters ancorados independentemente se sobrepuseram sem uma renderização visual ou um relatório de diagnóstico [3].
Sintaxe e Implementação
O Reladraw utiliza um formato simples de uma instrução por linha, sem aninhamentos ou recuos significativos [3]. Isso garante que nenhuma linha dependa da posição de outra [1].
Os principais elementos da sintaxe incluem:
- Nós (Nodes): Definidos como
node name "text"[2]. Nomes com pontos (ex:server.docker) indicam um nó filho, desde que o pai seja declarado primeiro [2]. - Arestas (Edges): As conexões são definidas usando setas, como
edge a -> b[2]. Você pode especificar a curvatura da linha usandofrom: right to: left[2]. - Estilização: A aparência é gerenciada via a palavra-chave
styleou entre colchetes após o texto, permitindo cores, tamanhos e formas personalizadas comorectangle,documentoudatabase[2].
Para usar o reladraw, você pode escrever um arquivo .reladraw e renderizá-lo em um SVG independente usando o comando reladraw diagram.reladraw -o diagram.svg [3]. Para quem utiliza assistentes de IA como Claude Code, Cursor ou Copilot, uma habilidade específica de agente pode ser instalada via npx skills add reladraw/reladraw -g para ensinar a sintaxe da linguagem ao modelo [1].
Se você quiser experimentar a linguagem sem instalar nada, pode testar o playground do reladraw no seu navegador para ver os layouts serem resolvidos em tempo real enquanto você edita a fonte [S1, S2].
