MÓDULO 4.1

📊 beautiful-mermaid

Renderiza diagramas Mermaid como SVG e PNG usando a biblioteca Beautiful Mermaid — com temas visuais ricos, saída em alta resolução (4K) e integração com agent-browser para captura de screenshot.

6
Tópicos
25
Minutos
Prático
Nível
Apoio
Categoria
Pipeline beautiful-mermaid Código .mmd graph TD / sequenceDiagram render.ts bun / tsx / deno --theme tokyo-night SVG Vetorial infinitamente escalável create-html.ts wrapper HTML para screenshot padding + background agent-browser Playwright / screenshot 4K — 3840×2160 diagram.svg Vector · pequeno diagram.png Raster · alta res Outputs sempre em par: SVG + PNG
1

🧩 O que é / o que faz

Definição precisa

beautiful-mermaid é um skill do Claude Code que renderiza diagramas Mermaid como SVG e PNG usando a biblioteca Beautiful Mermaid. A operação é bidirecional: recebe código .mmd (ou uma descrição em linguagem natural) e produz sempre os dois formatos — SVG vetorial e PNG em alta resolução (4K, viewport 3840×2160, largura mínima 1200px do diagrama).

Flowchart
Fluxos de processo, árvores de decisão, pipelines CI/CD
Sequence
Chamadas de API, fluxos OAuth, transações de banco de dados
State
Máquinas de estado, ciclos de vida de conexão
Class (UML)
Diagramas de classe, padrões de design
Entity-Relationship
Esquemas de banco de dados, modelos de dados
Saída dupla sempre
SVG + PNG produzidos em cada execução, sem exceção
Conceitos-chave
Beautiful Mermaid
biblioteca de renderização
SVG + PNG
sempre os dois formatos
render.ts
script principal
4K output
3840×2160 viewport
2

🎣 Quando dispara

O gatilho oficial do skill (campo description) é preciso:

📋
Gatilho oficial (description)

"Render Mermaid diagrams as SVG and PNG using the Beautiful Mermaid library. Use when the user asks to render a Mermaid diagram."

Situações que acionam o skill

"Renderize este diagrama Mermaid para mim"
Gatilho mais direto — código .mmd já presente
"Gere um diagrama de fluxo do meu processo de autenticação"
Claude gera o código Mermaid e já renderiza em seguida
"Converta este arquivo .mmd em imagem"
Lê o arquivo e executa render.ts com --input
"Visualize a arquitetura do sistema como sequência"
Gera sequenceDiagram e produz SVG + PNG
"Quero um diagrama ER do banco de dados"
Gera erDiagram Mermaid e renderiza
💡
A palavra-chave é "Mermaid"

Se o usuário mencionar "diagrama Mermaid", "código mermaid", "arquivo .mmd" ou pedir explicitamente para renderizar, o Claude ativa este skill. Não é necessário citar "beautiful-mermaid" — o gatilho é o tipo de diagrama.

Conceitos-chave
Render Mermaid
gatilho principal
Gerar + Renderizar
Claude gera o código
--input .mmd
arquivo existente
Qualquer tipo
flow / seq / state / ER
3

🚀 Como melhora suas páginas

Diagramas técnicos elevam significativamente a qualidade de páginas de documentação, cursos e dashboards. O beautiful-mermaid entrega isso com um único comando.

✓ FAZER com beautiful-mermaid
  • ✓ Embutir SVG direto na página HTML (vetorial, sem perda)
  • ✓ Usar PNG de alta resolução em apresentações e slides
  • ✓ Documentar fluxos de API com sequenceDiagram
  • ✓ Visualizar arquitetura de banco de dados com erDiagram
  • ✓ Escolher tema adequado ao contexto (dark/light/tokyo-night)
✗ EVITAR ao usar diagramas
  • ✗ Usar `-- label -->` (espaço-traço) — prefira `-->|label|`
  • ✗ Reutilizar IDs de nós — cada node ID deve ser único
  • ✗ Deixar colchetes abertos em labels de nós
  • ✗ Usar para diagramas que exigem interatividade complexa
  • ✗ Inserir caracteres especiais sem aspas nos labels
💡
SVG embutido direto na página

O SVG gerado pelo beautiful-mermaid pode ser copiado e embutido diretamente no HTML de módulos como o que você está lendo agora. É a mesma técnica usada nos SVGs futuristas deste curso — vetorial, leve, sem dependência externa.

