D2-Diagramme
Schreibe D2-Quellcode, rendere ihn in SVG, schau dir dann das Rendering an und korrigiere, was du siehst – in einer Schleife, bis das Diagramm versandfertig ist. Ein Diagramm, das du nicht gesehen hast, ist ein Diagramm, das du nicht fertiggestellt hast.
Referenzdateien – bei Bedarf laden
| Datei | Wann lesen |
|---|---|
references/d2-language.md | Beim Schreiben eines nicht-trivialen D2 – Syntax, Shapes, Container, Klassen, Variablen und die stillen Fallstricke, die fehlerfrei kompilieren, aber falsch rendern |
references/layout-engines.md | Bei der Auswahl oder Fehlersuche des Layouts: TALA vs. ELK vs. dagre, Lizenzierung, Seeds, enginespezifische Verhaltensunterschiede |
references/diagram-patterns.md | Bei der Auswahl eines Diagrammtyps und seiner Struktur – Architektur, Sequenz, ERD, Grid, C4; Themes, Icons, Dark Mode, GitHub-Einbettung |
Schritt 0 – Toolchain-Prüfung
Einmal pro Sitzung vor dem ersten Rendern ausführen (scripts/ bezieht sich hier auf das eigene Verzeichnis dieser Fertigkeit – in Claude Code wird ${CLAUDE_SKILL_DIR} darauf aufgelöst):
bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
d2: ok→ fortfahren.d2: MISSING→ den Benutzer informieren, dannscripts/setup.sh(ohne Flags) ausführen, um via Homebrew zu installieren, wo verfügbar, oder die angezeigten Installationsbefehle anzuzeigen. Nicht blind rendern – nichts anderes in dieser Fertigkeit funktioniert ohne d2.tala: not installedoderunlicensed→ in Ordnung. ELK ist der automatische Fallback und erzeugt gute Layouts. TALA nur einmal erwähnen, wenn das Diagramm ein Software-Architekturdiagramm ist (wo TALA deutlich besser ist) und der Benutzer sich für die Ausgabequalität zu interessieren scheint; niemals nörgeln.
Schritt 1 – Planen vor dem Schreiben
Zuerst drei Dinge entscheiden:
- Die Botschaft. Was soll ein Leser in fünf Sekunden erkennen? Ein Diagramm argumentiert etwas – „Anfragen verteilen sich hier", „dieser Dienst ist der Engpass", „diese beiden Pfade berühren sich nie". Wenn du das Argument nicht formulieren kannst, wirst du gleich eine Sammlung beschrifteter Kästen zeichnen.
- Der Typ. Architektur/Topologie → einfache Shapes und Container. Interaktion über Zeit →
sequence_diagram. Datenmodell →sql_table. Strenge Ausrichtung (Matrix, Dashboard, legendenlastig) → Grid. Siehereferences/diagram-patterns.mdfür Strukturhinweise pro Typ. - Der Maßstab. 5–15 Knoten lesen sich gut; 15–25 benötigen Container zur Gruppierung; jenseits von ~25 in mehrere Diagramme aufteilen oder
layersverwenden. Ein zweites Diagramm ist einer Wandmalerei vorzuziehen.
Verwende bei technischen Diagrammen realer Systeme echte Namen – tatsächliche Dienstnamen, tatsächliche Tabellennamen, tatsächliche Ereignisnamen aus der Codebasis oder Beschreibung des Benutzers. Durchsuche den Code, wenn verfügbar. Service A -> Service B verschwendet das Vertrauen des Lesers.
Schritt 2 – D2 schreiben
Lies references/d2-language.md, bevor du etwas über ein triviales Diagramm hinaus schreibst. Die Regeln, die 90% defekter Ausgaben verhindern:
- Keys verbinden, nicht Labels. Nach
api: API Gatewayschreibeapi -> db, niemalsAPI Gateway -> db– Letzteres erzeugt still einen doppelten Shape. - Labels mit
#oder;in Anführungszeichen setzen – nicht in Anführungszeichen gesetztes#startet einen Kommentar mitten im Label und nicht in Anführungszeichen gesetztes;teilt die Zeile in zwei Shapes, beide kompilieren fehlerfrei. Jedes Label mit Satzzeichen in Anführungszeichen zu setzen, ist die sichere Gewohnheit. - Stil über
classes:, nicht knotenweise Stile – eine Definition, angewendet mitclass:. Vermeidestyle.fillauf einzelnen Knoten; hartcodierte Füllungen kämpfen mit dem Theme und brechen das Dark-Mode-Rendering. direction: rightsetzen für die meisten Architekturflüsse (von links nach rechts liest sich natürlich). Alle Engines beachten die root-level-Richtung; TALA unterstützt zusätzlich die per-Containerdirection.- Speichere die Quelle als
{name}.d2neben dem Ort, an den die Ausgabe gehört (Standard:./diagrams/im Projekt).
Schritt 3 – Rendern
Immer über das gebündelte Skript rendern – es wählt die Layout-Engine, schützt vor Wasserzeichen und validiert zuerst:
bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
--pngschreibt auchoutput.png– benötigt für Schritt 4 (das Lese-Tool zeigt Rasterbilder an, kein SVG).- Das Skript gibt
engine:(was tatsächlich gerendert hat) undfallback:(warum, wenn TALA nicht verwendet wurde) aus. Gib dem Benutzer nur dann eine einzeilige Notiz, wenn er nach Engines gefragt oder explizit TALA gewünscht hat. - Nützliche Flags:
--theme N,--dark-theme 200(SVG reagiert auf das Farbschema des Lesers),--sketch,--pad N,--seed N(TALA-Neuberechnung),--engine tala|elk|dagre(erzwingen),--allow-watermark(TALA-Auswertung). - Bei Fehlern gibt das Skript den d2-Kompilierungsfehler mit
datei:zeile:spalteaus – behebe die Quelle an dieser Stelle und führe erneut aus. Wenn der Fehler unklar ist, überprüfe den Abschnitt „Fallstricke" inreferences/d2-language.md.
Rendere niemals TALA-Ausgabe zur Auslieferung mit einem Wasserzeichen, es sei denn, der Benutzer akzeptiert dies ausdrücklich; das Skript erzwingt dies durch Fallback auf ELK.
Schritt 4 – Anschauen, dann korrigieren (nicht optional)
Die .d2-Quelle sagt nichts darüber aus, wie das Rendering tatsächlich angekommen ist – Layout ist die Entscheidung der Engine, nicht deine. Öffne das PNG mit dem Lese-Tool und überprüfe es in zwei Durchgängen:
Durchgang 1 – Vermittelt es die Botschaft?
- Tritt das Auge dort ein, wo die Geschichte beginnt, und tritt es dort aus, wo sie endet?
- Ist die Flussrichtung konsistent (nicht unbeabsichtigt zurücklaufend oder von unten nach oben lesend)?
- Entsprechen die Containergruppierungen den geplanten logischen Gruppierungen?
- Ist das wichtigste Element visuell hervorgehoben oder vergraben?
Durchgang 2 – Layout-Mängel (Auto-Layout-Engines erzeugen alle diese):
- Kantenbeschriftungen weit von ihrer Kante abgedriftet oder mehrdeutig, zu welcher Kante sie gehören
- Kanten überlappen sich in parallelen Läufen, kreuzen Knoten oder Container oder nehmen absurde Umwege
- Text abgeschnitten oder kollidierend mit Shapes/Icons
- Eine Region überfüllt, während eine andere leer ist; ein Container erheblich größer als sein Inhalt
- Knoten so klein, dass sein Label dominiert, oder stark inkonsistente Knotengrößen
- Alles, was du entschuldigend erklären müsstest, wenn du es dem Benutzer zeigen würdest
Behebe mit D2s Hebeln, nicht mit Pixel-Justierung (Auto-Layout bedeutet, du änderst Eingaben, nicht Koordinaten): ändere direction; gruppiere oder gruppiere mit Containern um; kürze Kantenbeschriftungen (lange Beschriftungen driften bei ELK am stärksten ab); führe parallele Kanten zu einer beschrifteten Kante zusammen; verschiebe Legenden/Titel aus dem Fluss mit near; teile ein überladenes Diagramm in layers auf; passe --pad an; bei TALA mit --seed N neu berechnen (probiere 2–3 Seeds – Layouts variieren erheblich); als letztes Mittel wechsle die Engine für diese Diagrammform (siehe references/layout-engines.md).
Erneut rendern, erneut ansehen, wiederholen. Plane zwei bis vier Renderzyklen ein – ein erstes Rendering, das beide Durchgänge besteht, ist selten. Fertig bedeutet: beide Durchgänge sauber, und nichts im Bild benötigt eine Entschuldigung oder eine Erklärung.
Schritt 5 – Ausliefern
- Bestätige die endgültigen
.svg- (und.d2-Quell-)Pfade – gib dem Benutzer immer beide; die.d2ist das bearbeitbare Artefakt. - Wenn das Diagramm in einem GitHub-README oder einer Dokumentationsseite leben wird, biete eine Dark-Mode-fähige Variante an: erneut rendern mit
--dark-theme 200(einzelnes SVG, das dem Farbschema des Lesers folgt). Muster für PNG/<picture>-Einbettung findest du inreferences/diagram-patterns.md. - Wenn der Benutzer selbst am Diagramm iterieren wird, erwähne
d2 --watch input.d2für eine Live-Vorschau im Browser.
Fehlerbehebung
| Symptom | Ursache / Behebung |
|---|---|
d2: command not found | Führe scripts/setup.sh aus (geführte Installation) |
D2_LAYOUT "tala" is not bundled | TALA nicht im PATH – Skript fällt automatisch auf ELK zurück; installiere TALA nur, wenn der Benutzer es möchte |
UNLICENSED-Text in der Ausgabe | TALA ohne Lizenz – das Render-Skript rendert automatisch mit ELK erneut; ein Lizenzschlüssel kommt in TSTRUCT_TOKEN oder ~/.config/tstruct/auth.json |
| PNG-Export fehlschlägt, SVG funktioniert | Der erste PNG-Render lädt einen Headless-Browser herunter; einmal wiederholen. Wenn blockiert (offline/CI), liefere SVG und überprüfe es durch Konvertierung mit einem verfügbaren SVG-Rasterisierer |
Kompilierungsfehler unter --layout tala, den ELK fehlerfrei rendert | d2/TALA-Versionskonflikt – Skript fällt automatisch zurück; schlage vor, beide zu aktualisieren |
| Icons fehlen in der Ausgabe | Icon-URL gab 403/404 zurück – entferne das Icon oder wähle ein anderes von icons.terrastruct.com; teste Icons frühzeitig |