Estilo e acessibilidade dos diagramas
Todos os diagramas Mermaid deste repositório usam a mesma paleta monocromática. Branco, gelo, cinza e preto devem permanecer legíveis tanto no site escuro quanto em um documento impresso. A cor sozinha nunca comunica uma decisão, uma falha ou uma responsabilidade.
Paleta
| Token | Cor | Uso |
|---|---|---|
| Papel | #ffffff |
Área do diagrama, fundos dos rótulos |
| Gelo | #f5f5f5 |
Nós principais, notas, linhas ímpares de tabelas |
| Cinza claro | #e0e0e0 |
Nós secundários, participantes, linhas pares |
| Cinza médio | #bdbdbd |
Nós terciários, ativações |
| Cinza de contorno | #999999, #777777, #666666, #555555 |
Bordas de grupos e nós |
| Carvão | #444444, #333333 |
Relações, sinais |
| Tinta | #111111, #000000 |
Texto e ênfase |
O tema canônico é mantido em mermaid-theme.json. Cada bloco inclui essa configuração no frontmatter do diagrama do Mermaid, para que a renderização no GitHub não dependa do CSS do site Jekyll.
Escolha um diagrama que responda a uma pergunta
| Pergunta | Diagrama | O que não se deve implicar |
|---|---|---|
| Quais etapas e pontos de controle vêm a seguir? | flowchart |
Uma seta não é prova de que uma ferramenta foi executada |
| Quem chama quem, e o que é retornado? | sequenceDiagram |
Um retorno tracejado não é outra solicitação |
| Quais transições de estado são permitidas? | stateDiagram-v2 |
Um nome de estado não é um recurso implantado |
| Como os registros se relacionam? | erDiagram |
Uma chave conceitual não cria uma restrição no banco de dados |
| Quais interfaces dependem de quais tipos? | classDiagram |
Uma dependência não é necessariamente herança |
Usamos sintaxe estável com suporte na versão fixada do Mermaid no site. O GitHub controla sua própria versão do renderizador: verifique o renderizador real antes de adotar um novo tipo de diagrama. Tipos beta e mecanismos de layout de terceiros não são necessários para os laboratórios.
Todo diagrama precisa de quatro elementos
- Um bloco delimitado de Mermaid usando o tema canônico
basee a aparênciaclassic. accTitleeaccDescrque descrevam este diagrama, não rótulos genéricos.- Um parágrafo adjacente de Legenda. que explique formas, setas, limites e abreviações. Explique setas contínuas e tracejadas separadamente quando ambas existirem.
- Um parágrafo adjacente de Explicação. que interprete o diagrama e a lição que ele apoia. Inclua a limitação: por exemplo, um grafo é um projeto, não evidência de que ocorreu uma execução distribuída.
Mantenha os rótulos curtos, evite grafos decorativos e não dependa de passar o cursor ou clicar em nós para obter instruções essenciais. Textos e tabelas continuam sendo a fonte dos requisitos.
Validação
node scripts/check-diagrams.js
Isso verifica a configuração da paleta e a documentação, não a correção de um modelo de negócio. Renderize também os novos diagramas na visualização com suporte ou no site publicado; falhas de análise sintática ou renderização devem ser corrigidas antes da publicação.