MÓDULO 4.1

📊 beautiful-mermaid

Renderiza diagramas Mermaid como SVG y PNG usando la biblioteca Beautiful Mermaid — con temas visuales variados, salida en alta resolución (4K) e integración con agent-browser para capturar una screenshot.

Temas

Minutos

Práctico

Nivel

Soporte

Categoría

🧩 Qué es / qué hace

Definición precisa

beautiful-mermaid es un skill de Claude Code que renderiza diagramas Mermaid como SVG y PNG usando la biblioteca Beautiful Mermaid. La operación es bidireccional: recibe código .mmd (o una descripción en lenguaje natural) y produce siempre ambos formatos — SVG vectorial y PNG en alta resolución (4K, viewport 3840×2160, ancho mínimo de 1200px del diagrama).

Flowchart

Flujos de proceso, árboles de decisión, pipelines CI/CD

Sequence

Llamadas a API, flujos OAuth, transacciones de bases de datos

State

Máquinas de estado, ciclos de vida de conexión

Clase (UML)

Diagramas de clases, patrones de diseño

Entity-Relationship

Esquemas de bases de datos, modelos de datos

Salida doble siempre

SVG + PNG generados en cada ejecución, sin excepción

Conceptos clave

Beautiful Mermaid

biblioteca de renderizado

SVG + PNG

siempre ambos formatos

render.ts

script principal

Salida en 4K

3840×2160 viewport

🎣 Cuándo se activa

El disparador oficial de la skill (campo description) se necesita:

📋

Disparador oficial (description)

"Renderiza diagramas Mermaid como SVG y PNG usando la biblioteca Beautiful Mermaid. Úsala cuando el usuario pida renderizar un diagrama Mermaid."

Situaciones que activan la skill

"Renderiza este diagrama Mermaid para mí"

Disparador más directo — código .mmd ya presente

"Genera un diagrama de flujo de mi proceso de autenticación"

Claude genera el código Mermaid y lo renderiza enseguida

"Convierte este archivo .mmd en una imagen"

Lee el archivo y ejecuta render.ts con --input

"Visualiza la arquitectura del sistema como una secuencia"

Genera un sequenceDiagram y produce SVG + PNG

"Quiero un diagrama ER de la base de datos"

Genera un erDiagram de Mermaid y lo renderiza

💡

La palabra clave es "Mermaid"

Si el usuario menciona "diagrama Mermaid", "código mermaid", "archivo .mmd" o pide explícitamente renderizar, Claude activa este skill. No es necesario citar "beautiful-mermaid": el detonante es el tipo de diagrama.

Conceptos clave

Render Mermaid

disparador principal

Generar + renderizar

Claude genera el código

--input .mmd

archivo existente

Cualquier tipo

flow / seq / state / ER

🚀 Cómo mejora tus páginas

Los diagramas técnicos elevan significativamente la calidad de las páginas de documentación, los cursos y los dashboards. beautiful-mermaid los crea con un solo comando.

✓ HACER con beautiful-mermaid

✓ Insertar SVG directamente en la página HTML (vectorial, sin pérdida de calidad)
✓ Usar PNG de alta resolución en presentaciones y diapositivas
✓ Documentar flujos de API con sequenceDiagram
✓ Visualizar la arquitectura de la base de datos con erDiagram
✓ Elegir el tema adecuado para el contexto (dark/light/tokyo-night)

✗ EVITAR al usar diagramas

✗ Usar `-- label -->` (espacio-guion) — prefiere `-->|label|`
✗ Reutilizar IDs de nodos — cada ID de nodo debe ser único
✗ Dejar corchetes abiertos en las etiquetas de los nodos
✗ Usar para diagramas que requieren interactividad compleja
✗ Insertar caracteres especiales sin comillas en las etiquetas

💡

SVG incrustado directamente en la página

El SVG generado por beautiful-mermaid se puede copiar e insertar directamente en el HTML de módulos como el que estás leyendo ahora. Es la misma técnica que se usa en los SVG futuristas de este curso: vectorial, ligero y sin dependencias externas.

📐

Escalabilidad infinita

SVG vectorial — sin pérdida de calidad con ningún nivel de zoom

🖼️

PNG 4K listo

Sin trabajo manual: captura automática mediante agent-browser

🎨

Temas visuales ricos

default, dark, forest, neutral, base, tokyo-night y más

Conceptos clave

SVG incrustable

integrado en el HTML

PNG 4K

presentaciones

Sintaxis limpia

pipe `-->|label|`

Temas variados

dark/light/tokyo-night

⚙️ Cómo funciona por dentro

5 pasos secuenciales, siempre en ese orden — del código Mermaid a los dos archivos finales.

Generar o validar código Mermaid

Si el usuario describe el diagrama en lenguaje natural, Claude genera código Mermaid válido consultando la referencia references/mermaid-syntax.md. Si el código ya existe, valida la sintaxis.

Renderizar SVG con render.ts

Ejecuta el script de renderización con bun, tsx o deno. Produce <output>.svg en el directorio actual.

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

Crear un wrapper HTML con create-html.ts

Prepara un archivo HTML mínimo con el SVG, el padding adecuado y el fondo: listo para una captura de pantalla.

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

Capturar PNG con agent-browser (Playwright)

El skill agent-browser abre el HTML wrapper en Playwright, configura el viewport 4K (3840×2160) con un ancho mínimo de 1200px en el diagrama y captura el screenshot en PNG de alta resolución.

Limpiar archivos intermedios

Elimina el wrapper HTML temporal, manteniendo solo diagram.svg e diagram.png en el directorio de trabajo.

Dependencias reales

Beautiful Mermaid library — núcleo de renderizado
scripts/render.ts — renderizado SVG
scripts/create-html.ts — wrapper HTML
agent-browser — Playwright / captura de pantalla en 4K
bun / tsx / deno — entornos de ejecución TypeScript

