IbrahimSobh/content-mermaid

Content Mermaid

Produz diagramas Mermaid para processos e estruturas técnicas. Esta é a contraparte rápida e orientada por sintaxe do content-diagrams: os mesmos padrões de clareza visual, mas construída com uma linguagem que já garante geometria correta, portanto o esforço se concentra em escolher o tipo de diagrama certo e um sistema de cores legível e consistente, em vez de verificar coordenadas.

Relacionamento com content-diagrams

Ambos os skills compartilham os mesmos padrões — texto legível, um sistema de cores real em vez de decoração, clareza sobre densidade — mas content-diagrams calcula sua própria geometria SVG manualmente, enquanto este skill entrega a geometria inteiramente ao mecanismo de layout do Mermaid; escolha entre eles com base em onde o diagrama será realmente visualizado (superfície Mermaid nativa vs. uma plataforma que mostra apenas imagens estáticas), não por hábito, e se houver dúvida genuína, pergunte — o código-fonte Mermaid não é capturado de tela de forma limpa em um gráfico independente polido sem um retrabalho real.

Por que não há loop de verificação aqui

content-diagrams gasta a maior parte do esforço em geometria: uma linha, caixa ou rótulo SVG são apenas números que Claude calculou, e números calculados podem estar errados — daí renderizar, capturar tela, recortar e verificar.

O Mermaid elimina esse modo de falha completamente. Largura do nó, quebra de texto, caminhos de setas e prevenção de colisão entre elementos são tarefas do renderizador, não de Claude — o renderizador não colocará um rótulo em cima de uma caixa ou roteará uma linha através de uma forma. Rederivar esse loop de verificação aqui (capturar tela do diagrama renderizado, recortar, verificar sobreposições) apenas queimaria tokens e latência confirmando algo que a ferramenta já garante.

O que ainda pode dar errado é completamente diferente, e completamente textual:

• Sintaxe quebrada (colchetes não fechados, palavra reservada usada como ID de nó, tipos de seta incompatíveis)
• Uma aresta referenciando um ID de nó que nunca foi definido
• Contraste de cor ruim (um preenchimento e uma cor de texto que não são realmente legíveis um contra o outro)
• O tipo de diagrama errado para a estrutura real do conteúdo

Portanto, a verificação aqui significa: ler a sintaxe uma vez para verificar a correção, verificar se cada classDef emparelha um preenchimento com uma cor de texto genuinamente contrastante e confirmar se o tipo de diagrama corresponde ao que está sendo modelado. Nenhuma renderização de imagem necessária.

Seleção do tipo de diagrama

Escolha o tipo com base no que o conteúdo estruturalmente é — este é o equivalente Mermaid da seleção de motivo do content-diagrams:

Estrutura do conteúdo	Tipo Mermaid
Etapas sequenciais com ramificações/loops (um processo, um fluxo de trabalho, um algoritmo)	flowchart TD (de cima para baixo) ou LR (da esquerda para a direita para pipelines/linhas do tempo)
Mensagens ordenadas no tempo entre atores/serviços (chamadas de API, trocas de protocolo)	sequenceDiagram
Estados de uma entidade e as transições entre eles (um ciclo de vida, uma máquina de estados)	stateDiagram-v2
Modelo de dados / relacionamentos entre entidades (esquemas, tabelas de banco de dados)	erDiagram
Estrutura orientada a objetos (classes, herança, interfaces)	classDiagram
Cronograma com durações e dependências	gantt
Decomposição hierárquica / brainstorming sem sequência estrita	mindmap
Narrativa cronológica (histórico de um projeto, histórico de versão)	timeline
Priorização em dois eixos (impacto vs. esforço, etc.)	quadrantChart

Não defina flowchart como padrão para tudo — uma solicitação como "diagrama como nossos serviços se chamam" é um sequenceDiagram mesmo que seja tentador desenhá-lo como caixas e setas; uma solicitação como "mostre os estados pelos quais um ticket passa" é stateDiagram-v2, não um fluxograma com losangos representando estados.

