HTML Diagramm Ersteller
Erstelle eigenständige .html-Dateien mit einem einzigen eingebetteten <svg>, die visuell argumentieren, nicht nur Informationen anzeigen. Erstelle dann mit Playwright Screenshots, überprüfe das PNG und behebe Fehler, bis alles sauber ist.
Dateien in dieser Fähigkeit
| Datei | Zweck | Wann lesen |
|---|---|---|
references/color-palette.md | Alle Farben und Markenstile: die einzige Quelle der Wahrheit | Vor jedem Diagramm |
references/visual-patterns.md | Skizzen jedes Layoutmusters (Fan-Out, Timeline, Baum...) | Design Schritt 2 |
references/starter.html | Seiten-Shell: CSS-Tokens, Text-/Shape-Klassen, Pfeilmarkierungen, ein Beispiel jeder Konvention | Kopiere es als Start jedes Diagramms |
scripts/render.py | Erstellt Screenshots des HTML als PNG und prüft die Geometrie | Nach jeder Bearbeitung ausführen (siehe Rendern & Validieren) |
examples/ | Zwei fertige Diagramme mit ihren PNGs | Wenn du eine Referenz für Dichte und Stil möchtest |
Um jedes Diagramm für eine Marke umzugestalten, bearbeite color-palette.md (und die passenden Tokens in starter.html). Alles andere ist universelle Methode.
Zwei bereits getroffene Entscheidungen (Nicht pro Diagramm erneut diskutieren)
1. Alles ist SVG. HTML ist nur die Seite drumherum.
Boxen, Text, Pfeile und Codeblöcke leben alle in einem <svg id="diagram">. Baue keine Boxen aus HTML/CSS (Flexbox/Grid-Divs) mit einer SVG-Überlagerung für Verbindungen.
Warum: Ein Diagramm ist ein Geometrieproblem, und Pfeile benötigen exakte Koordinaten für beide Enden. Mit reinem SVG teilen sich jeder Knoten und jeder Pfeil ein Koordinatensystem, das in der Datei geschrieben ist, sodass du ein Pfeilende durch Arithmetik berechnen und durch Bearbeiten einer Zahl korrigieren kannst. Bei HTML-Boxen stammen die Positionen aus der Layout-Engine des Browsers: Sie sind nicht in der Quelle vorhanden, verschieben sich mit Schriftarten und Viewport-Breite, und Verbinder benötigen dann JavaScript, das Boxen zur Laufzeit misst. Das ist ein zweites Programm, das debuggt werden muss, und der Viewport des Lesers kann sich von dem unterscheiden, den du validiert hast. Die Kosten von reinem SVG sind real, aber geringer: SVG-Text wird nicht umbrochen (brich Zeilen selbst mit <tspan>) und seine Breite ist erst beim Rendern bekannt (der Linter misst sie und meldet Überlauf).
<foreignObject> (HTML innerhalb von SVG) ist standardmäßig deaktiviert: Es ist der einzige Ort, an dem du Textumbruch erhalten würdest, aber es rendert außerhalb von Browsern inkonsistent und der Linter kann es nicht überprüfen. Verwende es nur, wenn der Benutzer Absätze innerhalb einer Form benötigt.
2. Kein Graphviz oder D2 für das Layout. Platziere Koordinaten von Hand.
Warum: Die Methodik verlangt, dass das Layout das Konzept widerspiegelt: Fan-Outs, Zeitleisten, Zyklen, Side-by-Side-Vergleiche, freischwebende Anmerkungen, Codeblöcke neben dem Schritt, den sie veranschaulichen. Automatische Layout-Engines optimieren auf ein anderes Ziel (geschichtete Graphen mit wenigen Kantenkreuzungen), daher glätten sie jedes Diagramm in dieselbe Top-Down-Hierarchie, was genau die „einheitlichen Boxen“-Ausgabe ist, die diese Fähigkeit vermeiden soll. Sie fügen auch eine binäre Abhängigkeit hinzu und erzeugen SVG, das sich nur schwer umgestalten und mit Anmerkungen versehen lässt.
Die Ausnahme: Ein wirklich graphförmiges Subjekt (etwa 15+ Knoten mit vielen Querverbindungen, wie ein Abhängigkeitsgraph), bei dem Kreuzungen das Hauptproblem sind. Führe dort dot -Tplain (Graphviz) nur aus, um Knotenkoordinaten zu erhalten, zeichne dann die Knoten selbst mit den Stilen und Konventionen dieser Fähigkeit. Sage, dass du dies tust und warum.
Kernphilosophie
Diagramme sollten ARGUMENTIEREN, nicht ANZEIGEN.
Ein Diagramm ist kein formatierter Text. Es ist ein visuelles Argument, das Beziehungen, Kausalität und Fluss zeigt, die Worte allein nicht ausdrücken können. Die Form sollte die BEDEUTUNG sein.
Der Isomorphie-Test: Wenn du den gesamten Text entfernen würdest, würde die Struktur allein das Konzept kommunizieren? Wenn nicht, gestalte neu.
Der Bildungs-Test: Könnte jemand etwas Konkretes aus diesem Diagramm lernen, oder beschriftet es nur Boxen? Ein gutes Diagramm lehrt – es zeigt tatsächliche Formate, reale Ereignisnamen, konkrete Beispiele.
Tiefenbewertung (Zuerst durchführen)
Bevor du mit dem Design beginnst, bestimme, welchen Detaillierungsgrad dieses Diagramm benötigt:
Einfache/Konzeptionelle Diagramme
Verwende abstrakte Formen, wenn:
- Ein mentales Modell oder eine Philosophie erklärt wird
- Das Publikum keine technischen Details benötigt
- Das Konzept DIE Abstraktion IST (z. B. „Trennung der Belange“)
Umfassende/Technische Diagramme
Verwende konkrete Beispiele, wenn:
- Ein reales System, Protokoll oder eine Architektur diagrammiert wird
- Das Diagramm zum Lehren oder Erklären verwendet wird (z. B. YouTube-Video)
- Das Publikum verstehen muss, wie die Dinge tatsächlich aussehen
- Du zeigst, wie mehrere Technologien integriert werden
Bei technischen Diagrammen MUSST du Nachweisartefakte einfügen (siehe unten).
Recherche-Auftrag (Für technische Diagramme)
Bevor du etwas Technisches zeichnest, recherchiere die tatsächlichen Spezifikationen.
Wenn du ein Protokoll, eine API oder ein Framework diagrammierst:
- Suche die tatsächlichen JSON-/Datenformate nach
- Finde die realen Ereignisnamen, Methodennamen oder API-Endpunkte
- Verstehe, wie die Teile tatsächlich verbunden sind
- Verwende echte Terminologie, keine generischen Platzhalter
Schlecht: „Protokoll“ → „Frontend“ Gut: „AG-UI streamt Ereignisse (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)“ → „CopilotKit rendert via createA2UIMessageRenderer()“
Recherche macht Diagramme genau UND lehrreich.
Nachweisartefakte
Nachweisartefakte sind konkrete Beispiele, die beweisen, dass dein Diagramm korrekt ist, und den Betrachtern helfen, zu lernen. Füge sie in technische Diagramme ein.
Arten von Nachweisartefakten (wähle, was für dein Diagramm relevant ist):
| Artefakt-Typ | Wann verwenden | Wie rendern |
|---|---|---|
| Code-Ausschnitte | APIs, Integrationen, Implementierungsdetails | Dunkles Rechteck + syntax-gefärbter Text (siehe Farbpalette für Nachweisartefakt-Farben) |
| Daten/JSON-Beispiele | Datenformate, Schemata, Payloads | Dunkles Rechteck + farbiger Text (siehe Farbpalette) |
| Ereignis-/Schrittsequenzen | Protokolle, Workflows, Lebenszyklen | Timeline-Muster (Linie + Punkte + Beschriftungen) |
| UI-Mockups | Zeigen tatsächlicher Ausgabe/Ergebnisse | Verschachtelte Rechtecke, die echte UI imitieren |
| Echte Eingabeinhalte | Zeigen, was IN ein System geht | Rechteck mit sichtbarem Beispielinhalt |
| API-/Methodennamen | Echte Funktionsaufrufe, Endpunkte | Verwende tatsächliche Namen aus der Dokumentation, keine Platzhalter |
Beispiel: Für ein Diagramm über ein Streaming-Protokoll könntest du zeigen:
- Die tatsächlichen Ereignisnamen aus der Spezifikation (nicht nur „Ereignis 1“, „Ereignis 2“)
- Einen Code-Ausschnitt, der zeigt, wie man sich verbindet
- Wie die gestreamten Daten tatsächlich aussehen
Beispiel: Für ein Diagramm über eine Datentransformations-Pipeline:
- Zeige Beispieleingabedaten (tatsächliches Format, nicht „Eingabe“)
- Zeige Beispielausgabedaten (tatsächliches Format, nicht „Ausgabe“)
- Zeige bei Bedarf Zwischenzustände
Das Kernprinzip: zeige, wie die Dinge tatsächlich aussehen, nicht nur, wie sie heißen.
Multi-Zoom-Architektur
Umfassende Diagramme arbeiten auf mehreren Zoomstufen gleichzeitig. Stelle es dir wie eine Karte vor, die sowohl die Ländergrenzen als auch die Straßennamen zeigt.
Stufe 1: Zusammenfassungsfluss
Ein vereinfachter Überblick, der die gesamte Pipeline oder den gesamten Prozess auf einen Blick zeigt. Oft oben oder unten im Diagramm platziert.
Beispiel: Eingabe → Verarbeitung → Ausgabe oder Client → Server → Datenbank
Stufe 2: Abschnittsgrenzen
Beschriftete Bereiche, die zusammengehörige Komponenten gruppieren. Diese schaffen visuelle „Räume“, die dem Betrachter helfen zu verstehen, was zusammengehört.
Beispiel: Gruppierung nach Verantwortung (Backend / Frontend), nach Phase (Einrichtung / Ausführung / Bereinigung) oder nach Team (Benutzer / System / Extern)
Stufe 3: Details innerhalb der Abschnitte
Nachweisartefakte, Code-Ausschnitte und konkrete Beispiele in jedem Abschnitt. Hier liegt der Bildungswert.
Beispiel: In einem „Backend“-Abschnitt könntest du das tatsächliche API-Antwortformat zeigen, nicht nur eine Box mit der Beschriftung „API-Antwort“
Bei umfassenden Diagrammen solltest du alle drei Stufen einbeziehen. Die Zusammenfassung gibt Kontext, die Abschnitte organisieren und die Details lehren.
Schlecht vs. Gut
| Schlecht (Anzeigen) | Gut (Argumentieren) |
|---|---|
| 5 gleiche Boxen mit Beschriftungen | Jedes Konzept hat eine Form, die sein Verhalten widerspiegelt |
| Kartenraster-Layout | Visuelle Struktur entspricht der konzeptionellen Struktur |
| Symbole, die Text verzieren | Formen, die DIE Bedeutung SIND |
| Gleicher Container für alles | Unterschiedlicher visueller Wortschatz pro Konzept |
| Alles in einer Box | Freischwebender Text mit selektiven Containern |
Einfach vs. Umfassend (Wisse, was du brauchst)
| Einfaches Diagramm | Umfassendes Diagramm |
|---|---|
| Generische Beschriftungen: „Eingabe“ → „Prozess“ → „Ausgabe“ | Spezifisch: zeigt, wie die Eingabe/Ausgabe tatsächlich aussieht |
| Benannte Boxen: „API“, „Datenbank“, „Client“ | Benannte Boxen + Beispiele für tatsächliche Anfragen/Antworten |
| „Ereignisse“ oder „Nachrichten“-Beschriftung | Zeitleiste mit echten Ereignis-/Nachrichtennamen aus der Spezifikation |
| „UI“ oder „Dashboard“-Rechteck | Mockup mit tatsächlichen UI-Elementen und -Inhalten |
| ~30 Sekunden zum Erklären | ~2-3 Minuten Lehrinhalt |
| Betrachter lernt die Struktur | Betrachter lernt die Struktur UND die Details |
Einfache Diagramme sind in Ordnung für abstrakte Konzepte, schnelle Überblicke oder wenn das Publikum die Details bereits kennt. Umfassende Diagramme werden für technische Architekturen, Tutorials, Bildungsinhalte oder wenn das Diagramm selbst lehren soll, benötigt.
Container vs. Freischwebender Text
Nicht jedes Textstück benötigt eine Form darum. Standardmäßig freischwebender Text. Füge Container nur hinzu, wenn sie einen Zweck erfüllen.
| Verwende einen Container, wenn... | Verwende freischwebenden Text, wenn... |
|---|---|
| Es der Brennpunkt eines Abschnitts ist | Es eine Beschriftung oder Beschreibung ist |
| Es eine visuelle Gruppierung mit anderen Elementen benötigt | Es unterstützendes Detail oder Metadaten ist |
| Pfeile eine Verbindung dorthin benötigen | Es etwas in der Nähe beschreibt |
| Die Form selbst Bedeutung trägt (Entscheidungsraute usw.) | Typografie allein ausreichende Hierarchie schafft |
| Es ein eindeutiges „Ding“ im System darstellt | Es ein Abschnittstitel, Untertitel oder eine Anmerkung ist |
Typografie als Hierarchie: Verwende Schriftgröße, -stärke und -farbe, um visuelle Hierarchie ohne Boxen zu schaffen. Ein 28px-Titel benötigt kein Rechteck darum.
Der Container-Test: Frage bei jedem boxierten Element: „Würde dies als freischwebender Text funktionieren?“ Wenn ja, entferne den Container.
Designprozess (Führe DIES VOR dem Schreiben von SVG durch)
Schritt 0: Erforderliche Tiefe bewerten
Bestimme vor allem anderen, ob dies sein muss:
- Einfach/Konzeptionell: Abstrakte Formen, Beschriftungen, Beziehungen (mentale Modelle, Philosophien)
- Umfassend/Technisch: Konkrete Beispiele, Code-Ausschnitte, reale Daten (Systeme, Architekturen, Tutorials)
Wenn umfassend: Recherchiere zuerst. Suche die tatsächlichen Spezifikationen, Formate, Ereignisnamen, APIs nach.
Schritt 1: Tief verstehen
Lies den Inhalt. Frage bei jedem Konzept:
- Was tut dieses Konzept? (nicht was IST es)
- Welche Beziehungen bestehen zwischen den Konzepten?
- Was ist die Kern-Transformation oder der Kern-Fluss?
- Was müsste jemand SEHEN, um das zu verstehen? (nicht nur darüber lesen)
Schritt 2: Konzepte Mustern zuordnen
Finde für jedes Konzept das visuelle Muster, das sein Verhalten widerspiegelt. Skizzen und Nutzungshinweise für jedes Muster findest du in references/visual-patterns.md.
| Wenn das Konzept... | Verwende dieses Muster |
|---|---|
| Mehrere Ausgaben erzeugt | Fan-Out (radiale Pfeile vom Zentrum) |
| Eingaben zu einer zusammenführt | Konvergenz (Trichter, zusammenlaufende Pfeile) |
| Hierarchie/Verschachtelung hat | Baum (Linien + freischwebender Text) |
| Eine Abfolge von Schritten ist | Zeitleiste (Linie + Punkte + freischwebende Beschriftungen) |
| Schleift oder sich kontinuierlich verbessert | Spirale/Zyklus (Pfeil, der zum Start zurückkehrt) |
| Ein abstrakter Zustand oder Kontext ist | Wolke (überlappende Ellipsen) |
| Eingabe in Ausgabe transformiert | Fließband (vorher → Prozess → nachher) |
| Zwei Dinge vergleicht | Nebeneinander (parallel mit Kontrast) |
| In Phasen trennt | Lücke/Pause (visuelle Trennung zwischen Abschnitten) |
Schritt 3: Vielfalt sicherstellen
Für Diagramme mit mehreren Konzepten: Jedes Hauptkonzept muss ein anderes visuelles Muster verwenden. Keine einheitlichen Karten oder Raster.
Schritt 4: Den Fluss skizzieren
Bevor du Markup schreibst, zeichne mental nach, wie das Auge durch das Diagramm wandert. Es sollte eine klare visuelle Geschichte geben.
Schritt 5: Das HTML/SVG bauen
Erst jetzt die Datei schreiben, beginnend mit references/starter.html. Lege auf einem 20px-Raster aus und notiere die wichtigsten Koordinaten (Spalten, Zeilen, Knotenmittelpunkte), bevor du etwas platzierst. Siehe unten für den Umgang mit großen Diagrammen.
Schritt 6: Rendern & Validieren (VERPFLICHTEND)
Nach dem Schreiben der Datei MUSST du den Render-Ansicht-Korrigieren-Zyklus ausführen, bis das Diagramm richtig aussieht. Dies ist nicht optional – siehe den Abschnitt Rendern & Validieren unten für den vollständigen Prozess.
Strategie für große / umfassende Diagramme
Baue das SVG bei umfassenden oder technischen Diagrammen abschnittsweise auf. Schreibe die gesamte Datei nicht in einem Durchgang. Ein umfassendes Diagramm kann das Ausgabelimit pro Antwort überschreiten, und selbst wenn es passt, erhält jeder Abschnitt bei einem Durchgang pro Abschnitt die volle Aufmerksamkeit.
Der Abschnittsweise Workflow
Phase 1: Jeden Abschnitt bauen
- Erstelle die Datei aus
references/starter.html: setze den<title>, dieviewBoxund füge den ersten Abschnitt hinzu. - Füge einen Abschnitt pro Bearbeitung hinzu, jeden in einem eigenen
<g id="sec-...">. Denke über das Layout dieses Abschnitts, seine Abstände und wie er mit dem bereits Vorhandenen verbunden ist. - Verwende beschreibende IDs (
data-node="trigger",id="sec-backend"), damit abschnittsübergreifende Kanten lesbar sind:data-from="trigger" data-to="router". - Führe einen Koordinatenplan in einem HTML-Kommentar oben im SVG (Spalten-x, Zeilen-y, Abschnittsgrenzen). Jeder spätere Abschnitt und jede Kante liest daraus, und so behebst du Abstandsprobleme, ohne zu raten.
Phase 2: Das Ganze überprüfen
Lies die vollständige Datei durch und überprüfe:
- Benennt jedes
data-from/data-toeindata-node, das existiert? - Sind die Abstände ausgewogen, oder sind einige Abschnitte beengt, während andere spärlich sind?
- Enthält die
viewBoxalles, mit ~40px Rand?
Phase 3: Rendern & validieren (unten).
Abschnittsgrenzen
…
[truncated for translation]