IbrahimSobh/content-mermaid

Content Mermaid

Erzeugt Mermaid-Diagramme für technische Prozesse und Strukturen. Dies ist das schnelle, syntaxgesteuerte Gegenstück zu content-diagrams: gleiche visuelle Klarheitsstandards, aber basierend auf einer Sprache, die bereits korrekte Geometrie garantiert. Der Aufwand fließt daher in die Auswahl des richtigen Diagrammtyps und eines lesbaren, konsistenten Farbsystems, anstatt in das Überprüfen von Koordinaten.

Beziehung zu content-diagrams

Beide Fähigkeiten teilen dieselben Standards – lesbarer Text, ein echtes Farbsystem statt Dekoration, Klarheit vor Informationsdichte – aber content-diagrams berechnet seine SVG-Geometrie von Hand, während dieser Skill die Geometrie vollständig der Mermaid-Layout-Engine überlässt. Wählen Sie zwischen ihnen basierend darauf, wo das Diagramm tatsächlich betrachtet wird (native Mermaid-Oberfläche vs. eine Plattform, die nur statische Bilder anzeigt), nicht aus Gewohnheit. Wenn Sie sich unsicher sind, fragen Sie – Mermaid-Quellcode lässt sich ohne echten Arbeitsaufwand nicht sauber in eine eigenständige Grafik exportieren.

Warum es hier keine Verifikationsschleife gibt

content-diagrams verwendet den Großteil seiner Rechenleistung für Geometrie: Eine SVG-Linie, -Box oder -Beschriftung besteht aus Zahlen, die Claude berechnet hat, und berechnete Zahlen können falsch sein – daher: rendern, screenshoten, zuschneiden und prüfen.

Mermaid eliminiert diese Fehlerquelle vollständig. Knotenbreite, Textumbruch, Pfeilpfade und Kollisionsvermeidung zwischen Elementen sind Aufgabe des Renderers, nicht von Claude – der Renderer platziert keine Beschriftung auf einer Box und führt keine Linie durch eine Form. Diese Verifikationsschleife hier neu zu implementieren (Screenshot des gerenderten Diagramms, Zuschneiden, Überlappungsprüfung) würde nur Tokens und Latenz verschwenden, um etwas zu bestätigen, das das Tool bereits garantiert.

Was schiefgehen kann, ist völlig anders und rein textuell:

• Fehlerhafte Syntax (nicht geschlossene Klammern, ein reserviertes Wort als Knoten-ID, nicht passende Pfeiltypen)
• Eine Kante, die auf eine nie definierte Knoten-ID verweist
• Schlechter Farbkontrast (eine Füll- und Textfarbe, die nicht lesbar gegeneinander sind)
• Der falsche Diagrammtyp für die tatsächliche Struktur des Inhalts

Verifikation bedeutet hier also: die Syntax einmal auf Korrektheit lesen, jedes classDef auf eine Füllung mit einer wirklich kontrastierenden Textfarbe prüfen und bestätigen, dass der Diagrammtyp zum modellierten Inhalt passt. Kein Rendern von Bildern erforderlich.

Diagrammtypauswahl

Wählen Sie den Typ basierend auf der inhaltlichen Struktur – dies ist das Mermaid-Äquivalent zur Motivauswahl von content-diagrams:

Inhaltsstruktur	Mermaid-Typ
Sequenzielle Schritte mit Verzweigungen/Schleifen (ein Prozess, ein Workflow, ein Algorithmus)	flowchart TD (top-down) oder LR (links-rechts für Pipelines/Zeitlinien)
Zeitlich geordnete Nachrichten zwischen Akteuren/Diensten (API-Aufrufe, Protokollaustausche)	sequenceDiagram
Die Zustände einer Entität und die Übergänge zwischen ihnen (ein Lebenszyklus, eine Zustandsmaschine)	stateDiagram-v2
Datenmodell / Entitätsbeziehungen (Schemata, DB-Tabellen)	erDiagram
Objektorientierte Struktur (Klassen, Vererbung, Schnittstellen)	classDiagram
Zeitplan mit Dauern und Abhängigkeiten	gantt
Hierarchische Aufteilung / Brainstorming ohne strenge Sequenz	mindmap
Chronologischer Erzählstrang (Projektverlauf, Versionsgeschichte)	timeline
Zweiachsige Priorisierung (Aufwand vs. Nutzen usw.)	quadrantChart

Standardmäßig nicht alles als flowchart darstellen – eine Anfrage wie "Diagramm, wie unsere Dienste sich gegenseitig aufrufen" ist ein sequenceDiagram, auch wenn es verlockend ist, es als Boxen und Pfeile zu zeichnen; eine Anfrage wie "zeige die Zustände, die ein Ticket durchläuft" ist stateDiagram-v2, kein Flussdiagramm mit Rauten als Platzhalter für Zustände.