Sistema de cores e legibilidade

Este é o único lugar onde a verificação manual ainda importa, porque o Mermaid renderizará felizmente escolhas de cores ilegíveis sem reclamar.

A regra: cada classDef deve emparelhar um preenchimento com uma cor de texto que foi deliberadamente escolhida para contrastar com ele — nunca deixe color não definido e espere que o padrão do tema funcione. A paleta padrão do Mermaid (verde/rosa/azul suave com texto preto) é boa precisamente porque preenchimento e texto foram escolhidos juntos; no momento em que você substitui fill por algo mais saturado ou escuro, você também deve definir color explicitamente, ou reproduzirá um defeito comum: caixas de aparência legível com texto que na verdade tem baixo contraste contra elas.

Duas receitas de paleta, escolha uma e use-a consistentemente em todas as classes em um diagrama (não misture):

1. Preenchimento escuro / texto branco (o padrão — comprovado, alto contraste, lê-se bem em temas de chat claro e escuro):

   classDef categoria1 fill:#1e3a5f,stroke:#0d1f33,stroke-width:2px,color:#ffffff
   

2. Preenchimento de tom claro / texto escuro / traço saturado (use quando um diagrama precisar ficar visualmente próximo a um SVG do content-diagrams que segue sua convenção de tom claro):

   classDef categoria1 fill:#e1f0ff,stroke:#1e3a5f,stroke-width:2px,color:#1a1a1a
   

Tomando emprestado diretamente a regra do content-diagrams: um matiz por categoria, aplicado em todo lugar onde essa categoria aparece — a mesma cor no preenchimento/traço em cada nó dessa função, não um de cada vez. Atribua matizes por função, por exemplo:

• Azul → entradas / dados / itens de backlog
• Verde → processo / etapas de trabalho ativo
• Âmbar ou marrom → pontos de decisão / portões
• Roxo → saídas / versões / estados terminais
• Vermelho → loops de feedback / caminhos de falha / retrospectiva

Trave a tela para que não dependa do modo claro/escuro do host. Coloque uma diretiva init como a primeira linha do diagrama:

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif', 'fontSize': '16px', 'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0d1f33', 'lineColor': '#666666', 'background': '#ffffff' } } }%%

theme: 'base' mais themeVariables explícitos significa que o diagrama terá a mesma aparência, independentemente de qual tema Mermaid o ambiente host usar por padrão — não confie apenas no nome do tema padrão (default, dark, forest, etc.), pois isso deixa as cores reais a critério do renderizador.

Tamanho da fonte: 16px no mínimo para qualquer diagrama com mais de um punhado de nós; 14px apenas se o diagrama for simples o suficiente para que a legibilidade não esteja em questão. Se um diagrama precisar encolher abaixo de 14px para caber seus rótulos, esse é o mesmo sinal de "clareza sobre densidade" do content-diagrams — divida o diagrama ou corte o conteúdo, não encolha ainda mais o texto.

O alcance da estilização difere por tipo de diagrama: flowchart, stateDiagram-v2 e classDiagram todos suportam atribuição direta de classDef/class por nó, portanto use o sistema de cores por categoria acima nó por nó. sequenceDiagram, erDiagram e gantt têm estilização por elemento muito mais limitada — para estes, coloque o esforço nos themeVariables no bloco init (actorBkg, actorTextColor, noteBkgColor, etc. para diagramas de sequência) em vez de esperar que classes de nível de nó funcionem da mesma forma.

Gramática de setas

Ao contrário do SVG codificado manualmente, o Mermaid renderiza rótulos de seta de forma limpa com posicionamento automático — o texto -->|rótulo| não corre o risco de cair em cima de uma forma como um rótulo SVG posicionado manualmente. Portanto, ao contrário do padrão "manter texto fora das setas, decodificar via legenda" do content-diagrams, rotular setas diretamente é bom e frequentemente mais claro aqui. Ainda assim, mantenha os rótulos como fragmentos curtos ("aprovado", "repetir", "em falha") em vez de frases — um rótulo é uma tag, não uma sentença.

