diagram-design 2026: SVG/PNG-Export fehlerhaft – wie prüfen Sie ein KI-Architekturdiagramm?

Die SVG-Spezifikation beschreibt das viewBox-Attribut mit vier Werten für Position und Ausdehnung des sichtbaren Koordinatenbereichs (SVG 2). Fehlt dieser Bereich oder ist er unpassend, kann die Grafik abgeschnitten oder falsch skaliert erscheinen.

Vorschau stimmt, Export nicht: Vergleichen Sie zuerst die HTML-Quelldatei, die Browserdarstellung und die exportierte Datei; ändern Sie nicht vorschnell das Diagramm.

Datei sieht korrekt aus, Aussage ist fraglich: Prüfen Sie Knoten und Verbindungen anhand von Code, Schnittstellenverträgen oder dokumentierten Annahmen. Ein sauberer Export belegt keine fachliche Richtigkeit.

Dieser Beitrag richtet sich an Sie, wenn Sie KI-generierte Diagramme in Dokumentation, Präsentationen oder Code-Repositories übernehmen. Er hilft Ihnen, wenn Sie SVG- und PNG-Dateien visuell oder technisch prüfen müssen. Auch für Plattformteams, die eine nachvollziehbare Diagrammabnahme in CI/CD einrichten möchten, ist der Ablauf geeignet.

Fehler zuerst dem richtigen Verarbeitungsschritt zuordnen

Ein Exportproblem ist nicht automatisch ein Fehler des Diagrammwerkzeugs. Zwischen der Diagrammbeschreibung und der Datei, die Sie weitergeben, liegen mehrere mögliche Ursachen: die erzeugte HTML-Datei, eingebundene Styles, der Exportbefehl, die verwendete Renderumgebung und schließlich die Anwendung, in der die Datei geöffnet wird. Wenn Sie an mehreren Stellen gleichzeitig Änderungen vornehmen, verlieren Sie den Hinweis darauf, wo die Abweichung entstanden ist.

Gehen Sie daher von einem unveränderten Ausgangspunkt aus. Sichern Sie die ursprüngliche HTML-Datei und notieren Sie den verwendeten Exportbefehl, dessen Optionen, den Arbeitsordner und den tatsächlichen Ausgabepfad. Halten Sie außerdem fest, mit welcher Version und in welcher Umgebung Sie den Export ausgeführt haben. Verwenden Sie für den Vergleich dieselbe Eingabedatei: Eine neu erzeugte Grafik ist kein brauchbarer Gegenvergleich, wenn sich zugleich der Inhalt geändert hat.

Prüfen Sie anschließend die drei Artefakte getrennt:

• HTML-Quelldatei: Sind Knoten, Beschriftungen, Styles und Diagrammbereiche vorhanden?
• Browseransicht: Wird die Quelldatei in der vorgesehenen Umgebung vollständig und lesbar dargestellt?
• Exportdatei: Ist die Abweichung bereits in der Datei sichtbar oder tritt sie erst in einem bestimmten Viewer auf?

Die Exportanleitung des offiziellen diagram-design-Repositorys und die Dokumentation des Exportbefehls sind die maßgeblichen Stellen, um den aktuell beschriebenen Aufruf und dessen Optionen zu prüfen. Leiten Sie aus einem erfolgreichen Lauf nicht ab, dass jeder Agent-Client oder jede Renderumgebung dasselbe Verhalten zeigen muss. Prüfen Sie die genaue Datei, die Ihr eigener Ablauf erzeugt hat.

Warum weicht der PNG-Export von der HTML-Vorschau ab? Häufig liegt der Unterschied nicht in der Diagrammbeschreibung, sondern im Renderkontext: Schriftarten können fehlen oder ersetzt werden, ein anderer Zoomfaktor kann die Darstellung beeinflussen und ein abweichender Ausschnitt kann Inhalt abschneiden. Vergleichen Sie deshalb die HTML-Ansicht und den PNG-Export in derselben Umgebung und kontrollieren Sie, ob beide dieselbe Fläche abbilden.

