Mermaid com a cara do site

Diagrama em imagem envelhece pior que código. O PNG exportado há dois anos continua no README mostrando um serviço que fala com um banco que já foi desligado, e ninguém corrige — corrigir exige achar o arquivo original, abrir a ferramenta, exportar de novo. Diagrama em texto envelhece junto com o texto: mora no mesmo arquivo, entra no mesmo commit, aparece no mesmo diff.

É por isso que este site desenha com Mermaid. O preço é que o Mermaid chega com identidade visual própria, e um site cuja regra é uma cor de acento e só uma não convive com isso. Este texto é o catálogo do que ele desenha aqui e o registro do que custou para ele desaparecer na página.

As nove cores

Toda cor de diagrama sai de um custom property do css/base.css, lido em tempo de execução. São nove, e são hex sólidos de propósito: o Mermaid faz conta com eles para derivar tons — borda de nó, fundo de nota, texto sobre fundo — e derivar a partir de rgba() com alfa dá resultado errado.

• --mm-nodefundo de nó, ator, estado
• --mm-node-borderborda de tudo que é caixa
• --mm-texttodo rótulo e toda legenda
• --mm-linearesta, seta, linha de vida
• --mm-clusterfundo de subgrafo
• --mm-cluster-borderborda tracejada do subgrafo
• --mm-notenota e ativação — o único destaque
• --mm-note-borderborda da nota, na cor de acento
• --mm-altfaixa alternada, fundo secundário

Troque o tema no canto superior direito e as nove trocam de valor. O que não troca sozinho é o desenho: o SVG que o Mermaid produz carrega a cor embutida em cada forma e não herda custom property. Trocar o tema aqui significa redesenhar — é a única parte deste site em que o JavaScript precisa saber que cor é a cor.

O catálogo

O Mermaid 11.15 desenha vinte e dois tipos de diagrama. Vinte e um funcionam por CDN sem plugin nenhum; os oito abaixo são os que este site usa, e cada um está desenhando algo verdadeiro sobre o próprio site — nenhum é exemplo de manual.

flowchart TD
    F["fonte no .html"] --> W["espera document.fonts.ready"]
    subgraph tokens["css/base.css"]
      direction LR
      T1["--mm-node"] --- T2["--mm-line"]
    end
    tokens --> C["themeVariables"]
    W --> I["mermaid.initialize"]
    C --> I
    I --> R["mermaid.run"]
    R --> A{{"cabe na coluna?"}}
    A -- "sim" --> N(["fica no tamanho natural"])
    A -- "não" --> Z(["reduz, e o rótulo encolhe junto"])

sequenceDiagram
    autonumber
    participant N as navegador
    participant F as document.fonts
    participant M as mermaid
    N->>F: espera fonts.ready
    activate F
    F-->>N: a JetBrains Mono chegou
    deactivate F
    N->>M: run() com os fontes do grafo
    activate M
    Note over M: mede o texto renderizado
    M-->>N: svg com a cor embutida
    deactivate M

stateDiagram-v2
    [*] --> Escondido
    Escondido --> Desenhado: run() terminou
    Desenhado --> Ajustado: ajustarEscala
    Ajustado --> Escondido: tema mudou
    Escondido --> Fonte: mermaid fora do ar
    Fonte --> [*]
    note right of Fonte
        o leitor vê o texto do
        grafo, não um buraco
    end note

classDiagram
    class Site {
        +tema() string
        +token(nome) string
        +alternar()
    }
    class Publicacao {
        -fontes
        +desenhar()
        +ajustarEscala()
    }
    Publicacao ..> Site : lê os tokens

