Beautiful Mermaid: diagrammi belli davvero, anche dal terminale

Se hai mai usato Mermaid sai due cose: è comodissimo per creare diagrammi scrivendo solo testo, e il risultato visivo è... discutibile.

Colori piatti, font generici, nodi che sembrano usciti da un PowerPoint del 2003. Funziona, ma non è qualcosa che mostreresti volentieri a un cliente.

Beautiful Mermaid risolve esattamente questo problema.

Cos'è

Una libreria TypeScript che prende la stessa sintassi Mermaid che già conosci e la trasforma in qualcosa di diverso:

• SVG tematizzati con colori derivati automaticamente da una palette
• ASCII art per il terminale, utile in contesti CLI o AI agent
• Zero dipendenze DOM — gira ovunque, non serve un browser

Sviluppata da Luki Labs (il team dietro Craft), è pensata per integrarsi in tool AI e ambienti dove serve generare diagrammi al volo.

15 temi pronti, oppure il tuo

Il sistema di theming è la parte più interessante. Non devi combattere con CSS o sovrascrivere classi. Dai due colori — background e foreground — e la libreria fa il resto:

import { renderMermaid, THEMES } from 'beautiful-mermaid'

// Usa un tema predefinito
const svg = await renderMermaid('graph TD; A-->B-->C', THEMES['tokyo-night'])

// Oppure crea il tuo con due colori
const svg = await renderMermaid('graph TD; A-->B-->C', {
  bg: '#0f0f0f',
  fg: '#e0e0e0'
})

I 15 temi inclusi coprono i classici: Tokyo Night, Catppuccin, Nord, Dracula, GitHub, Solarized, One Dark, e altri. Se usi Shiki per la syntax highlighting, puoi estrarre il tema direttamente da lì:

import { fromShikiTheme } from 'beautiful-mermaid'
import { getSingletonHighlighter } from 'shiki'

const highlighter = await getSingletonHighlighter({ themes: ['vitesse-dark'] })
const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark'))

Il meccanismo sotto è elegante: usa color-mix() in CSS per derivare colori secondari (linee, accenti, bordi, superfici) dai due colori base. Il risultato è sempre coerente, senza bisogno di specificare 10 variabili.

Diagrammi nel terminale

Questa è la feature che lo distingue davvero. Beautiful Mermaid può renderizzare i diagrammi come testo, usando caratteri Unicode box-drawing o ASCII puro:

import { renderMermaidAscii } from 'beautiful-mermaid'

const output = renderMermaidAscii('graph LR; A-->B-->C')
console.log(output)

Risultato:

┌───┐     ┌───┐     ┌───┐
│ A │────>│ B │────>│ C │
└───┘     └───┘     └───┘

Questo è fondamentale per chi lavora con agenti AI o tool da terminale. Se stai costruendo un agent che deve ragionare su architetture, pipeline o flussi di dati, poter generare un diagramma leggibile direttamente nella risposta testuale è un vantaggio enorme.

Cinque tipi di diagramma

Non supporta tutta la sintassi Mermaid (che è sterminata), ma copre i cinque tipi più usati:

Per il 90% dei casi d'uso reali — documentazione tecnica, design di sistema, onboarding — questi bastano.

Come si installa

npm install beautiful-mermaid
# oppure
bun add beautiful-mermaid

Oppure direttamente da CDN:

<script type="module">
  import { renderMermaid } from 'https://cdn.jsdelivr.net/npm/beautiful-mermaid/+esm'
</script>

Un esempio concreto

Immagina di voler documentare un flusso di autenticazione. Con Mermaid standard scrivi:

graph TD
    A[Utente] -->|Login| B[API Gateway]
    B --> C{Token valido?}
    C -->|Sì| D[Dashboard]
    C -->|No| E[Errore 401]
    E --> A

Con il renderer standard ottieni un diagramma funzionale ma anonimo. Con Beautiful Mermaid:

import { renderMermaid, THEMES } from 'beautiful-mermaid'

const diagram = `graph TD
    A[Utente] -->|Login| B[API Gateway]
    B --> C{Token valido?}
    C -->|Sì| D[Dashboard]
    C -->|No| E[Errore 401]
    E --> A`

const svg = await renderMermaid(diagram, THEMES['dracula'])
document.getElementById('diagram').innerHTML = svg

Stesso input, output completamente diverso. Colori coerenti, nodi con bordi puliti, font leggibile.

Perché è interessante

Beautiful Mermaid non reinventa Mermaid. Prende un formato che è già diventato uno standard de facto nella documentazione tecnica e lo rende presentabile.

Il fatto che funzioni senza DOM lo rende adatto a contesti server-side, CLI, e soprattutto a sistemi AI che generano documentazione o ragionano su architetture. Il rendering ASCII è qualcosa che mancava nell'ecosistema — e che diventa sempre più rilevante man mano che gli agent AI lavorano in contesti testuali.

Con 6.7k stelle su GitHub in poco tempo, il progetto ha chiaramente toccato un nervo scoperto. A volte la differenza tra uno strumento che usi e uno che ami è solo questione di estetica.

Repo: github.com/lukilabs/beautiful-mermaid — MIT License