📐
Escalabilidade infinita
SVG vetorial — nenhuma perda de qualidade em qualquer zoom
🖼️
PNG 4K pronto
Sem trabalho manual — captura automática via agent-browser
🎨
Temas visuais ricos
default, dark, forest, neutral, base, tokyo-night e mais
Conceitos-chave
SVG embutível
inline no HTML
PNG 4K
apresentações
Sintaxe limpa
pipe `-->|label|`
Temas variados
dark/light/tokyo-night
4

⚙️ Como funciona por dentro

5 passos sequenciais, sempre nessa ordem — do código Mermaid aos dois arquivos finais.

1
Gerar ou validar código Mermaid
Se o usuário descrever o diagrama em linguagem natural, Claude gera o código Mermaid válido consultando a referência references/mermaid-syntax.md. Se o código já existe, valida a sintaxe.
2
Renderizar SVG com render.ts
Executa o script de renderização com bun, tsx ou deno. Produz <output>.svg no diretório atual.
bun run scripts/render.ts --code "graph TD; A-->B" --output diagram --theme default
# ou via arquivo:
bun run scripts/render.ts --input diagram.mmd --output diagram --theme tokyo-night
# runtimes alternativos:
npx tsx scripts/render.ts --code "..." --output diagram
deno run --allow-read --allow-write --allow-net scripts/render.ts --code "..."
3
Criar HTML wrapper com create-html.ts
Prepara um arquivo HTML mínimo com o SVG, padding adequado e background — pronto para screenshot.
bun run scripts/create-html.ts --svg diagram.svg --output diagram.html
4
Capturar PNG com agent-browser (Playwright)
O skill agent-browser abre o HTML wrapper no Playwright, configura viewport 4K (3840×2160) com largura mínima de 1200px no diagrama e captura o screenshot em PNG de alta resolução.
5
Limpar arquivos intermediários
Remove o HTML wrapper temporário, mantendo apenas diagram.svg e diagram.png no diretório de trabalho.
Dependências reais
  • Beautiful Mermaid library — núcleo de renderização
  • scripts/render.ts — renderização SVG
  • scripts/create-html.ts — wrapper HTML
  • agent-browser — Playwright / screenshot 4K
  • bun / tsx / deno — runtimes TypeScript
Temas disponíveis
  • default — claro padrão Mermaid
  • dark — escuro nativo
  • forest — tons verdes
  • neutral — sem cor forte
  • tokyo-night — neon escuro moderno
  • base — minimalista
⚠️
Problemas comuns e soluções
  • Tema não aplicado: verifique --bg e --fg CSS no SVG de saída
  • Diagrama cortado: use -->|label| — nunca -- label -->
  • SVG vazio/malformado: verifique IDs de nós únicos e colchetes fechados nos labels
Conceitos-chave
render.ts
script de renderização
create-html.ts
wrapper screenshot
agent-browser
Playwright 4K
bun/tsx/deno
runtimes suportados
5

💬 Exemplo prático + PROMPT pronto

Dois cenários concretos: renderizar código existente e gerar do zero a partir de uma descrição.

Sintaxe Mermaid — exemplos diretos

Flowchart (processo com decisão)
flowchart TD
    A([Início]) --> B[/Receber input/]
    B --> C{Válido?}
    C -->|Sim| D[Processar]
    C -->|Não| E[Retornar erro]
    D --> F[(Salvar no DB)]
    F --> G([Fim])
    E --> G
Sequence (fluxo de autenticação)
sequenceDiagram
    participant U as Usuário
    participant A as App
    participant S as Servidor
    U->>A: Login (email/senha)
    A->>S: POST /auth/login
    S-->>A: JWT token
    A-->>U: Acesso liberado
    Note over S: Valida credenciais
💡
Regra de ouro nos labels de aresta

Sempre use C -->|Sim| D com pipe. Nunca C -- Sim --> D (espaço-traço pode causar render incompleto, conforme o SKILL.md).

📋 PROMPT 1 — Renderizar código existente
Cole no Claude Code 
Renderize o diagrama Mermaid abaixo como SVG e PNG.
Use o tema tokyo-night. Salve como auth-flow.

```mermaid
sequenceDiagram
    participant U as Usuário
    participant A as App
    participant S as Servidor
    U->>A: Login (email/senha)
    A->>S: POST /auth/login
    S-->>A: JWT token
    A-->>U: Acesso liberado
```
📋 PROMPT 2 — Gerar e renderizar do zero
Cole no Claude Code 
Gere e renderize um flowchart Mermaid do pipeline CI/CD:
push → build → testes unitários → testes e2e →
deploy staging → aprovação manual → deploy produção.
Use o tema dark. Salve como cicd-pipeline.
📋 PROMPT 3 — Embutir diagrama em página HTML
Cole no Claude Code 
Gere um erDiagram Mermaid para um sistema de e-commerce
com entidades: Customer, Order, Product, OrderItem, Payment.
Renderize com tema forest e depois copie o SVG
inline para o arquivo docs/schema.html.
Conceitos-chave
flowchart TD
fluxo top-down
sequenceDiagram
interações sequenciais
-->|label|
rótulo de aresta seguro
--theme
parâmetro de tema
6

