Files
my-skills/skills/diagram-design.md
2026-10-17 19:27:00 +02:00

153 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <file>`, 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"`, `<title>` 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)