Cztery narzędzia do diagramów w trzy miesiące. Ten sam schemat, cztery razy

Pierwszy wykres kołowy, który wstawiłem na tę stronę, był nieczytelny. Generator założył białą kartkę i wypisał napisy najciemniejszym odcieniem, jaki miał, więc w trybie, w którym akurat pracowałem, zniknęły. Zamiast zmienić narzędzie, dopisałem w instrukcjach projektu regułę: wykres kołowy owijaj w biały kontener.

Ta reguła siedzi tam do dziś. Jest pomnikiem etapu, w którym łatałem zamiast wybierać.

Stronę buduję trzeci rok, ale narzędzia do diagramów wymieniłem w ostatnich trzech miesiącach - cztery podejścia, jedno po drugim. Każde weszło, bo poprzednie zaczęło mi przeszkadzać w konkretny sposób, a nie bo było nowsze. Poniżej ta droga, a na końcu ten sam schemat wygenerowany cztery razy - żebyś zobaczył różnicę, zamiast czytać o niej.

Jedna rzecz przewija się przez wszystkie cztery etapy: diagram musi być czytelny niezależnie od tego, w jakim trybie siedzi czytelnik. Ja pracuję w jednym, ktoś inny w drugim, a plik jest jeden. To wymaganie skreśliło więcej rozwiązań niż jakiekolwiek inne - i to ono decyduje, że kolejne narzędzia z tej listy potrafią wypuścić ten sam schemat w dwóch wariantach z jednego źródła.

Z tego artykułu dowiesz się:

• czym różnią się cztery podejścia do diagramów: język znaczników, kompilator, generator obrazów i generator z walidatorem,
• gdzie każde z nich pęka, na moich konkretnych wpadkach z tego tygodnia,
• dlaczego lokalny podgląd SVG potrafi kłamać i jak to sprawdzić w dwie minuty,
• czym dziś robię który rodzaj grafiki, w formie tabeli do skopiowania.

Etap 1: Mermaid, czyli diagram w tekście

Mermaid wygrał na starcie jedną rzeczą: nie trzeba nic instalować. Piszesz kilka linii w bloku kodu, GitHub i Obsidian renderują to same. Diagram żyje w tym samym pliku co treść, więc wersjonuje się razem z nią.

Problemy przyszły w kolejności, w jakiej zwykle przychodzą - od kosmetyki do fundamentu.

Najpierw układ. Domyślne pionowe schematy na stronie czytają się źle: wąska kolumna pudełek, mnóstwo pustego miejsca po bokach, a na telefonie i tak trzeba przewijać. W instrukcjach projektu skończyło się to twardym zapisem, że wolno używać wyłącznie poziomych.

Potem kolory. Motyw ciemny w Mermaidzie nie pokrywa wszystkich typów wykresów jednakowo, stąd wspomniany biały kontener pod wykresy kołowe.

Na koniec rzecz, którą odkryłem dopiero przy pisaniu tego artykułu. Mermaid wkłada etykiety węzłów w element foreignObject, czyli wstawia HTML do środka SVG. Przeglądarka pokaże to poprawnie, dopóki SVG jest częścią strony. Wstaw ten sam plik jako obrazek - a tak wstawia się grafiki we wpisach - i w części przeglądarek zostaną same puste prostokąty. Ratuje ustawienie htmlLabels: false, tylko trzeba wiedzieć, że istnieje.

Etap 2: D2, czyli kompilator zamiast znaczników

D2 to język, który kompilujesz do SVG jedną komendą. Różnica względem Mermaida nie jest kosmetyczna, siedzi w dwóch miejscach.

Pierwsze to silnik układu. D2 potrafi liczyć rozmieszczenie przez ELK, ten sam, który stoi za porządnymi narzędziami do grafów. Efekt: linie nie przecinają pudełek, a schemat da się czytać bez mrużenia oczu.

