Diagram Studio
Transformez une spécification JSON en un diagramme net. L'aspect est entièrement configurable :
- Dessiné à la main : wobble rough.js et polices manuscrites.
- Vectoriel net : wobble nul, polices sans ou serif, ombres douces.
- Tout entre les deux.
Tout le texte est converti en contours, donc le SVG et le PNG sont identiques partout. Un linter détecte les chevauchements, le texte débordant, les étiquettes sur les bordures et les flèches qui traversent les boîtes.
Tout est inclus : Node 18+ est la seule exigence, sans npm install et sans réseau.
SKILL_DIR ci-dessous signifie le chemin absolu de ce dossier de compétence (le dossier qui contient ce fichier).
node SKILL_DIR/scripts/render.mjs diagram.json --out out/ # → out/diagram.png (2x), .svg, .report.json, .tiles/
0. Exécution dans Codex, Claude Code ou un autre agent
- SKILL_DIR :
- Dans Codex, développez le chemin court de la compétence avec la table des racines de compétences (ex.
r0/diagram-studio/SKILL.md→~/.codex/skills/diagram-studio). - Dans Claude Code, c'est généralement
~/.claude/skills/diagram-studio. - Appelez toujours les scripts avec ce chemin absolu.
- Dans Codex, développez le chemin court de la compétence avec la table des racines de compétences (ex.
- Regarder les images est obligatoire : l'originale, la grille, les tuiles et la comparaison.
- Codex : utilisez l'outil
view_imageavec le chemin du PNG.render.mjsécritname.preview.png(≤ 1400 px) pour cela, donc il n'est pas nécessaire de redimensionner l'image vous-même ; utilisezname.tiles/*.pngpour les détails. - Claude Code : utilisez l'outil Read.
- Ne jugez jamais un rendu uniquement à partir de la sortie du linter.
- Codex : utilisez l'outil
- Compatible sandbox :
- Seul
nodeest nécessaire. Il n'y a pas d'appels réseau et pas d'installations. - Les sorties vont dans
--out; gardez-les dans l'espace de travail, par exemple./diagram-out. - La conversion WebP/HEIC écrit dans le dossier temporaire du système.
- Seul
- L'utilisateur a collé une image au lieu de donner un chemin : si vous pouvez voir un chemin de pièce jointe, utilisez-le. Sinon, demandez le chemin du fichier, car les outils ont besoin d'un fichier réel.
- Finalisation : listez les chemins absolus du PNG, SVG et JSON afin que l'utilisateur puisse les ouvrir.
1. Choisissez le travail
| L'utilisateur veut | Travail | Lire ensuite |
|---|---|---|
| "Rendre cette image plus claire / haute résolution / propre", "redessiner / reconstruire / 复刻 / 高清重建 ceci" | A. Reconstruction à partir d'une image. Fidélité d'abord : conserver le style de l'original sauf indication contraire | references/rebuild-from-image.md (obligatoire) |
| "Embellir / ranger / 美化 ce diagramme" | A + polissage. Identique à A, puis améliorer la hiérarchie, l'espacement et l'alignement | references/rebuild-from-image.md |
| Un nouveau diagramme à partir d'une description, d'un code ou de notes | B. Nouveau diagramme | references/spec.md |
| Un aspect différent ("faites-le dessiné à la main", "corporate plat", "blueprint", "pour un article") | C. Restylage | references/style-guide.md |
Pour une image donnée, correspondre à son style par défaut : le dessiné à la main reste dessiné à la main, le plat reste plat, et ses couleurs et catégorie de police restent telles quelles. Ne modifiez l'aspect que lorsque l'utilisateur le demande. Les préréglages sont des points de départ, pas des limites ; styleOverrides, les palettes personnalisées et les fichiers de polices personnalisées ("fonts") peuvent reproduire presque tous les aspects. Ne demandez le niveau de fidélité que lorsque la demande est vraiment ambiguë, par exemple "embellir" sans style de référence. Sinon, par défaut, fidèle + plus clair.
Commencez par le modèle le plus proche dans templates/ : copiez-le dans votre dossier de travail et modifiez la copie. Les aperçus sont dans assets/gallery/. Un modèle est un motif, pas un contenu : remplacez tout son texte et conservez exactement les sauts de ligne et les flèches comme dans votre source. --expect détecte les oublis et les changements de formulation.
| Modèle | Montre |
|---|---|
dense-rebuild.json | Reconstruction d'une image d'architecture dense : coordonnées explicites, cartes, panneaux, connecteurs fusionnés, étiquettes en ligne |
pipeline-rag.json | Pipeline gauche-droite : lignes avec connect, rightOf, panneaux à ajustement automatique |
layered-architecture-zh.json | Architecture chinoise en couches : lignes below empilées, flèches en éventail, cylindres |
flowchart-decision.json | Organigramme : pilule, losange, branches oui/non, flèches de retour |
agent-loop.json | Cycle : flèches courbes, badges, hub elliptique |
auto-layout.json | Sans coordonnées : disposition automatique ELK avec groupes |
2. La boucle (pour chaque travail)
-
Inventoriez d'abord. Listez chaque chaîne de texte textuellement (enregistrez-la dans
texts.txt, une par ligne), chaque nœud, chaque flèche (de → vers, étiquette) et chaque groupe. Rien n'est inventé ou supprimé. -
Écrivez
name.json, en partant d'un modèle. -
Rendu :
node SKILL_DIR/scripts/render.mjs name.json --out OUT --expect texts.txt -
Corrigez chaque ERREUR ; chacune vient avec un
→correctif concret. Corrigez les AVERTISSEMENTS sauf s'ils sont intentionnels, et réduisez au silence ceux qui sont intentionnels avec"ignore": ["code"]sur cet élément ou cette flèche. -
Regardez
OUT/name.pngetOUT/name.tiles/*.png, et comparez avec l'original (scripts/compare.mjs). Passez en revue la liste de contrôle dansprompts/visual-review.md; le linter ne peut pas juger du sens, de l'équilibre ou de la fidélité. -
Répétez les étapes 3 à 5 jusqu'à ce qu'il y ait 0 erreurs et que le résultat soit bon (généralement 2 à 4 cycles).
-
Livrez :
name.png: 2x ; utilisez--scale 3pour l'impression.name.svg: vectoriel.name.json: conservé pour des modifications ultérieures.
Ajoutez une ligne sur ce que vous avez conservé et ce que vous avez amélioré.
3. Spécification en 60 secondes
{
"canvas": { "width": 1600 },
"style": "marker",
"title": "Checkout Service",
"subtitle": "{blue:clients} · {purple:services} · {green:data}",
"elements": [
{ "id": "web", "title": "Web app", "icon": "app-window", "x": 120, "y": 220 },
{ "id": "api", "title": "API", "color": "purple", "emphasis": true, "rightOf": "web", "gap": 160,
"lines": ["`POST /checkout`", { "text": "validates cart", "muted": true }] },
{ "id": "db", "type": "cylinder", "title": "Orders DB", "color": "green", "below": "api", "gap": 120 },
{ "id": "core", "type": "panel", "title": "Backend", "color": "purple", "contains": ["api", "db"] },
{ "id": "n1", "type": "note", "text": "Idempotent by **order id**", "rightOf": "core", "gap": 40 }
],
"arrows": [
{ "from": "web", "to": "api", "label": "HTTPS" },
{ "from": "api", "to": "db", "label": "INSERT", "color": "green" }
]
}
-
Types d'éléments :
box(par défaut),pill,ellipse,circle,diamond,cylinder,note,card,panel,text,icon,badge,image,path(forme SVG personnalisée), plus les assistants de dispositionrow,columnetgroup. -
Positionnez chaque élément avec l'un de ces éléments :
x/ypour le coin supérieur gauche, oucx/cypour le centre.below/above/rightOf/leftOfplusgap.contains, qui ajuste automatiquement un panneau autour de ses enfants.
La taille est automatique. Définissez
w/hpour correspondre exactement à un original. -
Texte :
titleest en gras et\ncoupe la ligne. Leslinessont des lignes de corps. Balisage dans le texte :**gras**`code`(utilise la police de code){green:span}et{muted:span}->(dessiné comme un glyphe de flèche)
Le chinois et l'anglais se mélangent librement. Par élément, vous pouvez définir
size,textSize,font,textColoretalign. -
Couleur avec une famille (
blue purple green orange red teal yellow pink gray navy), une nuance (blue.tint),#hexou un nom CSS simple tel quewhite, défini viacolor,fill,strokeettextColor. -
Les flèches connectent
fromàto:- Épinglez un côté et glissez le long de celui-ci avec
"id.right"ou"id.right+20". - Étiquettes :
label, placé aveclabelPos(above,below,left,rightouinline) et déplacé aveclabelAt. - Aspect :
dash,color,widthethead(end,start,bothounone). - Chemin : points
via,points(une polyligne exacte) ou"route": "curve".
- Épinglez un côté et glissez le long de celui-ci avec
Chaque clé se trouve dans references/spec.md.
4. Aspect : style, palette, police, effets
-
Préréglages de style :
- Dessiné à la main :
marker(par défaut),neat,excalidraw,sketchy,whiteboard,pencil,blueprint,chalk. - Net :
clean,paper.
Tout champ de préréglage peut être remplacé via
styleOverrides:roughness(0 = lignes parfaitement droites) etbowingfillStyle(solid,hachure,cross-hatch,dotsounone)strokeScale,cornerRadiusshadow(none,softouhard)font,cjkFont,codeFont,background
- Dessiné à la main :
-
Palettes :
marker,pastel,excalidraw,mono,academic,colorblind,modern,blueprint,chalkboard,midnight. Pour reproduire exactement les couleurs d'un original, exécuteznode SKILL_DIR/scripts/palette.mjs original.pnget collez le résultat. -
Polices :
- Manuscrites :
shantell,kalam,caveat,patrick,architects. - Sans :
inter. Serif :serif. Mono :mono. - CJK :
kai(manuscrite),kuaile(ludique),sans-sc(propre). - Vos propres
.ttf/.otf/.woff:"fonts": {"brand": {"regular": "Brand.ttf", "bold": "Brand-Bold.ttf"}}, puis"font": "brand".
- Manuscrites :
-
Catalogues :
assets/gallery/styles.png,palettes.pngetfonts.png. Régénérez-les avecscripts/catalog.mjs. -
Icônes : 1 500+ icônes Lucide. Recherchez avec
node SKILL_DIR/scripts/icons.mjs search 数据库 robot queue, et prévisualisez avecicons.mjs sheet a,b,c. -
Outils pour l'image originale :
grid.mjs: superpose les coordonnées sur l'original. Lisez les étiquettes des axes rouges, jamais les positions des pixels.fontmatch.mjs: montre un exemple de texte dans chaque police à côté d'un recadrage agrandi de l'original.palette.mjs: extrait les couleurs de l'original.crop.mjs: découpez les logos, photos ou captures d'écran à intégrer comme élémentsimage.compare.mjs: révision côte à côte ; ajoutez--crop x,y,w,hpour zoomer les deux images sur la même région.
-
Versions sombres ou alternatives : conservez la même spécification et modifiez uniquement
palette(midnight,blueprintouchalkboard) oustyle, puis effectuez le rendu sous un autre--name. -
Pour les diapositives (PPT, Keynote) :
"canvas": {"aspect": "16:9"}rembourre l'image au rapport de la diapositive."background": "transparent"donne un PNG avec alpha. Le SVG peut également être collé directement.
5. Règles de clarté (toujours applicables)
- Conservez exactement les mots tels que donnés : étiquettes, identifiants de code et termes chinois. N'inventez, ne traduisez et ne supprimez jamais de texte sauf demande contraire.
- Rendez la hiérarchie visible :
- Titre en gras par boîte.
- Identifiants comme corps ou texte
code. - Explications comme texte
muted. - Titres de section dans la couleur de leur section.
- La couleur signifie quelque chose : une famille par région ou rôle, utilisée de manière cohérente. Les étiquettes de flèches héritent de la couleur de leur flèche.
- De l'espace pour respirer :
- ≥ 60 px entre les formes reliées par une flèche étiquetée, ≥ 24 px sinon.
- Panneaux ajustés avec
contains. - Pas d'étiquette sur une bordure.
- Lisible une fois réduit :
- Texte ≥ 18 px (valeurs par défaut : nœud 30, corps 25, étiquette 24).
- Toile de 1400 à 2200 px de large, avec un rapport hauteur/largeur entre 1:2 et 3:1. Le linter avertit dans le cas contraire.
- Longues chaînes de 6+ nœuds : serpentez-les en 2–3 rangées, ou utilisez ELK
"direction": "DOWN", plutôt qu'une seule très longue rangée.
- Peu de croisements et pas de détours. Alignez et réorganisez avant d'ajouter
via. - Polissez, ne reconcevez pas, dans les travaux de reconstruction : améliorez l'alignement, l'espacement et la hiérarchie, mais conservez la topologie, l'ordre de lecture et l'identité du style.
6. Définition de terminé
-
render.mjsrapporte 0 erreur. Tout avertissement restant est intentionnel et réduit au silence avecignore. - Chaque chaîne de l'inventaire est présente et orthographiée exactement (
--expect texts.txtréussit). - Vous avez visualisé le PNG et les tuiles, et pour les reconstructions, comparé côte à côte avec l'original : même structure, même identité de style, plus clair.
- Vous avez livré le PNG, le SVG et le JSON, avec une courte note "conservé / amélioré".
7. Dépannage
node : commande introuvable: installez Node 18+. Rien d'autre n'est nécessaire.- L'entrée WebP, HEIC, BMP ou TIFF est convertie automatiquement lorsque
sips,magick,dwebp,ffmpegou Python PIL est disponible. Sinon, demandez à l'utilisateur un PNG ou JPEG. - Un caractère s'affiche sous la forme
?: les polices incluses couvrent le latin, le chinois GB2312 et les symboles courants. Reformulez-le ou enregistrez une police qui l'a. - Pour chaque code de linter et son correctif, consultez
references/troubleshooting.md.