erDiagram
    PUBLICACAO }o--|| TOPICO : "tem"
    PUBLICACAO ||--o{ DIAGRAMA : "contém"
    PUBLICACAO ||--|| CARTAO : "gera"
    PUBLICACAO {
        string titulo
        date publicado
        int palavras
    }

gitGraph
    commit id: "site no ar"
    branch fix/ancoras
    commit id: "checks na ci"
    checkout main
    merge fix/ancoras tag: "publica"
    commit id: "este texto"

mindmap
  root((mermaid))
    cor
      themeVariables
      themeCSS
      redesenhar no tema
    medida
      fonts.ready
      useMaxWidth
      largura natural
    queda
      sem CDN
      grafo inválido

xychart-beta
    title "largura natural de cada espécime, em px"
    x-axis [flow, seq, state, class, er, git, mind, xy]
    y-axis "px" 0 --> 800
    bar [643, 690, 580, 247, 596, 368, 665, 700]

A camada de customização

Nada do que está acima é o Mermaid de fábrica. São nove ajustes, e cada um existe por um defeito visível — não por preferência estética:

As cores não são escritas na configuração: são lidas do CSS. É o que garante que existe um só lugar onde a paleta do site vive, e que o diagrama nunca discorda dele.

function cor(nome) {
  return window.Site.token(nome);        // getComputedStyle no :root
}

themeVariables: {
  darkMode:           window.Site.tema() === 'dark',
  fontFamily:         MONO,
  primaryColor:       cor('--mm-node'),
  primaryBorderColor: cor('--mm-node-border'),
  primaryTextColor:   cor('--mm-text'),
  lineColor:          cor('--mm-line'),
  clusterBkg:         cor('--mm-cluster'),
  noteBkgColor:       cor('--mm-note'),
  noteBorderColor:    cor('--mm-note-border')
  // …e mais trinta, para ator, linha de vida, ativação e estado
}

O ajuste menos óbvio e o mais importante é a espera pela fonte. O Mermaid calcula o tamanho do desenho medindo o texto renderizado; se ele roda antes de a JetBrains Mono chegar, mede com a fonte de fallback, que é mais larga. O mesmo diagrama de sequência sai com 922px em vez de 777px — número que está registrado no próprio código, de quando o defeito apareceu — e passa a ser reduzido para caber na coluna sem nenhum motivo, e sem erro nenhum no console.

var fontesProntas = (document.fonts && document.fonts.ready)
  ? document.fonts.ready
  : Promise.resolve();

fontesProntas.then(desenhar).then(ajustarEscala);

As três camadas de obediência

Medindo tipo por tipo apareceu um padrão que eu não esperava, e que é a informação mais útil deste texto: os tipos do Mermaid não obedecem todos ao mesmo mecanismo de tema. São três grupos.

Primeiro: os que obedecem a themeVariables. Flowchart, sequência, estado, classe, ER, requisito, bloco, arquitetura. Configura uma vez, valem todos. É o grupo onde vive quase todo diagrama de engenharia.

Segundo: os que têm paleta numerada própria. O gitGraph pinta por git0..git7, o mindmap por cScale0..cScale11, o xychart por um bloco xyChart inteiro, e nenhum deles olha para primaryColor. Cada um exige tratamento separado — e o sintoma é sempre o mesmo: uma cor que não existe no seu site aparecendo no desenho. Caqui, no caso de dois deles.

Terceiro: os que não sobrevivem a uma cor de acento só. Aqui não é questão de configurar: gráfico de pizza e jornada de usuário precisam de cor categórica — cor que distingue, não que decora. Numa paleta de quase-branco, quase-preto e um vermelho, três fatias viram três tons quase idênticos:

pie title peso de uma publicação, em KB
    "mermaid pela CDN" : 3300
    "highlight.js" : 120
    "html, css e js do site" : 46

A medição

A regra que eu seguia — "diagrama não pode passar de uns 840px" — estava escrita no CLAUDE.md do repositório como estimativa. Medindo, ela virou um número exato e ganhou explicação: 840px é a largura da coluna do artigo numa tela de 1440px. Numa tela de 1520px ou mais a coluna é de 920px. Acima disso, o desenho é reduzido para caber e o rótulo encolhe na mesma proporção.

E a largura vem de dois lugares diferentes, o que decide como consertar. Nos tipos que têm espécime nesta página, o número da tabela é o deste desenho — largura de tipo cujo tamanho vem do conteúdo só significa algo junto com o grafo que a produziu:

A diferença é prática. Nos tipos cuja largura vem do conteúdo, um diagrama largo se resolve encurtando rótulo ou virando o eixo — mexendo no grafo. Nos de largura fixa, mexer no grafo não muda nada: dobrei o conteúdo do quadrantChart, do sankey, do packet e do gantt e os quatro devolveram exatamente a mesma largura. Lá o único caminho é configuração — ou não usar o tipo.

O que não funciona

Seis coisas que custaram tempo, na ordem em que doeriam de novo:

1. <br/> em rótulo de nó. A tag é removida e o espaço em volta é engolido: "cabe na<br/>janela?" vira cabe najanela?. Não muda com htmlLabels ligado nem desligado.¹
2. Dois-pontos no rótulo de relação do classDiagram. Derruba o parser inteiro e desenha a bomba de erro. Vale para o rótulo depois de : em qualquer relação de classe.
3. themeVariables.fontSize não chega ao rótulo do nó. Quem manda ali é o themeCSS, e só com !important.
4. Um grafo inválido derruba os outros. Defeito deste site, não do Mermaid: o catch do mermaid.run é global, então um erro de sintaxe num diagrama marca todos os da página como indisponíveis. Foi assim que eu descobri o item 2 — e é o que a medição um-tipo-por-página contornou.³
5. zenuml não vem no pacote. Está na documentação, mas o mermaid.min.js do cdnjs não tem uma única ocorrência da palavra: exige o pacote @mermaid-js/mermaid-zenuml à parte. Dos 22 tipos, é o único que não desenha aqui.
6. Ligadura em bloco de código. A JetBrains Mono desenha != como um sinal de diferente. Em prosa é bonito; em código é mentira, porque mostra um caractere que não está lá e que não vem no copiar. Desligada em pre e code.

O que eu levo disso

Diagrama como texto vale a pena — o desenho envelhece junto com o texto, e isso resolve o problema real. Mas tematizar uma biblioteca de desenho não é escolher cores: é descobrir, um tipo por vez, onde cada cor foi parar. Três mecanismos diferentes, uma paleta numerada escondida por tipo, e um cálculo de layout que depende de a fonte já ter chegado.

E a regra que eu recomendaria a quem for fazer o mesmo é a mais chata: meça. As duas coisas que este texto corrigiu no meu próprio entendimento — de onde vem o 840px e quais tipos ignoram o tema — não apareceram lendo a documentação nem o código. Apareceram renderizando e lendo o número.