Drugie to motywy jako liczby. --theme 0 daje wariant jasny, --theme 200 ciemny. Ta sama treść, dwa pliki, zero dłubania w kolorach.

Dlatego w moim generatorze wpisów blogowych stoi dziś jednoznaczna reguła: jeśli wpis ma diagram, to D2, nie Mermaid, i zawsze poziomo. Realnie stoi na tym trzy artykuły: o RAG po polsku, o lokalnym klonowaniu głosu i o prompterach w notchu MacBooka.

Ograniczenie D2 jest uczciwe: to wciąż pudełka i strzałki. Ładne, spójne, ale bez ikon marek i bez ruchu.

Etap 3: prompt zamiast kodu

Tu poszedłem w bok. Zamiast opisywać strukturę, opisywałem obrazek. Baoyu-design pisał gotowy prompt, a generator obrazów renderował z niego grafikę.

To działa, ale nie na diagramy. Model obrazu nie rozumie, że dwie strzałki nie mogą się przecinać, że etykieta ma należeć do jednej krawędzi i że kolejność kroków jest treścią, nie ozdobą. Dostajesz ładny kadr z klimatem marki, w którym napisy bywają zmyślone, a układ za każdym razem inny.

Tak wygląda taki prompt dla naszego schematu:

Ilustracja techniczna w motywie terminalowym, ciemne tło #0d1117,
akcent zieleń #3fb950, typografia bezszeryfowa i monospace.
Sześć etapów pracy ułożonych poziomo, połączonych cienkimi liniami:
notatka z pomysłem, research ze źródłami, dokument tekstowy,
schemat i ilustracja obok siebie, strona internetowa,
na końcu trzy ikony sieci społecznościowych.
Płaski styl, cienkie obramowania 1 px, bez cieni, bez gradientów,
bez tekstu na obrazku. Format panoramiczny 16:9.

Zwróć uwagę na ostatni warunek: bez tekstu na obrazku. To jedyny sposób, żeby taka grafika nie kłamała. A schemat bez podpisów przestaje być schematem i staje się dekoracją.

Wniosek z tego etapu jest prosty i wcale nie negatywny: generator obrazów świetnie robi ilustracje do wpisu, byle nie udawały diagramu. Do dziś tak robię grafiki z maskotką. Do struktury wróciłem do kodu.

Etap 4: fireworks-tech-graph, czyli generator z bramkami

Ten skill działa inaczej niż wszystko wcześniej: model nie rysuje. Wybiera styl i wypełnia treść, a SVG składa generator w Pythonie. Potem wynik przechodzi przez walidator geometrii i przez odczyt wyrenderowanego obrazu. Plik zapisuje się dopiero po przejściu bramek.

Kontrakt kompozycji podany jest liczbami, nie przymiotnikami: zero niezamierzonych skrzyżowań krawędzi, maksymalnie dwa zgięcia na krawędź, minimum 40 px między węzłami, minimum 20 px marginesu w kontenerze. Do tego dwanaście stylów, czternaście typów UML, ponad czterdzieści ikon marek jako SVG i animowany GIF: 5,75 sekundy, 20 klatek na sekundę, w pętli.

Brzmi jak reklama, więc od razu trzy rzeczy, na których wywróciłem się w pierwszej godzinie.

Nazwa kontenera potrafi wywalić render. Nazwałem sekcję „Kontrola" i dostałem błąd EDGE_BEND_BUDGET: 4>2. Nagłówek kontenera stał się przeszkodą, więc strzałka próbowała go objechać czterema zgięciami przy budżecie dwóch. W przykładach dołączonych do skilla ta sekcja nazywa się trzyliterowym „Obs" i teraz wiem, że to nie przypadek. Polskie nazwy są dłuższe od angielskich i to realne ograniczenie tego narzędzia.