Farb- und Lesbarkeitssystem

Dies ist der einzige Punkt, an dem manuelle Prüfung noch wichtig ist, da Mermaid unleserliche Farbkombinationen ohne Beanstandung rendert.

Die Regel: Jedes classDef muss eine Füllfarbe mit einer Textfarbe kombinieren, die bewusst für Kontrast ausgewählt wurde – verlassen Sie sich niemals darauf, dass die color-Eigenschaft nicht gesetzt ist und die Standardeinstellung des Themes funktioniert. Mermaids eigene Standardpalette (sanftes Grün/Rosa/Blau mit schwarzem Text) ist in Ordnung, eben weil Füllung und Text zusammen ausgewählt wurden; sobald Sie fill durch eine kräftigere oder dunklere Farbe überschreiben, müssen Sie auch color explizit setzen, sonst reproduzieren Sie einen häufigen Fehler: lesbar aussehende Boxen mit Text, der tatsächlich geringen Kontrast zur Füllung aufweist.

Zwei Palettenrezepte, wählen Sie eines aus und verwenden Sie es durchgängig für jede Klasse in einem Diagramm (nicht mischen):

1. Dunkle Füllung / weißer Text (die Standardvariante – bewährt, hoher Kontrast, sowohl in hellen als auch dunklen Chat-Designs gut lesbar):

   classDef category1 fill:#1e3a5f,stroke:#0d1f33,stroke-width:2px,color:#ffffff
   

2. Helle Tönung / dunkler Text / kräftiger Strich (zu verwenden, wenn ein Diagramm visuell neben einem content-diagrams-SVG platziert werden soll, das dessen helle Tönungskonvention verwendet):

   classDef category1 fill:#e1f0ff,stroke:#1e3a5f,stroke-width:2px,color:#1a1a1a
   

Direkt übernommen von der content-diagrams-Regel: Ein Farbton pro Kategorie, der überall dort angewendet wird, wo diese Kategorie vorkommt – dieselbe Farbe in Füllung/Strich auf jedem Knoten dieser Rolle, nicht nur einmalig. Weisen Sie Farbtöne nach Rolle zu, z. B.:

• Blau → Eingaben / Daten / Rückstandselemente
• Grün → Prozess / aktive Arbeitsschritte
• Bernstein oder Braun → Entscheidungspunkte / Tore
• Lila → Ausgaben / Veröffentlichungen / Endzustände
• Rot → Rückkopplungsschleifen / Fehlerpfade / Retrospektiven

Sperren Sie die Leinwand, sodass sie nicht vom hellen/dunklen Modus des Hosts abhängt. Setzen Sie eine Init-Direktive als allererste Zeile des Diagramms:

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif', 'fontSize': '16px', 'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0d1f33', 'lineColor': '#666666', 'background': '#ffffff' } } }%%

theme: 'base' plus explizite themeVariables bedeutet, dass das Diagramm unabhängig davon gleich aussieht, auf welches Mermaid-Theme die Host-Umgebung standardmäßig zurückfällt – verlassen Sie sich nicht allein auf den Standard-Themenamen (default, dark, forest usw.), da dies die tatsächlichen Farben dem Renderer überlässt.

Schriftgröße: Mindestens 16px für jedes Diagramm mit mehr als einer Handvoll Knoten; 14px nur, wenn das Diagramm einfach genug ist, dass die Lesbarkeit nicht infrage steht. Wenn ein Diagramm unter 14px schrumpfen müsste, um seine Beschriftungen unterzubringen, ist das dasselbe Signal "Klarheit vor Informationsdichte" aus content-diagrams – teilen Sie das Diagramm auf oder reduzieren Sie den Inhalt, verkleinern Sie den Text nicht weiter.

Gestaltungsreichweite variiert nach Diagrammtyp: flowchart, stateDiagram-v2 und classDiagram unterstützen alle die direkte classDef/class-Zuweisung pro Knoten, verwenden Sie also das Kategorie-Farbsystem oben Knoten für Knoten. sequenceDiagram, erDiagram und gantt haben eine viel eingeschränktere Gestaltung pro Element – setzen Sie hier den Aufwand in die themeVariables im Init-Block (actorBkg, actorTextColor, noteBkgColor usw. für Sequenzdiagramme), anstatt zu erwarten, dass Klassen auf Knotenebene auf dieselbe Weise funktionieren.

Pfeilgrammatik

Im Gegensatz zu handcodiertem SVG rendert Mermaid Pfeilbeschriftungen sauber mit automatischer Platzierung – -->|label| Text landet nicht riskant auf einer Form, wie es eine manuell positionierte SVG-Beschriftung tun würde. Daher ist die direkte Beschriftung von Pfeilen in Ordnung und oft klarer als die "Text von Pfeilen fernhalten, über Legende kodieren"-Voreinstellung von content-diagrams. Halten Sie Beschriftungen dennoch kurz ("genehmigt", "wiederholen", "bei Fehler") statt als Phrasen – eine Beschriftung ist ein Tag, kein Satz.