Reserve o estilo da linha para a mesma distinção ampla que o content-diagrams usa:

• Seta sólida (-->) → fluxo primário/normal
• Seta tracejada (-.->) → feedback, um caminho opcional ou uma interação externa/indireta
• Seta grossa (==>) → um caminho enfatizado ou crítico, usado com moderação

Mantenha rótulos curtos; use subgráficos para agrupar

O texto do nó deve ser uma frase curta, não uma sentença — o Mermaid quebrará ou transbordará de forma estranha em rótulos do tamanho de um parágrafo como qualquer outra ferramenta. Se um nó precisar de várias linhas, insira-as explicitamente com <br/> dentro do rótulo em vez de confiar na quebra automática para quebrar em um lugar sensato.

Use subgraph para agrupar etapas relacionadas (por exemplo, tudo dentro de um sprint, um estágio de implantação, um limite de serviço) — é o equivalente Mermaid de uma caixa de agrupamento, e pode ser estilizado com sua própria linha style NomeSubgrafico fill:...,stroke:.... Não aninhe subgráficos com mais de um nível de profundidade; fica difícil de ler rapidamente.

Fluxo de trabalho

1. Identifique a estrutura subjacente e escolha o tipo de diagrama da tabela acima antes de escrever qualquer sintaxe.
2. Atribua cores de categoria às funções presentes (entradas, etapas do processo, decisões, saídas, feedback) — esboce isso em uma ou duas frases antes de escrever as classDef, o mesmo que a etapa "esboçar o raciocínio do motivo" do content-diagrams, para que a escolha seja auditável se o usuário quiser ajustar uma peça.
3. Escreva o diagrama, começando com a diretiva %%{init: ...}%%, depois a estrutura, depois as atribuições classDef/class (ou themeVariables para tipos que não suportam classes por nó).
4. Auto-verifique a sintaxe — todo ID de nó usado em uma aresta está definido em algum lugar; toda classDef tem fill e color definidos; colchetes/aspas estão equilibrados; nenhum rótulo do tamanho de um parágrafo. Nenhuma renderização, nenhuma captura de tela.
5. Salve como um arquivo .mermaid via create_file para que seja renderizado inline como um artefato, usando um slug descritivo: /mnt/user-data/outputs/<slug>.mermaid. Apresente com present_files.
6. Se o usuário precisar do diagrama como uma imagem estática portátil (para incorporar em algum lugar que não renderize Mermaid, ou para arquivamento), diga isso claramente: este ambiente não executa exportação de Mermaid para imagem headless de forma confiável (depende de um download do Chromium que a rede em sandbox geralmente não consegue acessar). Aponte para mermaid.live para uma exportação manual, ou mude para content-diagrams se o requisito real for um gráfico independente.

O que não fazer

• Não deixe o color de uma classDef não definido depois de substituir fill — esse é exatamente o bug de contraste que este skill existe para evitar.
• Não misture as receitas de paleta de preenchimento escuro e preenchimento claro dentro de um diagrama.
• Não defina flowchart como padrão para toda solicitação — escolha o tipo que corresponde à estrutura real (sequência, estado, ER, etc.).
• Não reintroduza o loop de renderizar/capturar/verificar do content-diagrams aqui — ele está resolvendo um problema que o mecanismo de layout do Mermaid não tem.
• Não coloque texto do tamanho de um parágrafo em um rótulo de nó; use <br/> para quebrar ou corte o conteúdo.
• Não aninhe subgráficos com mais de um nível.
• Não prometa uma exportação PNG/SVG limpa deste sandbox sem ressalvar que a renderização headless do Mermaid pode não funcionar aqui.