MODULE 4.1

📊 beautiful-mermaid

Renders Mermaid diagrams as SVG and PNG using the Beautiful Mermaid library — with rich visual themes, high-resolution output (4K), and integration with agent-browser for screenshot capture.

Topics

Minutes

Practical

Level

Support

🧩 What it is / what it does

Precise definition

beautiful-mermaid is a Claude Code skill that renders Mermaid diagrams as SVG and PNG using the Beautiful Mermaid library. The operation is bidirectional: it accepts code .mmd (or a natural-language description) and produces always both formats — vector SVG and high-resolution PNG (4K, 3840×2160 viewport, diagram width of at least 1200px).

Flowchart

Process flows, decision trees, CI/CD pipelines

Sequence

API calls, OAuth flows, database transactions

State

State machines, connection lifecycles

Class (UML)

Class diagrams, design patterns

Entity-Relationship

Database schemas, data models

Always output both

SVG + PNG produced on every run, without exception

Key Concepts

Beautiful Mermaid

rendering library

SVG + PNG

always both formats

render.ts

main script

4K output

3840×2160 viewport

🎣 When it triggers

The skill's official trigger (field description) you need to:

📋

Official trigger (description)

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

Situations that trigger the skill

"Render this Mermaid diagram for me"

Most direct trigger — .mmd code already present

"Generate a flowchart of my authentication process"

Claude generates the Mermaid code and renders it right away

"Convert this .mmd file to an image"

Read the file and run render.ts with --input

"Visualize the system architecture as a sequence"

Generates a sequenceDiagram and produces SVG + PNG

"I want an ER diagram of the database"

Generates an erDiagram in Mermaid and renders it

💡

The keyword is "Mermaid"

If the user mentions "Mermaid diagram," "Mermaid code," ".mmd file," or explicitly asks to render, Claude activates this skill. There’s no need to mention "beautiful-mermaid" — the trigger is the type of diagram.

Key Concepts

Mermaid rendering

main trigger

Generate + Render

Claude generates the code

--input .mmd

existing file

Any type

flow / seq / state / ER

🚀 How it improves your pages

Technical diagrams significantly improve the quality of documentation pages, courses, and dashboards. beautiful-mermaid delivers this with a single command.

✓ DO with beautiful-mermaid

✓ Embed SVG directly in the HTML page (vector, no quality loss)
✓ Use high-resolution PNGs in presentations and slides
✓ Document API flows with sequenceDiagram
✓ Visualize database architecture with erDiagram
✓ Choose a theme suited to the context (dark/light/tokyo-night)

✗ AVOID when using diagrams

✗ Use `-- label -->` (space-dash) — prefer `-->|label|`
✗ Reuse node IDs — each node ID must be unique
✗ Leave square brackets open in node labels
✗ Use for diagrams that require complex interactivity
✗ Insert special characters in labels without quotation marks

💡

SVG embedded directly in the page

The SVG generated by beautiful-mermaid can be copied and embedded directly into the HTML of modules like the one you're reading now. It's the same technique used for this course's futuristic SVGs — vector-based, lightweight, with no external dependencies.

📐

Infinite scalability

Vector SVG — no loss of quality at any zoom level

🖼️

4K-ready PNG

No manual work — automatic capture via agent-browser

🎨

Rich visual themes

default, dark, forest, neutral, base, tokyo-night, and more

Key Concepts

Embeddable SVG

inline in the HTML

4K PNG

presentations

Clean syntax

pipe `-->|label|`

Varied themes

dark/light/tokyo-night

⚙️ How it works under the hood

5 sequential steps, always in this order — from Mermaid code to the two final files.

Generate or validate Mermaid code

If the user describes the diagram in natural language, Claude generates valid Mermaid code by consulting the reference references/mermaid-syntax.md. If the code already exists, validate the syntax.

Render SVG with render.ts

Runs the rendering script with bun, tsx, or deno. Produces <output>.svg in the current directory.

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 "..."

Create an HTML wrapper with create-html.ts

Prepare a minimal HTML file with the SVG, appropriate padding, and a background — ready for a screenshot.

bun run scripts/create-html.ts --svg diagram.svg --output diagram.html

Capture PNG with agent-browser (Playwright)

The skill agent-browser opens the HTML wrapper in Playwright, sets a 4K viewport (3840×2160) with a minimum width of 1200px for the diagram, and captures a high-resolution PNG screenshot.

Clean up intermediate files

Removes the temporary HTML wrapper, keeping only diagram.svg e diagram.png in the working directory.

Actual dependencies

Beautiful Mermaid library — rendering core
scripts/render.ts — SVG rendering
scripts/create-html.ts — HTML wrapper
agent-browser — Playwright / 4K screenshot
bun / tsx / deno — TypeScript runtimes