Die Playwright-Dokumentation zur Seitenerfassung unterscheidet unter anderem zwischen einer Aufnahme des sichtbaren Viewports und einer Aufnahme der vollständigen Seite über die Option fullPage. Das ist für die Diagnose relevant: Ein Bild, das nur den sichtbaren Bereich erfasst, kann gegenüber einer vollständigen Seitendarstellung abgeschnitten wirken, ohne dass sich der Diagramminhalt geändert hat. Legen Sie deshalb fest, welche Art von Ausschnitt Ihr Liefergegenstand verlangt, und verwenden Sie diese Vorgabe bei jedem Vergleich.

SVG-Datei und Darstellungsstruktur untersuchen

Eine SVG-Datei ist nicht bloß ein Bild mit einer anderen Endung. Ihre Struktur, Styles und Verweise bestimmen mit, ob Beschriftungen und Formen in einem anderen Programm erhalten bleiben. Eine Datei kann sich im Browser korrekt darstellen und dennoch beim Öffnen in einem anderen Werkzeug Probleme zeigen, wenn dieses beispielsweise Styles anders auswertet oder referenzierte Elemente nicht wie erwartet findet.

Prüfen Sie die Datei zunächst als Text und nicht nur in einer Vorschau. Suchen Sie nach dem Wurzelelement <svg>, dem viewBox, den erwarteten Beschriftungen und den Elementen, die Knoten und Verbindungen zeichnen. Das viewBox legt den Koordinatenbereich fest; die SVG-2-Strukturübersicht beschreibt dessen vier Werte. Kontrollieren Sie, ob der Bereich die gesamte Zeichnung umfasst und ob seine Proportionen zum sichtbaren Inhalt passen. Ein zu enger Bereich kann Elemente am Rand abschneiden, während ein übergroßer Bereich die Grafik in einem Dokument unnötig klein erscheinen lassen kann.

