Decisões
ORG-0005 — Diagramas
- Status: aceita
- Data: 2026-10-18
- Decide: todo documento grande abre com um diagrama; rabisco desenhado por código recomendado, Mermaid permitido
Contexto
Um diagrama no começo de um documento grande faz o leitor entender o assunto antes do detalhe. Há dois jeitos que funcionam: o rabisco no estilo do design system, desenhado por código, que lê bem e envelhece bem; e o Mermaid, rápido de escrever e de mudar.
Decisão
- Todo documento grande abre com um diagrama que resume o assunto.
- Recomendado: rabisco desenhado por código, no estilo de rabisco do design system (o kit vem no modelo), para o que se lê muito e muda pouco: README, visão de produto, guias, a abertura dos documentos.
- Permitido: Mermaid, para o que muda em quase toda change ou precisa sair rápido
(sequências, trechos do
ARCHITECTURE.md). - O texto ao redor diz o mesmo que o diagrama: o diagrama não carrega informação sozinho.
- Imagem que não é diagrama é, de preferência, SVG desenhado por código. Quando precisa de um
gerador de imagens, nasce como prompt num arquivo
<imagem>.prompt.mdao lado, e a imagem é gerada pelo mantenedor.
Alternativas consideradas
| Alternativa | Por que não |
|---|---|
| Só Mermaid | Por que não: rápido, mas sem a identidade visual da Hibex e pouco legível em diagramas grandes |
| Só rabiscos | Por que não: caro para o que muda a cada change |
| Imagens desenhadas à mão em ferramenta gráfica | Por que não: não se revisam em diff nem se regeram quando a marca muda |
Consequências
- Os rabiscos seguem os tokens do design system e os dois temas.
- O texto alternativo de cada imagem vem do título do próprio desenho.
Mais
O detalhe está na documentação da arquitetura.