Diagram Design: una skill per agenti con un vero design system

Tutti i diagrammi generati dall'IA si somigliano. Lo conosci lo stile: riquadri arrotondati, un gradiente dal viola al blu da qualche parte, ombre su tutto, frecce che finiscono poco prima del bordo del riquadro e un carattere che urla «predefinito». È l'equivalente visivo di un comunicato stampa. Tecnicamente comunica. Nessuno ha voglia di leggerlo.

Diagram Design, una skill per agenti di Cathryn Lavery, attacca quello stile a viso aperto. Il claim è insolitamente brutale per un README: un unico file HTML con SVG incorporato, nel tuo brand, 45 tipi di diagramma, niente ombre, niente pasticci alla Mermaid.

Quest'ultima frase è la tesi. Il progetto non cerca di rendere più intelligente la generazione dei diagrammi. Cerca di far sembrare l'output opera di qualcuno che ha gusto.

Cosa produce davvero

Descrivi il diagramma che vuoi, l'agente scrive un singolo file HTML con SVG inline e tu fai doppio clic. Nessuno step di build, nessuna pipeline di rendering, nessuna dipendenza da un servizio. Il file si apre offline e tra cinque anni sarà identico.

La libreria copre uno spettro davvero ampio: diagrammi di architettura e di delta architetturale, deployment, grafi delle dipendenze, classi UML, schemi di database, flowchart, diagrammi di sequenza, macchine a stati, swimlane, flussi di dati, più tutta una serie di grafici (barre, linee, dispersione, treemap, radar, polare, waterfall, heatmap, sankey) e forme strutturali (alberi, organigrammi, stack di livelli, Venn, piramidi, medaglioni). Per strategia e pianificazione ci sono quadranti, mappe di Wardley, Gantt, timeline, kanban, story map e user journey. C'è perfino un'assonometria esplosa per il lavoro spaziale.

Ogni tipo arriva in tre varianti statiche: minimal chiara, minimal scura e un trattamento editoriale completo. Una piccola incoerenza da segnalare: il titolo del repository dice 44 tipi, il corpo del testo 45, e la galleria è numerata da 01 a 44. Un progetto così ossessionato dalla propria griglia ha un refuso. Capita.

La parte che lo fa funzionare: le regole

Lo sforzo è finito nel design system, ed è espresso in numeri, non in aggettivi.

Un solo colore d'accento per diagramma. L'accento serve a portare l'attenzione su uno o due elementi. Tutto il resto è inchiostro, carta e grigio smorzato. Questa singola regola elimina gran parte del rumore visivo che fa sembrare i diagrammi IA una dashboard del 2016.

Tre caratteri, ognuno con un compito. Instrument Serif per titoli e annotazioni in corsivo. Geist sans per i nomi dei nodi. Geist Mono per le sottoetichette tecniche: porte, URL, tipi di campo. Riservare il monospaziato al dettaglio tecnico è la cosa che un designer che lavora fa d'istinto e che un generatore non fa mai.

Una griglia da 4 pixel. Ogni coordinata, larghezza, spaziatura e padding deve essere divisibile per quattro. L'autrice la definisce la chiave perché l'output non sembri generato dall'IA. Ha ragione, e il motivo è sottile: il disallineamento è la spia. Non ti accorgi che un riquadro è largo 137 pixel. Ti accorgi che qualcosa non torna, e non sai dire cosa.

Filetti, niente ombre, raggio massimo 10px. I bordi fanno il lavoro che di solito fanno le ombre, e lo fanno senza fingere che il diagramma sia un oggetto fisico appoggiato su una superficie.

Densità informativa obiettivo: 4 su 10. È la regola a cui la maggior parte dei team resisterà e per cui la maggior parte dei lettori li ringrazierà. Il principio dichiarato: la mossa di qualità più alta è di solito la cancellazione.

Anche l'accessibilità non è un ripensamento. L'output SVG porta role="img", aria-labelledby ed elementi title/description; le preferenze di movimento ridotto vengono rispettate; il contrasto WCAG AA (4.5:1 per il testo, 3:1 per i segni chiave) è imposto in CI. La palette predefinita è nero pece e mandarino su carta bianco fumé.

L'onboarding del brand è la funzione sottovalutata

Gli dai l'URL del tuo sito. Estrae colori e font e li mappa su ruoli semantici: paper, ink, muted, accent, link. Poi ti consegna una ricevuta di fedeltà che dice cosa ha dedotto e dove ha tirato a indovinare.

