# diagram-design - **Autore:** Cathryn Lavery (LittleMight) - **Repository:** [cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design) (licenza MIT) - **Sorgente:** [skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) (versione 2.6) - **Sito e galleria:** [diagramdesign.dev](https://diagramdesign.dev) · [galleria dei diagrammi](https://cathrynlavery.github.io/diagram-design/) - **Pagina su skills.sh:** [cathrynlavery/diagram-design/diagram-design](https://skills.sh/cathrynlavery/diagram-design/diagram-design) - **Diffusione (ottobre 2026):** circa 14.300 installazioni; il repository ha circa 56.800 stelle su GitHub - **Controlli di sicurezza su skills.sh:** Gen Agent Trust Hub, Socket e Snyk superati, senza avvisi ## A cosa serve Fa disegnare all'agente diagrammi curati nello stile della tua grafica, invece dei soliti riquadri arrotondati generici. Ogni diagramma è un unico file HTML con SVG incorporato, che si apre con un doppio clic. Lo stile è editoriale e prevede un solo colore d'accento per uno o due elementi chiave, linee sottili, nessuna ombra e coordinate su una griglia di 4 pixel. Può prendere colori e font dal tuo sito e rifare in questo stile anche diagrammi già esistenti in draw.io, Mermaid ed Excalidraw. ## Cosa fa ### Quando si attiva Quando chiedi un diagramma a parole, per esempio: - "Fammi un diagramma di architettura della mia app: frontend, backend, database, cache Redis"; - "Mi serve un quadrante con i progetti del secondo trimestre per impatto e sforzo"; - "Dammi una sequenza di una chiamata con bearer token e refresh su 401"; - "Onboard diagram-design to https://tuosito.com" (per prendere palette e font del sito); - "Redraw this drawio file for my deck" (rifare un diagramma esistente), oppure l'esportazione di un diagramma in PNG o SVG. Il `SKILL.md` elenca 45 tipi di visual (il README dice 45; la descrizione del repository su GitHub dice 44). Tra i principali: architettura, flowchart, sequence, macchina a stati, ER, timeline, swimlane, quadrante, radar, ciclo, albero, organigramma, Venn, piramide/funnel, grafici (barre, linee, scatter, treemap, heatmap, waterfall), Gantt, Sankey, Wardley map, kanban, user journey, UML a classi, schema di database. ### Come lavora 1. **Controlla lo stile (primo uso in un progetto).** Se lo style guide è ancora quello predefinito, si ferma e ti chiede se personalizzarlo: da URL di un sito, da una skill installata, da una cartella locale o design system, incollando i token a mano, tenendo il predefinito, o caricando un profilo salvato. 2. **Sceglie il tipo.** Se conta il comportamento (code, colli di bottiglia, confini di fiducia, difese a strati), sceglie prima uno dei nove *semantic pattern* e poi il tipo di diagramma più vicino per il layout. Per un caso normale carica il `SKILL.md` e il riferimento di quel solo tipo. 3. **Dichiara il piano prima di disegnare:** tipo, formato, dimensione e cosa verrà tagliato per stare nei limiti. Salta la pausa solo se la richiesta specifica già tutto. 4. **Disegna** rispettando i limiti di complessità (al massimo 9 nodi, 12 frecce, 2 elementi con l'accento, 2 note), altrimenti propone di dividere in due diagrammi, e le sei regole obbligatorie sui connettori (solo angoli retti, spazio tra etichetta e linea, niente sovrapposizioni, punti di attacco distinti, nessun passaggio dietro a un riquadro, maschere prima dei nodi). 5. **Controlla il risultato** con una lista di verifica e con `python3 scripts/self_check.py `, che controlla accessibilità dell'SVG, file autonomo e contenuto dentro il `viewBox`. 6. **Produce un unico file `.html`:** CSS incorporato, SVG in linea, nessuna immagine esterna. Ogni SVG ha `role="img"`, `` e `<desc>`. Il principio di fondo è che la mossa migliore è di solito togliere: se una tabella o un paragrafo spiegano la stessa cosa, la skill suggerisce di non disegnare. ### Personalizzare lo stile (onboarding) Senza personalizzazione i diagrammi escono in nero e arancio ("tangerine"). Con *"onboard diagram-design to https://tuosito.com"* l'agente legge la home, ricava i colori e i font, li assegna ai ruoli (`paper`, `ink`, `muted`, `accent`, `link`, font del titolo, dei nodi e dei sottotitoli), ti mostra le differenze e, dopo la tua conferma, scrive i valori in `references/style-guide.md`. Controlla anche il contrasto WCAG AA e, se non basta, propone un valore corretto. | Rilevato dal sito | Diventa | |---|---| | sfondo di `<body>` | `paper` | | colore del testo principale | `ink` | | testo secondario | `muted` | | card o contenitori | `paper-2` | | colore del marchio più usato | `accent` | | font di `<h1>` / `<body>` / `<code>` | font del titolo / dei nodi / dei sottotitoli | Per più clienti puoi salvare un **profilo** con nome (in `~/.diagram-design/profiles/`) e aggiungere a ogni progetto un file `.diagram-design` con `profile: <nome>`. ### Importare ed esportare - **Import:** rifà (non converte) file `.drawio`, `.mmd`/`.mermaid` o blocchi Mermaid nel Markdown, e `.excalidraw`. Tiene i contenuti (componenti, relazioni, raggruppamenti, direzione) e scarta coordinate, colori e font della sorgente. Si regola con quattro opzioni: formato (`html`, `svg`, `png`, `html+png`), dimensione (`doc-inline`, `slide-16x9`, `social-og`, `print-a4-landscape`, `fit` e altre), livello di dettaglio (`faithful` fino a 24 nodi, `balanced` fino a 12, `simplified` fino a 7) e destinatari (`engineer`, `mixed`, `executive`, che cambiano le parole e non il numero di nodi). Alla fine riporta un elenco di cosa è stato unito, ridotto o scartato. - **Export:** su richiesta, salva il solo diagramma come SVG o PNG (`scripts/export_svg.py`, `scripts/export_png.py`). L'export non parte mai da solo. Il PNG usa Playwright (`pip install playwright && playwright install chromium`). - **Animazione (facoltativa):** modalità `none` (predefinita), `reveal`, `step`, `loop`, con il fotogramma statico sempre completo e controlli nascosti se il sistema chiede meno movimento. ### Da sapere - **Rete:** per impostazione predefinita ogni diagramma carica i font Instrument Serif, Geist e Geist Mono da Google Fonts, che è l'unica richiesta di rete. Chiedendo "system fonts" il file non fa alcuna richiesta. L'onboarding da sito fa scaricare all'agente alcune pagine di quel sito, e solo se lo chiedi. Secondo PRIVACY.md non ci sono server, account né telemetria. - **Script eseguiti:** richiede Python 3 per `self_check.py` e per gli estrattori degli import (`drawio_extract.py`, `mermaid_extract.py`, `excalidraw_extract.py`). Il PNG richiede anche Playwright con Chromium. Il README e il `SKILL.md` descrivono gli script come locali; i file importati vanno trattati come dati non fidati, e la skill lo prevede. - **Limiti dichiarati nel README:** la qualità dipende dal modello e lo stesso prompt può dare layout diversi; il risultato non è un formato sorgente modificabile (niente testo da confrontare in una pull request né canvas da trascinare). Per documenti in Git che cambiano a ogni sprint, il README consiglia Mermaid. Non va usata per elenchi, confronti di soli attributi o diagrammi con una sola forma. - **Comandi in più solo con il plugin:** `/diagram-design:export-diagram`, `import-drawio`, `import-mermaid`, `import-excalidraw`, `profile` e `doctor` (in Pi senza prefisso). Con `npx skills` si installa solo la skill, senza questi comandi; si può chiedere tutto anche a parole. - **Fonte ufficiale:** il README avverte che le versioni ufficiali vengono solo da questo repository; elenchi con altro nome sono copie non ufficiali. ## Installazione Il README raccomanda il marketplace quando l'agente ne ha uno, perché dà aggiornamenti e comandi; `npx skills` installa solo la skill. Non usarli entrambi sullo stesso agente. ### Claude Code Nella sessione, come due messaggi separati: ```text /plugin marketplace add cathrynlavery/diagram-design /plugin install diagram-design@diagram-design ``` Per gli aggiornamenti automatici: `/plugin` → **Marketplaces** → **diagram-design** → **Enable auto-update** (per i marketplace di terze parti è disattivato di default); poi `/reload-plugins` quando richiesto. ### Codex ```bash codex plugin marketplace add cathrynlavery/diagram-design codex plugin add diagram-design@diagram-design ``` Si aggiorna all'avvio; per forzarlo: `codex plugin marketplace upgrade diagram-design` e una nuova sessione. ### Claude Code e Codex (solo la skill) ```bash npx skills add cathrynlavery/diagram-design -g -a claude-code -a codex ``` | Opzione | Significato | |---|---| | `-g` | installazione globale (`~/.claude/skills/`, `~/.codex/skills/`); senza, solo nel progetto corrente | | `-a <agente>` | agente di destinazione, ripetibile | | `--copy` | copie indipendenti invece dei collegamenti simbolici (con più agenti il programma chiede il metodo e consiglia i collegamenti) | | `-y` | salta le domande di conferma | Il comando installa l'intera cartella della skill (`references/`, `assets/`, `scripts/`). Dopo l'installazione riavvia la sessione. Si può richiamare chiedendo un diagramma a parole; Claude Code la usa da solo quando la richiesta è pertinente. Gestione: ```bash npx skills list -g # skill installate npx skills update diagram-design # aggiornamento npx skills remove diagram-design # rimozione ``` Per il plugin usa i comandi `plugin` del rispettivo agente. Il README segnala che un'installazione con `npx skills` esistente non passa da sola al marketplace: va rimossa prima di reinstallare con il plugin. ### App desktop di Claude e ChatGPT Il README non documenta il caricamento come ZIP nelle app desktop di Claude e ChatGPT (PRIVACY.md cita ChatGPT tra gli agenti in cui la skill può essere installata, senza istruzioni). Si può provare con lo ZIP della sola cartella della skill: ```bash git clone --depth 1 https://github.com/cathrynlavery/diagram-design.git cd diagram-design/skills && zip -r ~/diagram-design.zip diagram-design ``` Lo ZIP deve contenere la cartella `diagram-design/` con dentro `SKILL.md`, `references/`, `assets/` e `scripts/`. **Claude (desktop o web)** 1. Attiva l'esecuzione del codice in **Settings → Capabilities**. 2. Vai in **Customize → Skills → + → Create skill → Upload a skill** e scegli lo ZIP. 3. Attiva l'interruttore della skill. **ChatGPT (desktop o web)** 1. Vai in **Skills** nella barra laterale, poi **Create → Upload from your computer**, e scegli lo ZIP o la cartella. 2. Attendi l'analisi di sicurezza di ChatGPT. 3. Richiamala con `@` nella chat. Le skill personali caricate su desktop e web non si sincronizzano: vanno caricate su ciascuna. > **Limite:** la skill è pensata per agenti che lavorano su file locali. Nelle app di chat non ho verificato se la dimensione dello ZIP, gli script Python, il controllo con `self_check.py` e l'export PNG (che richiede Playwright) funzionino, e probabilmente l'onboarding da un sito e il profilo salvato in `~/.diagram-design/` non sono utilizzabili. Il disegno vero e proprio dei diagrammi in HTML dovrebbe restare possibile. ## Fonti - [README di cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - [SKILL.md di diagram-design](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) - [PRIVACY.md di diagram-design](https://github.com/cathrynlavery/diagram-design/blob/main/PRIVACY.md) - [diagram-design su skills.sh](https://skills.sh/cathrynlavery/diagram-design/diagram-design) - [Use skills in Claude – Claude Help Center](https://support.claude.com/en/articles/12512180-use-skills-in-claude) - [Skills in ChatGPT – OpenAI Help Center](https://help.openai.com/en/articles/20001066-skills-in-chatgpt)