Uso mucho Mermaid: diagramas de flujo en documentos de diseño, diagramas de secuencia en los README, algún que otro diagrama ER. Los diagramas como código son muy prácticos: versionables, comparables, sin arrastrar cajas por el lienzo. Lo que nunca fue práctico es cómo luce el resultado.
Los temas integrados son funcionales, pero los colores se sienten anticuados. Mermaid sí tiene un sistema de temas de verdad: defines theme: 'base' y sobrescribes lo que quieras en themeVariables. El problema es el flujo de trabajo: editar un bloque de frontmatter, volver a renderizar, entrecerrar los ojos ante el resultado, adivinar cuál de las más de 70 variables pinta lo que te molesta y repetir.
Mi punto de quiebre fue un diagrama de secuencia. Cambié primaryColor y las cajas de actores cambiaron de color con él — resulta que esas dependen de actorBkg. Diez minutos por color, la mayor parte adivinando, porque el nombre de una variable casi no te dice qué pinta.
Lo que yo quería era simple: ajustar una variable y ver qué hace. Al instante.
Así que construí mermaid.design — código Mermaid a la izquierda, vista previa en vivo en el centro y todo el sistema de temas editable a la derecha. Cada cambio vuelve a renderizar el diagrama ahí mismo. El ciclo de retroalimentación pasó de minutos a segundos.
Ese es el escaparate. Aquí están los módulos que de verdad ahorran tiempo.
La galería: todos los tipos de diagrama de un vistazo
Lo molesto de las variables de tema es que una misma variable se comporta distinto según el tipo de diagrama. La página de la galería renderiza las 84 plantillas — diagramas de flujo, secuencia, clases, estados, ER y más — en vivo con tu tema actual. Cambia una variable, recorre la galería y el efecto sobre cada tipo de diagrama está ahí, a la vista. Se acabó el ir y venir entre tipos de diagrama para comprobar. Ese es el tiempo que ahorra.
Variables de tema: valores por defecto y herencia a la vista
Cada una de las 73 variables muestra su valor por defecto del tema base de mermaid. Las que no has definido llevan una insignia AUTO con el valor que mermaid deriva al renderizar — y de dónde sale ese valor:
mainBkgsigue aprimaryColorprimaryBorderColores un color de borde calculado a partir deprimaryColorsecondaryTextColores el inverso desecondaryColor(para contraste)actorBkgsigue amainBkg— lo que explica la trampa de antes: cambiarprimaryColormovió mis cajas de actores porque existe una cadena de herenciaprimaryColor→mainBkg→actorBkg
Cuando ves la cadena, recolorear deja de ser una adivinanza.
Ajustes preestablecidos: oficiales, de diseñador y más en camino
21 ajustes, un clic para aplicar: los 11 temas oficiales de mermaid (default, neutral, dark, forest, base, más las familias redux y neo de la v12) y 10 ajustes de diseñador que afiné a mano. Cada uno muestra una mini vista previa en vivo — y la colección sigue creciendo.
Generación: un color primario, toda una paleta
Elige un único color primario semilla y el generador rampa la luminosidad en el espacio HSL alrededor de su tono — una escala de 8 pasos — para derivar una paleta completa, variante oscura incluida. La forma más rápida de que un diagrama combine con tu marca.
Configuración de renderizado: más allá de los colores
Los colores son solo la mitad. Mermaid tiene 438 campos de configuración que afectan al renderizado, agrupados por tipo de diagrama en 34 grupos. Algunos ejemplos:
- Global:
fontFamily,fontSize,wrap(ajuste de texto automático),look(classic o handDrawn, estilo dibujado a mano) - Diagramas de flujo:
flowchart.curve(estilo de las curvas),flowchart.nodeSpacing/flowchart.rankSpacing,flowchart.diagramPadding - Secuencia:
sequence.actorMargin,sequence.messageMargin,sequence.showSequenceNumbers(numeración de mensajes),sequence.mirrorActors - Tarta:
pie.textPosition,pie.donutHole,pie.legendPosition
El grupo que corresponde a tu tipo de diagrama actual se abre automáticamente.
Modo ASCII: el diagrama como texto
El mismo diagrama puede renderizarse como arte ASCII: un clic para copiar y listo para comentarios de código, mensajes de commit o documentos de texto plano. Actualmente admite cinco tipos de diagrama: flujo, secuencia, clases, estados y ER. El juego de caracteres puede ser box-drawing Unicode o ASCII puro.
En resumen
La motivación detrás de mermaid.design es simple: los colores oficiales de los temas son difíciles de querer, ajustar themeVariables a mano es lento, y quería un lugar donde cada cambio mostrara su efecto al instante. Hoy tiene variables de tema editables en vivo con valores por defecto y herencia visibles, una galería que muestra todos los tipos de diagrama a la vez, ajustes preestablecidos oficiales y de diseñador, un generador que saca toda una paleta de un solo color primario, 438 campos de configuración de renderizado y un modo ASCII que convierte los diagramas en texto.
Si tú también luchas con los temas de Mermaid, pruébalo.