Quest'ultima parte conta molto più dell'estrazione. Gli strumenti di brand extraction di solito ti porgono una palette e stanno zitti. Mostrarti l'inferenza è ciò che ti permette di correggerla prima di produrre quaranta diagrammi con l'arancione sbagliato.

C'è anche una via d'importazione: puntalo a un file Mermaid, draw.io o Excalidraw e ridisegna il diagramma nel design system, con quattro manopole — formato, dimensione, dettaglio, pubblico — e un registro di fedeltà. Migrare un wiki pieno di grafici Mermaid è esattamente il caso d'uso per cui è nato.

Dove va bene e dove no

L'installazione è volutamente noiosa. npx skills add cathrynlavery/diagram-design per qualsiasi cosa legga Agent Skills; comandi del marketplace dei plugin per Claude Code, Codex, GitHub Copilot e Factory Droid; symlink o import di sottodirectory per Cursor, Cline, Gemini CLI, Windsurf, Amp, Zed, Kiro e OpenCode. Ci sono comandi slash per export, import, profiling e un controllo doctor.

L'autrice è schietta sui limiti in modo rinfrescante, e sono i limiti giusti.

La qualità dipende dal modello. Lo stesso prompt può produrre due layout diversi, perché quello che ottieni è geometria generata, non un template riempito. Non c'è sorgente modificabile: nessuna tela da trascinare, nessun testo da mettere in diff in una pull request. Per documentazione che cambia ogni settimana consiglia Mermaid: si può fare il diff, GitHub lo renderizza nativamente, e questo vale più della bellezza.

Pone anche una domanda che più autori di strumenti dovrebbero porsi: il lettore ricaverà da questo diagramma più che da un paragrafo? Se il «diagramma» è un riquadro con un'etichetta, scrivi la frase. Se stai confrontando due elenchi, usa una tabella. Se vuoi ASCII art per un terminale, questo non è lo strumento.

L'output è un file, non un servizio

C'è una decisione di design che sembrerà più intelligente ogni anno: il deliverable è un singolo file HTML con SVG inline, e si apre offline. Nessun account, nessuno script da incorporare, nessuna dipendenza da un fornitore che magari il trimestre prossimo ritocca il prezzo dell'API. Mettilo in un repository, allegalo a un ticket, stampalo, spediscilo a un cliente che usa un portatile blindato.

Per chiunque abbia visto un SaaS di diagrammi venire acquisito e poi degradarsi, non è una funzione da poco. È la differenza tra un artefatto e un abbonamento.

Il compromesso è che non puoi modificarlo come modificheresti una tela. Niente drag and drop, niente pannello livelli, niente stack di undo. Se il layout è sbagliato, rigeneri o correggi le coordinate a mano — e siccome tutto poggia su una griglia da 4px, la modifica manuale è sopravvivibile in un modo che in un documento libero non sarebbe.

Come giudicare una skill per diagrammi in dieci minuti

Chiedile qualcosa di forma scomoda: un sistema con un nodo ovviamente importante, tre servizi di supporto e un database che tutti dimenticano. Un buon output usa l'unico accento per segnare il nodo importante e lascia che il resto arretri. Un cattivo output colora tutto, perché colorare tutto è quello che fanno i generatori quando non hanno priorità.

Poi chiedi lo stesso diagramma due volte. Output identico significa che stai guardando un template. Output diverso significa che stai guardando generazione, che è più onesto ed è anche il motivo per cui il modello che usi conta.

Infine, guarda i numeri. Conta gli spazi. Se non sono multipli di quattro, i vincoli vengono ignorati, e probabilmente anche il resto del design system.

L'argomento vero

Esiste una versione di questo progetto che sarebbe stata solo un prompt di stile. «Fallo editoriale, senza ombre, minimale». Quella versione avrebbe prodotto spazzatura incoerente, perché i prompt non sopravvivono al contatto con un diagramma di architettura da quaranta nodi.

Ciò che rende interessante Diagram Design è che codifica il gusto come vincoli che una macchina può verificare: divisibile per quattro, un solo accento, tre caratteri, rapporto di contrasto, niente ombre. L'estetica non sta nel modello. Sta nella specifica.

È un'idea più trasferibile della skill stessa. Qualunque cosa usi per generare visual — diagrammi, slide, copertine, thumbnail — la differenza tra un output che sembra progettato e uno che sembra generato è di solito una breve lista di regole che qualcuno si è preso la briga di scrivere.