Prüfen Sie auch, ob Styles tatsächlich Teil der Datei sind. Die MDN-Referenz zum SVG-Element <style> erläutert, dass dieses Element CSS-Stilinformationen für SVG aufnehmen kann. Fehlt ein benötigter Styleblock oder wurde eine Formatierung nur in der HTML-Umgebung definiert, kann die exportierte Datei anders aussehen als die Vorschau. Achten Sie dabei auf Verweise aus Attributen wie class oder url(#...): Ein vorhandener Style oder Filter hilft nicht, wenn die referenzierte Kennung fehlt oder im Dokument nicht eindeutig ist.

Wie prüfen Sie, ob der diagram-design-SVG-Export vollständig ist? Vergleichen Sie die erwarteten Texte und Diagrammelemente mit dem Dateiinhalt, prüfen Sie den sichtbaren Koordinatenbereich und öffnen Sie die exportierte SVG in einer unabhängigen Zielanwendung. Bleiben Beschriftungen nur in der HTML-Datei auffindbar, fehlen Styles oder sind Verweise nicht auflösbar, behandeln Sie die SVG nicht als abnahmefähig. Entscheidend ist die konkrete Datei, nicht die Behauptung, ein Format werde grundsätzlich unterstützt.

Achten Sie bei wiederverwendeten SVG-Bestandteilen zusätzlich auf doppelte IDs. IDs dienen innerhalb des Dokuments zur Identifikation von Elementen und können als Ziele für Verweise verwendet werden. Wenn sich identische IDs einschleichen, können Verknüpfungen auf das falsche Element zeigen oder in unterschiedlichen Renderern anders aufgelöst werden. Die SVG-2-Strukturdokumentation bietet hierfür den maßgeblichen Strukturkontext. Ändern Sie solche Stellen gezielt und prüfen Sie danach erneut, ob Filter, Pfeilspitzen, Beschriftungen und andere referenzierte Elemente noch funktionieren.

Eine SVG, die sich in einem Browser öffnen lässt, ist damit noch nicht als vollständige Lieferdatei bestätigt. Bewahren Sie bei der Abnahme die tatsächlich geprüfte Datei und die zugehörige Quelle gemeinsam auf.

PNG-Rendering und Umgebung voneinander trennen

PNG ist ein gerastertes Ausgabeformat. Anders als bei einer Vektordatei können Sie nach dem Export nicht beliebig in die Formen hineinzoomen, ohne dass die Darstellung an Schärfe verliert. Für die Diagnose ist daher wichtig, ob die Ausgabe bereits beim Erzeugen abgeschnitten oder anders skaliert wurde oder ob lediglich die Anzeige im Zielprogramm täuscht.

Vergleichen Sie den PNG-Export mit dem HTML-Rendering bei möglichst gleichen Bedingungen. Prüfen Sie insbesondere:

• Sind alle Diagrammränder und Beschriftungen im Bild enthalten?
• Haben Schriftgröße, Zeilenumbrüche und Abstände sichtbar gewechselt?
• Sind Farben und Kontraste ausreichend, um Knoten und Verbindungen zu unterscheiden?
• Wird das Bild im Zielprogramm mit einer Vergrößerung angezeigt, die einen fairen Vergleich erlaubt?
• Wird dieselbe Schriftfamilie verwendet oder ersetzt die Exportumgebung eine lokal vorhandene Schrift?

Wenn der PNG-Export in Ihrer lokalen Umgebung korrekt aussieht, in der Dokumentationspipeline aber nicht, führen Sie denselben Export mit derselben Eingabedatei in beiden Umgebungen erneut aus. Notieren Sie die Umgebungsunterschiede, statt die Grafik sofort manuell zu korrigieren. Andernfalls kann eine vermeintliche Layoutkorrektur einen Font- oder Ausschnittfehler verdecken und bei der nächsten Ausführung an anderer Stelle neue Abweichungen erzeugen.

Eine belastbare Vergleichsprobe enthält die unveränderte Quelldatei, die lokale Ausgabe, die Ausgabe aus der Zielpipeline und eine kurze Notiz dazu, welche Unterschiede Sie festgestellt haben. Speichern Sie außerdem die ausgegebene Datei als Beleg. So können Sie später nachvollziehen, ob ein Problem bei der Erzeugung, bei einer nachgelagerten Verarbeitung oder erst bei der Darstellung aufgetreten ist.

Visuelle Korrektheit und fachliche Richtigkeit getrennt bewerten

Die entscheidende Abnahmefrage lautet nicht nur, ob das Bild gut aussieht. Ein Diagramm kann technisch sauber exportiert sein und trotzdem eine falsche Abhängigkeit, einen erfundenen Dienst oder einen irreführenden Pfeil enthalten. Gerade bei automatisch erzeugten Architekturdiagrammen müssen Sie deshalb Inhalt und Darstellung als getrennte Prüffälle behandeln.

Gehen Sie Knoten und Verbindungen einzeln durch. Für jeden Knoten sollten Sie klären können, ob er durch Code, eine Schnittstellenvereinbarung, eine Anforderung oder eine andere belastbare Projektquelle gestützt wird. Für jede Verbindung muss nachvollziehbar sein, was sie bedeutet: etwa Datenfluss, Aufrufrichtung, Abhängigkeit oder bloße Gruppierung. Wenn eine Linie keine eindeutige Semantik besitzt, ergänzen Sie eine Beschriftung oder lassen Sie sie von der verantwortlichen Person bestätigen.

Was ist zu tun, wenn der Export korrekt ist, aber eine Verbindung die falsche Bedeutung hat? Korrigieren Sie nicht nur die Position des Pfeils. Gehen Sie auf die fachliche Quelle zurück und prüfen Sie, ob die dargestellte Beziehung tatsächlich belegt ist. Ist sie weder im Code noch in einer Anforderung oder Schnittstellenvereinbarung nachweisbar, kennzeichnen Sie sie als offene Annahme und geben Sie das Diagramm nicht als bestätigte Architektur aus.

Das gilt auch für Komponenten, die ein Agent plausibel ergänzt, obwohl sie in den Eingaben nicht genannt wurden. Eine optisch stimmige Grafik macht aus einer Vermutung keine dokumentierte Tatsache. Führen Sie daher bei unklaren Elementen eine sichtbare Kennzeichnung wie „zu verifizieren“ oder entfernen Sie den Knoten bis zur fachlichen Klärung. Diese Trennung hilft besonders dann, wenn eine Grafik später in Architekturentscheidungen, Sicherheitsprüfungen oder Betriebsdokumentation einfließt.

Als Praxisfall: Ein Team übernimmt eine HTML-Vorschau in ein internes Dokument und bemerkt erst nach dem PDF-Export, dass Pfeilspitzen fehlen. Das ist zunächst ein Darstellungs- oder Exportproblem. Bei der anschließenden Prüfung fällt auf, dass eine Verbindung zwischen zwei Diensten in der Quelldatei zwar vorhanden ist, aber keine Schnittstellenquelle dafür existiert. Hier liegen zwei Fehlerklassen vor: Der Export muss technisch korrigiert werden, und die Beziehung muss fachlich geprüft werden. Werden beide Punkte zu einem allgemeinen „Diagramm fehlerhaft“ zusammengefasst, bleibt unklar, wer was beheben muss.

Abnahmebedingungen für den Dokumentationsablauf

Ein verlässlicher Freigabeprozess trennt automatisierbare Dateiprüfungen von der menschlichen Bewertung der Aussage. Automatisierung kann feststellen, ob ein erwartetes Artefakt vorhanden und als Datei lesbar ist oder ob ein Exportlauf fehlgeschlagen ist. Sie kann jedoch nicht ohne belastbare fachliche Regeln bestätigen, dass jede Verbindung die tatsächliche Architektur korrekt wiedergibt.

Die folgende Gegenüberstellung hilft Ihnen, die passende Prüfung dem jeweiligen Risiko zuzuordnen:

Für die automatische Ablage können Sie die Ausgabedateien zusammen mit den Protokollen des Prüfjobs sichern. Die Dokumentation zu Workflow-Artefakten beschreibt, wie Dateien aus einem Workflow zur späteren Prüfung aufbewahrt werden können. Richten Sie die Ablage so ein, dass eine fehlgeschlagene Prüfung nicht nur einen allgemeinen Status hinterlässt, sondern die verwendete Quelle, die erzeugten Dateien und relevante Protokolle verfügbar bleiben.

Wie integrieren Sie diagram-design-Ausgaben in die CI-Abnahme? Beginnen Sie mit einer eng begrenzten Prüfung: Lassen Sie den dokumentierten Exportbefehl auf einer festgelegten Eingabe laufen, prüfen Sie anschließend, ob die erwarteten Dateien erstellt wurden, und speichern Sie diese als Artefakte. Ergänzen Sie danach gezielte Strukturkontrollen für Elemente, die bei Ihnen zwingend vorhanden sein müssen. Eine menschliche Sicht- und Faktenprüfung bleibt nötig, wenn die Grafik veröffentlicht oder als technische Entscheidungsgrundlage genutzt wird.

Umsetzbarer Prüfablauf für eine konkrete Abweichung

Führen Sie die Untersuchung in einer Reihenfolge durch, in der jeder Schritt eine mögliche Fehlerquelle eingrenzt:

1. Ausgangsdateien sichern. Kopieren Sie die HTML-Quelle und alle Eingaben an einen Prüfpfad. Ändern Sie während der Diagnose weder Labels noch Layout.
2. Exportaufruf festhalten. Notieren Sie den genauen Befehl, die gewählten Optionen, die verwendete Version und den Speicherort der Ausgabe. Vergleichen Sie den Aufruf mit der aktuellen Exportdokumentation.
3. HTML-Ansicht kontrollieren. Prüfen Sie in der vorgesehenen Renderumgebung, ob Beschriftungen, Knoten und Verbindungen bereits dort fehlen oder falsch angeordnet sind. Tritt der Fehler schon hier auf, suchen Sie zuerst in Quelle und Styles.
4. SVG-Struktur prüfen. Kontrollieren Sie viewBox, Text, Styles und interne Referenzen. Öffnen Sie die Datei zusätzlich in der Anwendung, in der sie später verwendet wird.
5. PNG unter gleichen Bedingungen neu erzeugen. Nutzen Sie unveränderte Eingaben und vergleichen Sie lokale Ausgabe und Pipeline-Ausgabe. Halten Sie Unterschiede bei Schrift, Ausschnitt, Skalierung und Farben fest.
6. Fakten nachweisen. Ordnen Sie jeden Knoten und jede relevante Verbindung einer Code-Stelle, Schnittstellenbeschreibung oder bestätigten Anforderung zu. Unbelegte Beziehungen bleiben ausdrücklich Annahmen.
7. Freigabe dokumentieren. Bewahren Sie Quelle, Exportdatei und Prüfprotokoll zusammen auf. Vermerken Sie, welche Punkte automatisiert geprüft wurden und welche eine fachkundige Person bestätigt hat.

Wenn Sie diese Schritte für andere Teams dokumentieren, sollte auch klar sein, wer Fehler behebt: Ein Dateifehler gehört in den Exportablauf, ein Font- oder Renderingunterschied in die Umgebungskonfiguration und eine unbelegte Architekturbeziehung zur fachlichen Prüfung. Für Fragen zu den verfügbaren Abläufen können Sie das kvmboot Help Center als Anlaufstelle verwenden; es ersetzt allerdings nicht die Prüfung Ihrer konkreten Dateien.

Temporäre Testumgebung statt vermeintlicher Exportlösung

Wenn die Prüfung an einer inkonsistenten lokalen Umgebung scheitert, müssen Sie nicht sofort Ihre gesamte Arbeitsweise umstellen. Lokale Exporte sind oft der einfachste Weg für einzelne Diagramme. Für wiederkehrende Agent-Läufe können jedoch eine rechnergebundene Umgebung, lokal installierte Schriften und nicht dokumentierte Abhängigkeiten die Reproduktion erschweren. Eine zentral definierte Pipeline ist besser nachvollziehbar, verlangt aber weiterhin, dass Sie Eingaben, Versionen und Ausgaben sauber festhalten.

Für zeitlich begrenzte Tests kann eine gemietete Mac-Umgebung von kvmboot eine Alternative sein, wenn Sie einen Agent-Arbeitsablauf unter einer separaten, kontrollierbaren Umgebung erproben oder Artefakte reproduzierbar erzeugen möchten. Sie beseitigt weder einen falschen viewBox-Wert noch eine unbelegte Verbindung und sollte nicht als Reparatur für einen Diagrammfehler behandelt werden. Prüfen Sie außerdem vorab, ob Ihre Datenschutzvorgaben die Übertragung von Quellcode und Dokumentation in eine externe Umgebung erlauben; sensible Projektdaten gehören nur in einen dafür freigegebenen Ablauf.

Die Abwägung ist praktisch: Ihre vorhandene lokale Umgebung verursacht keine zusätzliche Mietentscheidung, kann aber von individuellen Schrift- und Softwareständen abhängen. Eine CI-Pipeline liefert wiederholbare Prüfungen, benötigt dafür jedoch Pflege und klare Verantwortlichkeiten. Eine temporär gemietete Umgebung kann für einen begrenzten Test oder eine reproduzierbare Agent-Ausführung sinnvoll sein, ist aber keine passende Dauerlösung für jeden Workload und keine Voraussetzung für eine SVG-/PNG-Abnahme. Wenn Sie nach dieser Diagnose tatsächlich eine separate Umgebung testen möchten, finden Sie die entsprechende Mietoption für die US-Ostküste. Veröffentlichen Sie die Grafik erst, wenn sowohl die Exportdatei als auch die fachliche Bedeutung der dargestellten Beziehungen geprüft sind.