Temas disponibles

default — patrón Mermaid claro
dark — oscuro por defecto
forest — tonos verdes
neutral — sin colores intensos
tokyo-night — neón oscuro moderno
base — minimalista

⚠️

Problemas comunes y soluciones

Tema no aplicado: verifica --bg e --fg CSS en el SVG de salida
Diagrama cortado: usa -->|label| — nunca -- label -->
SVG vacío o malformado: verifica que los IDs de nodos sean únicos y que los corchetes de los labels estén cerrados

Conceptos clave

render.ts

script de renderizado

create-html.ts

wrapper screenshot

agent-browser

Playwright 4K

bun/tsx/deno

entornos de ejecución compatibles

💬 Ejemplo práctico + PROMPT listo

Dos escenarios concretos: renderizar código existente y generar desde cero a partir de una descripción.

Sintaxis de Mermaid: ejemplos directos

Flowchart (proceso con decisión)

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 (flujo de autenticación)

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

💡

Regla de oro para las etiquetas de arista

Siempre usa C -->|Sim| D con pipe. Nunca C -- Sim --> D (el espacio-trazo puede causar un renderizado incompleto, según el SKILL.md).

📋 PROMPT 1 — Renderizar código existente

Pégalo en 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 — Generar y renderizar desde cero

Pégalo en 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 — Incrustar un diagrama en una página HTML

Pégalo en 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.

Conceptos clave

flowchart TD

flujo top-down

sequenceDiagram

interacciones secuenciales

-->|label|

etiqueta de borde segura

--theme

parámetro de tema

🧬 Combina con / límites

beautiful-mermaid forma parte de un ecosistema de skills de visualización y apoyo. Entender dónde empieza y termina cada herramienta evita elegir mal.

📊 beautiful-mermaid vs ✏️ excalidraw

M beautiful-mermaid

→ Diagramas técnicos precisos y estructurados
→ Sintaxis declarativa — defines la lógica y la biblioteca organiza el diseño
→ Estilo pulido, profesional, temas seleccionados
→ SVG + PNG exportables para documentación
→ Ideal para: arquitectura, flujos de código, BD, CI/CD

E excalidraw (próximo módulo 4.2)

→ Diagramas "a mano", bosquejados, exploratorios
→ Estilo dibujado a mano — comunica "trabajo en progreso"
→ Ideal para wireframes y borradores de arquitectura inicial
→ Interactivo — puedes editarlo en el browser
→ Ideal para: wireframes de UX, lluvia de ideas visual, bocetos de UI

Regla práctica: usa Mermaid cuando necesites precisión técnica y outputs profesionales. Usa Excalidraw cuando el visual "polished" pueda inhibir la iteración: los bocetos indican que la idea sigue abierta.

Combina con otros skills del curso

🕹️

agent-browser (Módulo 4.3)

Dependencia directa — agent-browser (Playwright) es quien captura el PNG 4K en el Paso 4 del workflow. Sin él, la salida es solo SVG.

🔭

website-intelligence (Módulo 4.4)

Combina: renderiza diagramas de arquitectura de sitios analizados por website-intelligence — arquitecturas de diseño, flujos de navegación.

⚛️

frontend-design (Módulo 1.1)

Insertar el SVG generado por beautiful-mermaid directamente en páginas React/Tailwind creadas por frontend-design: diagramas técnicos inline.

🏷️

brand-guidelines (Módulo 2.2)

Crea diagramas de arquitectura de marca o flujos de identidad visual y exporta SVG con los colores adecuados para presentaciones de lineamientos.

✓ USA cuando

✓ Necesitas diagramas técnicos en la documentación
✓ Quieres un SVG que puedas insertar en HTML o un PNG para una diapositiva
✓ El diagrama tiene una estructura lógica clara (flujo, secuencia, estado)
✓ Necesita múltiples temas visuales

✗ NO USE cuando

✗ El diagrama es un wireframe o un borrador conceptual (→ excalidraw)
✗ Necesitas diagramas interactivos editables en el browser
✗ El contenido es una animación o un diagrama 3D (→ 3d-animation-creator)
✗ Necesitas control total del diseño visual de cada elemento

Conceptos clave

Mermaid = técnico

precisión y estructura

Excalidraw = sketch

borrador y wireframe

agent-browser

dependencia directa

SVG incrustable

se integra con T1/T2

📋 Resumen del Módulo 4.1

Qué aprendiste

✓beautiful-mermaid renderiza Mermaid como SVG + PNG usando la biblioteca Beautiful Mermaid
✓El disparador es que el usuario pida renderizar un diagrama Mermaid, de cualquier tipo
✓El pipeline tiene 5 pasos: validar → render.ts → create-html.ts → agent-browser (Playwright) → limpiar
✓El PNG se captura en 4K (3840×2160), con un ancho mínimo de 1200px en el diagrama
✓Usa siempre -->|label| para etiquetas de arista —nunca espacio y guion
✓Mermaid = diagramas técnicos precisos; Excalidraw = bocetos sketchy y wireframes
✓El SVG generado se puede insertar en línea en HTML: la misma técnica de los SVG de este curso

Próximo módulo:

4.2 ✏️ excalidraw

El skill que genera diagramas al estilo "a mano" de Excalidraw: wireframes, borradores de arquitectura y bocetos de UI con un aspecto informal que comunica "en construcción".

Ruta 4 — Apoyo

✓4.1 📊 beautiful-mermaid

→4.2 ✏️ excalidraw

○4.3 🕹️ agent-browser

○4.4 🔭 website-intelligence

← Volver a la ruta 4 Próximo módulo: 4.2 ✏️ excalidraw →