Reservieren Sie die Linienart für dieselbe breite Unterscheidung, die content-diagrams verwendet:

• Durchgezogener Pfeil (-->) → primärer/normaler Fluss
• Gestrichelter Pfeil (-.->) → Rückkopplung, ein optionaler Pfad oder eine externe/indirekte Interaktion
• Dicker Pfeil (==>) → ein hervorgehobener oder kritischer Pfad, sparsam verwendet

Halten Sie Beschriftungen kurz; verwenden Sie Subgraphs zur Gruppierung

Knotentext sollte eine kurze Phrase sein, kein Satz – Mermaid wird bei absatzlangen Beschriftungen genau wie jedes andere Tool umbrechen oder überlaufen lassen. Wenn ein Knoten mehrere Zeilen benötigt, fügen Sie sie explizit mit <br/> innerhalb der Beschriftung ein, anstatt darauf zu vertrauen, dass der automatische Umbruch an einer sinnvollen Stelle trennt.

Verwenden Sie subgraph, um zusammengehörige Schritte zu gruppieren (z. B. alles innerhalb eines Sprints, einer Bereitstellungsstufe, einer Dienstgrenze) – es ist das Mermaid-Äquivalent zu einem Gruppierungsrahmen und kann mit einer eigenen style SubgraphName fill:...,stroke:...-Zeile gestaltet werden. Verschachteln Sie Subgraphs nicht tiefer als eine Ebene; es wird schnell unleserlich.

Workflow

1. Identifizieren Sie die zugrunde liegende Struktur und wählen Sie den Diagrammtyp aus der obigen Tabelle, bevor Sie Syntax schreiben.
2. Weisen Sie Kategoriefarben den vorhandenen Rollen zu (Eingaben, Prozessschritte, Entscheidungen, Ausgaben, Rückkopplungen) – skizzieren Sie dies in ein oder zwei Sätzen, bevor Sie classDefs schreiben, derselbe Schritt wie "die Begründung des Motivs skizzieren" bei content-diagrams, damit die Wahl nachvollziehbar ist, falls der Benutzer eine Anpassung wünscht.
3. Schreiben Sie das Diagramm, beginnend mit der %%{init: ...}%%-Direktive, dann die Struktur, dann classDef/class-Zuweisungen (oder themeVariables für Typen, die keine Klassen pro Knoten unterstützen).
4. Überprüfen Sie die Syntax selbst – jede Knoten-ID, die in einer Kante verwendet wird, ist irgendwo definiert; jedes classDef hat sowohl fill als auch color gesetzt; Klammern/Anführungszeichen sind ausgeglichen; keine absatzlangen Beschriftungen. Kein Rendern, kein Screenshot.
5. Speichern Sie als .mermaid-Datei über create_file, damit es als Artefakt inline gerendert wird, mit einem beschreibenden Slug: /mnt/user-data/outputs/<slug>.mermaid. Präsentieren Sie es mit present_files.
6. Wenn der Benutzer das Diagramm als portables statisches Bild benötigt (zur Einbettung an einem Ort, der Mermaid nicht rendert, oder zur Archivierung), sagen Sie dies klar: Diese Umgebung führt keine zuverlässige Headless-Mermaid-zu-Bild-Exporte durch (abhängig von einem Chromium-Download, den das sandboxierte Netzwerk normalerweise nicht erreichen kann). Verweisen Sie für einen manuellen Export auf mermaid.live oder wechseln Sie zu content-diagrams, wenn die tatsächliche Anforderung eine eigenständige Grafik ist.

Was zu vermeiden ist

• Lassen Sie bei einem classDef die color-Eigenschaft nicht ungesetzt, nachdem Sie fill überschrieben haben – das ist genau der Kontrastfehler, den dieser Skill vermeiden soll.
• Mischen Sie nicht die Rezepte für dunkle Füllung und helle Füllung innerhalb eines Diagramms.
• Standardmäßig nicht jede Anfrage als flowchart behandeln – wählen Sie den Typ, der der tatsächlichen Struktur entspricht (Sequenz, Zustand, ER usw.).
• Führen Sie nicht den render/crop/verify-Zyklus von content-diagrams wieder ein – dieser löst ein Problem, das Mermaids Layout-Engine nicht hat.
• Setzen Sie keinen absatzlangen Text in eine Knotenbeschriftung; verwenden Sie <br/> oder kürzen Sie den Inhalt.
• Verschachteln Sie Subgraphs nicht tiefer als eine Ebene.
• Versprechen Sie keinen sauberen PNG/SVG-Export aus dieser Sandbox, ohne darauf hinzuweisen, dass Headless-Mermaid-Rendering hier möglicherweise nicht funktioniert.