Walidator nie widzi wszystkiego. Diagram przeszedł wszystkie automatyczne kontrole, a na obrazku podpisy w cylindrach nachodziły na krawędzie kształtu. Wyszło dopiero przy oglądaniu wyeksportowanego PNG - i dlatego ten krok jest w instrukcji skilla obowiązkowy.

Layout jest ciasno spasowany. Chciałem podnieść wysokość węzłów, żeby zrobić miejsce na drugą linię tekstu, i dostałem CONTAINER_GUTTER: 6.0>20.0. Łatwiej skrócić tekst niż powiększyć kształt.

Żadna z tych trzech rzeczy nie jest wadą pomysłu. To koszt tego, że narzędzie ma twarde reguły - a ja ten koszt płacę chętnie, bo w zamian dostaję diagram, który nie wygląda na wygenerowany.

Ten sam schemat, cztery razy

Wszystkie cztery narzędzia dostały to samo zadanie: pokaż drogę wpisu na tym blogu. Od pomysłu w kopalni, przez research i tekst, przez diagram i grafiki maskotki, na stronę i dalej do trzech sieci społecznościowych. Każde w wersji jasnej i ciemnej.

Mermaid

Zero instalacji, dziesięć linijek tekstu. Widać jednak, że wszystkie pudełka są identyczne, a odstępy przypadkowe. To schemat funkcjonalny, nie redakcyjny.

D2

Ten sam nakład pracy co w Mermaidzie, a układ policzony przez ELK. Linie nie walczą z pudełkami, całość wygląda jak z dokumentacji, nie z generatora.

Generator obrazów

Tutaj nie ma pliku do porównania i to jest właśnie pointa tego etapu. Prompt z sekcji wyżej daje ładny kadr, ale bez podpisów, więc nie mówi nic o kolejności kroków. Grafika owszem, diagram nie.

fireworks-tech-graph

I to samo w ruchu. Połączenia rysują się w kolejności semantycznej, potem diagram zostaje w stanie pracy z płynącymi kreskami:

Różnica względem D2 nie polega na tym, że jest ładniej. Polega na tym, że kształt niesie znaczenie: baza danych to cylinder, agent ma podwójną obwódkę, terminal ma pasek okna, a legenda mówi, co znaczy każdy kolor strzałki.

Pułapka, która kosztowała mnie dziś dwadzieścia minut

Renderowałem Mermaida lokalnie, żeby zobaczyć wynik, i dostałem osiem pustych prostokątów. Bez jednego napisu. Zdążyłem zmienić konfigurację dwa razy, zanim sprawdziłem to, co należało sprawdzić od początku: jak plik wygląda w przeglądarce.

W przeglądarce był w porządku. Tekst siedział w SVG cały czas, tylko lokalny konwerter go nie rysował.

Wniosek na przyszłość: jeśli grafika ma trafić na stronę, sprawdzaj ją w przeglądarce, a nie w konwerterze. Najprostszy test to plik HTML z jednym tagiem obrazka i zrzut ekranu z przeglądarki uruchomionej bez okna.

Czym dziś robię co

Dwa narzędzia z tej czwórki zostały mi na stałe: D2 do wpisów, fireworks do rzeczy, które mają wyglądać poważnie i ruszać się na LinkedInie. Mermaid został tam, gdzie jest wygodny, czyli w notatkach. Generator obrazów robi ilustracje i nie udaje schematów.

Jedno pytanie przed każdym diagramem

W moim generatorze wpisów blogowych diagramu domyślnie nie ma. Trzeba go uzasadnić, odpowiadając twierdząco na pytanie: czy czytelnik dowie się z tego rysunku więcej niż z dobrze napisanego akapitu.

Większość diagramów w artykułach tego pytania nie przechodzi. Są wypełniaczem, który ma pokazać, że autor się starał. Cztery narzędzia w trzy miesiące niczego tu nie zmieniły - zmieniły tylko to, jak szybko potrafię zrobić diagram, który przechodzi.

Narzędzia są wtórne. Pytanie jest pierwsze.