Diagrammes Lisibles
Une page. Une question. Un schéma que le lecteur comprend du premier coup d'œil.
Cette compétence fusionne deux compétences amont et ajoute la couche manquante :
| Couche | Origine | Ce qu'elle apporte |
|---|---|---|
| Pipeline de spécifications validées | Archify | JSON intermédiaire → rendu déterministe → contrôles machine |
| Système de conception éditorial | diagram-design | Tokens papier/encre/accent, rampe typographique, connecteurs orthogonaux, retenue éditoriale |
| Contrat de compréhension | cette compétence | Titre en forme de conclusion, phrase clé, chemin de lecture numéroté, légende, légende descriptive — et un vérificateur qui fait échouer la page lorsqu'ils sont absents |
Aucune des deux compétences parentes ne valide qu'un humain peut lire le résultat. C'est tout l'objet de cette compétence.
0. Le contrat — répondez à quatre questions avant de dessiner
- Qui le lit ?
executive/mixed/engineer— cela détermine le vocabulaire, pas seulement le ton. - Que doit-il savoir après 10 secondes ? Une phrase. Elle devient la phrase clé.
- Où les yeux commencent-ils, et dans quel ordre se déplacent-ils ? 2 à 5 arrêts. Ils deviennent le chemin numéroté.
- Que pourraient-ils mal comprendre si le schéma était paresseux ? C'est le travail de la légende, et la raison pour laquelle le schéma vaut la peine d'être dessiné.
Si une réponse est inconnue et que l'utilisateur est joignable, posez une question — sinon, indiquez votre hypothèse dans le pied de page de la légende. Si un paragraphe ou un tableau de trois lignes l'enseignerait mieux, ne dessinez pas.
1. Pipeline
Tous les chemins sont relatifs au dossier de cette compétence — le répertoire qui contient
ce SKILL.md. Claude Code, Codex, Cursor et DSH signalent tous ce dossier comme le
répertoire de base de la compétence ; un plugin DSH l'indique explicitement à la fin de
ce fichier. Dans un checkout de dépôt, il s'agit de skills/readable-diagrams/.
# 1. écrire une spécification (voir references/spec-schema.md)
# 2. rendre
python3 scripts/render.py spec.json -o page.html --json
# 3. exécuter les deux contrôles ; un code de sortie non nul n'est jamais un succès
python3 scripts/self_check.py page.html
python3 scripts/comprehension_check.py page.html
self_check.py valide l'hygiène SVG (contrat d'accessibilité, sécurité du fichier unique, contenu à l'intérieur du viewBox). comprehension_check.py valide la lisibilité (titre/phrase clé/légende descriptive/légende/chemin de lecture, budget d'accentuation, budget de nœuds, seuils typographiques, contraste, connecteurs orthogonaux). Les deux doivent réussir avant la livraison.
Les échecs sont des preuves ordinaires, pas un jugement : lisez le message, réparez la spécification ou la page, réexécutez. Ne corrigez jamais manuellement le HTML généré — régénérez à partir de la spécification pour que la page reste reproductible.
2. Choisir le type
| Si le lecteur doit voir… | Type | Moteur |
|---|---|---|
| Composants et ce qui se connecte à quoi | architecture | ✅ spec |
| Étapes, branches, une décision | flow | ✅ spec |
| États et transitions | state | ✅ spec |
| Messages entre parties, dans le temps | sequence | ✅ spec |
| Événements sur une horloge | timeline | ✅ spec |
| Contenance / décomposition | tree | ✅ spec |
| Bandes d'abstraction, une pile | layers | ✅ spec |
| Grandeurs par catégories | bar | ✅ spec |
| Positionnement sur deux axes / priorité | quadrant | ✅ spec |
| Lignes, nuages de points, aires, Sankey, radar, heatmap, Gantt, Venn, entonnoir, parcours… | rédigé à la main | ✍️ references/hand-authoring.md |
Le catalogue complet de 40+ types, avec le motif sémantique qui devrait guider le choix, se trouve dans references/type-router.md. Lisez-le lorsque le type n'est pas évident.
Règle d'ambiguïté : choisissez l'axe dominant, pas deux mises en page. Si deux types conviennent tous les deux, dessinez celui dont la grammaire correspond à la question du lecteur, et répartissez le reste en une paire vue d'ensemble + détail.
3. Écrire la spécification, pas le HTML
La spécification est l'objet lisible ; le HTML est un produit de construction. Spécification minimale viable :
{
"type": "architecture",
"meta": {
"title": "一次下单请求如何穿过网关到达数据库",
"eyebrow": "ARCHITECTURE · 架构",
"takeaway": "写路径只有一条；风控与通知是旁路，不阻塞下单。",
"caption": "从左往右是请求方向。实线同步，虚线异步；编号是建议阅读顺序。",
"audience": "mixed",
"size": "fit",
"reading_path": ["client", "gateway", "orders", "pg"],
"source": "示意结构，非实测"
},
"zones": [{"id": "edge", "label": "EDGE"}],
"nodes": [
{"id": "client", "label": "客户端", "sublabel": "web · app", "kind": "input", "zone": "edge"},
{"id": "gateway", "label": "API 网关", "sublabel": ":443", "kind": "backend", "zone": "edge"},
{"id": "orders", "label": "订单服务", "kind": "focal"},
{"id": "pg", "label": "订单库", "sublabel": "PostgreSQL", "kind": "store"}
],
"edges": [
{"from": "client", "to": "gateway", "label": "HTTPS", "variant": "accent"},
{"from": "gateway", "to": "orders", "label": "POST /orders", "variant": "accent"},
{"from": "orders", "to": "pg", "label": "写入", "variant": "accent"}
]
}
Liste complète des champs, formes par type, contrôles de mise en page (col, row, zones, couloirs) et exemples travaillés : references/spec-schema.md.
Tailles : fit (par défaut — la page suit le contenu), doc-inline (960×600), doc-wide (1280×720), slide-16x9, slide-4x3, social-og, social-square, print-a4-landscape, print-a3-landscape. Utilisez un préréglage fixe uniquement lorsque la figure atterrit quelque part de fixe (un diaporama, une feuille imprimée) ; sinon fit maintient la police à une taille lisible.
Thèmes : light (par défaut) ou dark.
4. Les règles de compréhension
Le vérificateur en applique la plupart. Les autres relèvent du jugement de l'auteur.
- Le titre énonce la conclusion, pas la catégorie. « 一次下单请求如何穿过网关到达数据库 », pas « 订单系统架构图 ». ≤60 caractères.
- Une phrase clé. Ce avec quoi le lecteur doit repartir. S'il en faut deux, c'est qu'il y a deux diagrammes.
- La légende descriptive explique comment lire. Direction, unités, ce qui est illustratif, ce qui a été omis.
- 2 à 5 arrêts numérotés. Le badge sur la figure et la liste d'étapes ci-dessous doivent correspondre.
- Un chemin focal. 1 à 2 éléments d'accent. Un troisième accent annule le signal.
- Neuf nœuds est le maximum pour les types structurels. Au-delà : diviser en vue d'ensemble + détail ; ne réduisez jamais la police pour faire rentrer.
- Nommez chaque connexion à moins que la mise en page ne la rende indubitable ; les arêtes non étiquetées en dessous de 60 % sont un avertissement.
- Légende uniquement lorsqu'il y a quelque chose à décoder — et alors elle couvre chaque type utilisé, rien de plus.
- Seuils typographiques : noms de nœuds ≥12 (CJK jamais en dessous de 12), sous-étiquettes ≥9, étiquettes de flèches ≥8. Les préréglages de présentation mettent à l'échelle toute la rampe, pas seulement le titre.
- Contraste ≥4.5:1 pour chaque token de texte sur son arrière-plan réel, dans les deux thèmes.
- Accessible par défaut : `<svg role=