🧬 Combina com / limites

O beautiful-mermaid se encaixa num ecossistema de skills de visualização e apoio. Entender onde começa e termina cada ferramenta evita escolhas erradas.

📊 beautiful-mermaid vs ✏️ excalidraw

M beautiful-mermaid
  • → Diagramas técnicos precisos e estruturados
  • → Sintaxe declarativa — você define a lógica, a lib organiza o layout
  • → Estilo polido, profissional, temas curados
  • → SVG + PNG exportáveis para documentação
  • → Ideal para: arquitetura, fluxos de código, BD, CI/CD
E excalidraw (próximo módulo 4.2)
  • → Diagramas "à mão", sketchy, exploratorios
  • → Estilo hand-drawn — comunica "trabalho em progresso"
  • → Ótimo para wireframes, rascunhos de arquitetura inicial
  • → Interativo — o usuário pode editar no browser
  • → Ideal para: UX wireframes, brainstorm visual, sketches de UI
Regra prática: use Mermaid quando precisar de precisão técnica e outputs profissionais. Use Excalidraw quando o visual "polished" pode inibir a iteração — rascunhos informam que a ideia ainda está aberta.

Combina com outros skills do curso

🕹️
agent-browser (Módulo 4.3)
Dependência direta — o agent-browser (Playwright) é quem captura o PNG 4K no Passo 4 do workflow. Sem ele, a saída é apenas SVG.
🔭
website-intelligence (Módulo 4.4)
Combine: renderize diagramas de arquitetura de sites analisados pelo website-intelligence — arquiteturas de layout, fluxos de navegação.
⚛️
frontend-design (Módulo 1.1)
Embutir o SVG gerado pelo beautiful-mermaid diretamente em páginas React/Tailwind criadas pelo frontend-design — diagramas técnicos inline.
🏷️
brand-guidelines (Módulo 2.2)
Gere diagramas de arquitetura de marca ou fluxos de identidade visual, exportando SVG com as cores certas para apresentações de guideline.
✓ USE quando
  • ✓ Precisa de diagramas técnicos em documentação
  • ✓ Quer SVG embutível em HTML ou PNG para slide
  • ✓ O diagrama tem estrutura lógica clara (fluxo, sequência, estado)
  • ✓ Necessita de múltiplos temas visuais
✗ NÃO USE quando
  • ✗ O diagrama é um wireframe ou rascunho conceitual (→ excalidraw)
  • ✗ Precisa de diagramas interativos editáveis no browser
  • ✗ O conteúdo é uma animação ou diagrama 3D (→ 3d-animation-creator)
  • ✗ Precisa de controle total do layout visual de cada elemento
Conceitos-chave
Mermaid = técnico
precisão e estrutura
Excalidraw = sketch
rascunho e wireframe
agent-browser
dependência direta
SVG embutível
integra com T1/T2

📋 Resumo do Módulo 4.1

O que você aprendeu

  • ✓beautiful-mermaid renderiza Mermaid como SVG + PNG usando a biblioteca Beautiful Mermaid
  • ✓O gatilho é o usuário pedir para renderizar um diagrama Mermaid — qualquer tipo
  • ✓O pipeline tem 5 passos: validar → render.ts → create-html.ts → agent-browser (Playwright) → limpar
  • ✓PNG é capturado em 4K (3840×2160) com largura mínima de 1200px no diagrama
  • ✓Use sempre -->|label| para rótulos de aresta — nunca espaço-traço
  • ✓Mermaid = diagramas técnicos precisos; Excalidraw = rascunhos sketchy e wireframes
  • ✓O SVG gerado é embutível inline em HTML — mesma técnica dos SVGs deste curso
Próximo módulo:
4.2 ✏️ excalidraw

O skill que gera diagramas no estilo "à mão" do Excalidraw — wireframes, rascunhos de arquitetura e sketches de UI com visual informal que comunica "em construção".

Trilha 4 — Apoio
✓4.1 📊 beautiful-mermaid
→4.2 ✏️ excalidraw
○4.3 🕹️ agent-browser
○4.4 🔭 website-intelligence
← Voltar para Trilha 4 Próximo Módulo: 4.2 ✏️ excalidraw →