Available themes

default — clear Mermaid convention
dark — dark by default
forest — green tones
neutral — no strong color
tokyo-night — modern dark neon
base — minimalist

⚠️

Common problems and solutions

Theme not applied: check --bg e --fg CSS in the output SVG
Cropped diagram: use -->|label| — never -- label -->
Empty/malformed SVG: check for unique node IDs and closed brackets in labels

Key Concepts

render.ts

rendering script

create-html.ts

screenshot wrapper

agent-browser

Playwright 4K

bun/tsx/deno

supported runtimes

💬 Practical example + Ready-to-use PROMPT

Two concrete scenarios: render existing code and generate from scratch based on a description.

Mermaid syntax — direct examples

Flowchart (process with decision)

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 (authentication flow)

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

💡

Golden rule for edge labels

Always use C -->|Sim| D with a pipe. Never C -- Sim --> D (spaces or dashes can cause incomplete rendering, according to SKILL.md).

📋 PROMPT 1 — Render existing code

Paste into 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 — Generate and render from scratch

Paste into 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 — Embed a diagram in an HTML page

Paste into 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.

Key Concepts

flowchart TD

top-down flow

sequenceDiagram

sequential interactions

-->|label|

safe edge label

--theme

theme parameter

🧬 Works well with / limitations

beautiful-mermaid fits into an ecosystem of visualization and support skills. Understanding where each tool starts and ends helps avoid poor choices.

📊 beautiful-mermaid vs ✏️ excalidraw

M beautiful-mermaid

→ Technical diagrams precise and structured
→ Declarative syntax — you define the logic, the library organizes the layout
→ Style polished, professional, curated themes
→ Exportable SVG + PNG for documentation
→ Ideal for: architecture, code flows, databases, CI/CD

E excalidraw (next module 4.2)

→ Diagrams "by hand", sketchy, exploratory
→ Hand-drawn style — communicates "work in progress"
→ Great for wireframes, initial architecture drafts
→ Interactive — you can edit it in the browser
→ Ideal for: UX wireframes, visual brainstorming, UI sketches

Rule of thumb: use Mermaid when you need technical precision and professional outputs. Use Excalidraw when a "polished" look might inhibit iteration — sketches show that the idea is still open.

Works with other course skills

🕹️

agent-browser (Module 4.3)

Direct dependency — agent-browser (Playwright) captures the 4K PNG in Step 4 of the workflow. Without it, the output is SVG only.

🔭

website-intelligence (Module 4.4)

Combine them: render architecture diagrams for sites analyzed by website-intelligence — layout architectures, navigation flows.

⚛️

frontend-design (Module 1.1)

Embed the SVG generated by beautiful-mermaid directly in React/Tailwind pages created by frontend-design — inline technical diagrams.

🏷️

brand-guidelines (Module 2.2)

Create brand architecture diagrams or visual identity flows, exporting SVG with the right colors for guideline presentations.

✓ USE when

✓ Need technical diagrams in documentation
✓ Want an embeddable SVG for HTML or a PNG for a slide
✓ The diagram has a clear logical structure (flow, sequence, state)
✓ Requires multiple visual themes

✗ DO NOT use when

✗ The diagram is a wireframe or conceptual sketch (→ excalidraw)
✗ Need interactive diagrams that can be edited in the browser
✗ The content is an animation or 3D diagram (→ 3d-animation-creator)
✗ Need full control over the visual layout of each element

Key Concepts

Mermaid = technical

precision and structure

Excalidraw = sketch

draft and wireframe

agent-browser

direct dependency

Embeddable SVG

integrates with T1/T2

📋 Module 4.1 Summary

What you learned

✓beautiful-mermaid renders Mermaid as SVG + PNG using the Beautiful Mermaid library
✓The trigger is a request from the user to render a Mermaid diagram — any type
✓The pipeline has 5 steps: validate → render.ts → create-html.ts → agent-browser (Playwright) → clean up
✓PNG is captured in 4K (3840×2160) with a minimum diagram width of 1200px
✓Always use -->|label| for edge labels — never space-hyphen
✓Mermaid = precise technical diagrams; Excalidraw = sketchy drafts and wireframes
✓The generated SVG can be embedded inline in HTML — the same technique as the SVGs in this course

Next module:

4.2 ✏️ excalidraw

The skill that generates Excalidraw-style "hand-drawn" diagrams—wireframes, architecture drafts, and UI sketches with an informal look that communicates "under construction".

Track 4 — Support

✓4.1 📊 beautiful-mermaid

→4.2 ✏️ excalidraw

○4.3 🕹️ agent-browser

○4.4 🔭 website-intelligence

← Back to Track 4 Next Module: 4.2 ✏️ excalidraw →