Ich benutze Mermaid ständig — Flussdiagramme in Design-Dokumenten, Sequenzdiagramme in READMEs, ab und zu ein ER-Diagramm. Diagramme als Code sind eine feine Sache: versionierbar, vergleichbar, kein Herumschieben von Kästchen. Was nie fein war, ist, wie das Ergebnis aussieht.
Die eingebauten Themes sind funktional, aber die Farben wirken veraltet. Mermaid hat durchaus ein richtiges Theme-System: theme: 'base' setzen und in themeVariables überschreiben, was man will. Das Problem ist der Arbeitsablauf: einen Frontmatter-Block bearbeiten, neu rendern, das Ergebnis anblinzeln, raten, welche der 70-und-ein-paar Variablen das bemalt, was einen stört, wiederholen.
Der Tropfen, der das Fass zum Überlaufen brachte, war ein Sequenzdiagramm. Ich änderte primaryColor — und die Actor-Boxen änderten ihre Farbe gleich mit. Stellt sich heraus, die gehören zu actorBkg. Zehn Minuten pro Farbe, das meiste davon Raten, weil der Name einer Variablen einem fast nichts darüber verrät, was sie bemalt.
Was ich wollte, war einfach: eine Variable verstellen und sehen, was sie tut. Sofort.
Also habe ich mermaid.design gebaut — Mermaid-Code links, eine Live-Vorschau in der Mitte und das gesamte Theme-System rechts editierbar. Jede Änderung rendert das Diagramm an Ort und Stelle neu. Die Feedbackschleife schrumpfte von Minuten auf Sekunden.
Das ist die Schaufensterseite. Hier sind die Module, die wirklich Zeit sparen.
Die Galerie: alle Diagrammtypen auf einen Blick
Das Nervige an Theme-Variablen ist, dass sich dieselbe Variable je nach Diagrammtyp unterschiedlich verhält. Die Galerie-Seite rendert alle 84 Templates — Flussdiagramme, Sequenz-, Klassen-, Zustands-, ER-Diagramme und mehr — live mit deinem aktuellen Theme. Variable ändern, durch die Galerie scrollen, und der Effekt auf jeden Diagrammtyp liegt direkt vor dir. Kein Hin- und Herschalten zwischen Diagrammtypen mehr. Genau das ist die gesparte Zeit.
Theme-Variablen: Standardwerte und Vererbung offengelegt
Jede der 73 Variablen zeigt ihren Standardwert aus dem Mermaid-Basethema. Variablen, die du nicht gesetzt hast, bekommen ein AUTO-Badge mit dem Wert, den mermaid zur Renderzeit ableitet — und woher dieser Wert kommt:
mainBkgfolgtprimaryColorprimaryBorderColorist eine ausprimaryColorberechnete RahmenfarbesecondaryTextColorist die Umkehrung vonsecondaryColor(für Kontrast)actorBkgfolgtmainBkg— das erklärt die Falle von vorhin: Das Ändern vonprimaryColorverschob meine Actor-Boxen, weil es eine VererbungsketteprimaryColor→mainBkg→actorBkggibt
Wer die Kette sieht, hört auf zu raten.
Presets: offiziell, Designer — und es werden mehr
21 Presets, ein Klick zum Anwenden: die 11 offiziellen Mermaid-Themes (default, neutral, dark, forest, base, plus die redux- und neo-Familien aus v12) und 10 Designer-Presets, die ich von Hand abgestimmt habe. Jedes zeigt eine Live-Mini-Vorschau — und die Sammlung wächst weiter.
Generierung: eine Primärfarbe, eine ganze Palette
Eine einzige primäre Seed-Farbe wählen, und der Generator rampt im HSL-Raum die Helligkeit um ihren Farbton — eine 8-stufige Skala — und leitet eine komplette Palette ab, Dark-Mode-Variante inklusive. Der schnellste Weg, ein Diagramm an die eigene Marke anzupassen.
Render-Config: jenseits der Farben
Farben sind nur die Hälfte. Mermaid hat 438 render-relevante Config-Felder, nach Diagrammtyp in 34 Gruppen sortiert. Ein paar Beispiele:
- Global:
fontFamily,fontSize,wrap(automatischer Textumbruch),look(classic oder handDrawn im Handzeichenstil) - Flussdiagramme:
flowchart.curve(Kurvenstil der Kanten),flowchart.nodeSpacing/flowchart.rankSpacing,flowchart.diagramPadding - Sequenzdiagramme:
sequence.actorMargin,sequence.messageMargin,sequence.showSequenceNumbers(Nachrichtennummerierung),sequence.mirrorActors - Kreisdiagramme:
pie.textPosition,pie.donutHole,pie.legendPosition
Die Gruppe, die zum aktuellen Diagrammtyp passt, öffnet sich automatisch.
ASCII-Modus: das Diagramm als Text
Dasselbe Diagramm lässt sich als ASCII-Art rendern — ein Klick zum Kopieren, fertig für Code-Kommentare, Commit-Messages oder Klartext-Dokumente. Aktuell werden fünf Diagrammtypen unterstützt: Flussdiagramme, Sequenz-, Klassen-, Zustands- und ER-Diagramme. Der Zeichensatz kann Unicode-Box-Drawing oder reines ASCII sein.
Fazit
Die Motivation hinter mermaid.design ist einfach: Die offiziellen Theme-Farben sind schwer zu mögen, das manuelle Tuning der themeVariables ist langsam, und ich wollte einen Ort, an dem jede Änderung sofort ihre Wirkung zeigt. Heute gibt es dort live editierbare Theme-Variablen mit sichtbaren Standardwerten und Vererbung, eine Galerie, die alle Diagrammtypen auf einmal zeigt, offizielle und Designer-Presets, einen Generator, der aus einer Primärfarbe eine ganze Palette ableitet, 438 Render-Config-Felder und einen ASCII-Modus, der Diagramme in Text verwandelt.
Wenn du dich auch mit Mermaid-Themes herumschlägst, probier es aus.