Flowy, Compétence de Diagramme IA-Native
Flowy génère des fichiers HTML autonomes qui affichent des diagrammes SVG interactifs. Chaque fichier contient du CSS, JavaScript et les données du diagramme intégrés, zéro dépendance : il suffit de double-cliquer pour l'ouvrir dans n'importe quel navigateur.
Emplacements des Fichiers
- Diagrammes :
docs/diagrams/*.html(p. ex.docs/diagrams/upload-flow.html). Créez le dossier lors de la première utilisation ; il peut ne pas encore exister. Si un projet conserve déjà des diagrammes ailleurs, suivez la convention de ce projet à la place. - Modèle HTML :
${CLAUDE_SKILL_DIR}/references/html-template.html, le moteur de rendu canonique, et le seul fichier de référence fourni par cette compétence. Le chemin résout le dossier de cette compétence où qu'elle soit installée (plugin, personnel ou projet), il ne dépend donc pas du projet en cours.
Il n'y a délibérément pas de fichier de schéma, de dossier d'exemples ni d'éditeur visuel. Les versions
précédentes de cette compétence pointaient vers flowy/schema.ts, flowy/examples/,
flowy/editor.html et un dépôt source Flowy sur le disque. Aucun de ceux-ci n'existe, les chemins
étaient obsolètes, et les suivre faisait perdre du temps. Le modèle HTML ci-dessus est la
source de vérité pour la structure ; lisez-le avant d'écrire un diagramme.
Pré-vérification
Avant de créer ou de modifier un diagramme Flowy :
- Lisez
${CLAUDE_SKILL_DIR}/references/html-template.htmlpour avoir le code du moteur de rendu actuel - Listez les diagrammes existants dans
docs/diagrams/pour éviter les conflits de noms - Si vous mettez à jour un diagramme existant, lisez-le d'abord et extrayez l'objet
DIAGRAM
Schéma
Chaque diagramme est un objet JavaScript avec trois champs :
{
meta: { title, description, type, tags[], created, updated },
nodes: [...],
edges: [...]
}
meta
| Champ | Type | Requis | Notes |
|---|---|---|---|
| title | string | oui | Titre lisible par l'humain |
| description | string | non | Ce que montre le diagramme |
| type | string | oui | "flowchart" ou "ui-mockup" |
| tags | string[] | non | Pour l'organisation |
| created | string | non | Date ISO (AAAA-MM-JJ) |
| updated | string | non | Date ISO, mettre à aujourd'hui lors de la création/mise à jour |
nodes
| Champ | Type | Requis | Notes |
|---|---|---|---|
| id | string | oui | unique, snake_case (p. ex. "etape1_upload") |
| type | string | oui | "box", "circle", "diamond", "note", "group" |
| label | string | oui | Texte principal affiché dans la forme |
| sublabel | string | non | Texte secondaire affiché dans l'infobulle au survol |
| position | { x, y } | oui | Coin supérieur gauche en pixels |
| size | { width, height } | oui | Dimensions en pixels |
| style | object | non | Voir les champs de style des nœuds ci-dessous |
| group | string | non | id du nœud de groupe parent (regroupement visuel uniquement) |
Champs de style des nœuds : fill, stroke, strokeWidth, color (texte), fontSize, borderRadius, opacity
edges
| Champ | Type | Requis | Notes |
|---|---|---|---|
| id | string | oui | unique (p. ex. "e_upload_to_extract") |
| source | string | oui | id du nœud source |
| target | string | oui | id du nœud cible |
| label | string | non | texte sur la flèche (p. ex. "oui", "erreur") |
| sourceHandle | string | non | "top", "right", "bottom" (par défaut), "left" |
| targetHandle | string | non | "top" (par défaut), "right", "bottom", "left" |
| style | object | non | Voir les champs de style des arêtes ci-dessous |
Champs de style des arêtes : stroke, strokeWidth, strokeDasharray, markerEnd
Règles de Rendu des Nœuds
| Type | Élément SVG | Détails |
|---|---|---|
| box | <rect> | Coins arrondis via rx/ry depuis borderRadius. Par défaut : 8px |
| circle | <ellipse> | cx = x + largeur/2, cy = y + hauteur/2, rx = largeur/2, ry = hauteur/2 |
| diamond | <polygon> | 4 points : centre-haut, centre-droit, centre-bas, centre-gauche |
| note | <path> | Rectangle avec coin replié (en haut à droite). Taille du repli : 12px |
| group | <rect> | Bordure en pointillés (stroke-dasharray: 6,3). Rendu DERRIÈRE tous les autres nœuds. Étiquette en haut à gauche. Faible opacité |
Règles de Rendu des Arêtes
- Calculez le point source : centre du côté de la poignée spécifié du nœud source (par défaut : bas)
- Calculez le point cible : centre du côté de la poignée spécifié du nœud cible (par défaut : haut)
- Dessinez une courbe de Bézier cubique (commande
C) avec des points de contrôle décalés de 50px dans la direction de la poignée - Ajoutez une pointe de flèche en utilisant une définition
<marker>SVG - Si
strokeDasharrayest défini, rendez en ligne pointillée - Si
labelexiste, rendez-le au point médian de la courbe de Bézier avec un petit rectangle d'arrière-plan blanc derrière
Règles de Disposition
Sens du Flux
- Organigrammes : De haut en bas (par défaut)
- Maquettes UI : De haut en bas dans un conteneur de groupe, annotations à droite
Espacement
- Minimum 70px vertical entre les centres des nœuds
- Minimum 60px horizontal entre les nœuds parallèles
- Rembourrage du groupe : 40px à l'intérieur des limites du groupe
Losanges de Décision
- Branche Gauche = chemin principal / oui
- Branche Droite = chemin secondaire / non / erreur
Notes d'Erreur/Avertissement
- Placez à DROITE du flux principal
- Connectez avec des arêtes rouges en pointillés (
strokeDasharray: "6,3", stroke:#991b1b)
Tailles Standard
| Type | Largeur | Hauteur |
|---|---|---|
| box | 200 | 50 |
| circle | 90 | 40 |
| diamond | 120 | 60 |
| note | 180 | 44 |
Palette de Couleurs
| Objet | Remplissage | Contour | Texte |
|---|---|---|---|
| Actions | #ffffff | #2d6a4f | #1f2937 |
| Actions principales | #d1fae5 | #065f46 | #065f46 |
| Décisions | #fef3c7 | #92400e | #1f2937 |
| Erreurs | #fee2e2 | #991b1b | #991b1b |
| Terminaux | #40916c | #2d6a4f | #ffffff |
| Groupes | #f5f5f2 | #e6e4df | #374151 |
| Info/secondaire | #dbeafe | #1e40af | #1e40af |
| Arêtes par défaut | , | #6b7280 | , |
Structure du Fichier HTML
Chaque fichier HTML Flowy suit cette structure. Lisez la référence du modèle HTML pour le code de travail complet.
<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{titre du diagramme}</title>
<style>
/* Tout le CSS en ligne, barre d'outils, canevas, infobulles, surbrillance de sélection */
</style>
</head>
<body>
<div id="toolbar">
<!-- [Ajuster] [-] 100% [+] Titre badge [Télécharger JSON] -->
</div>
<div id="canvas-wrap">
<svg id="canvas">
<defs><!-- marqueurs de pointe de flèche --></defs>
<g id="diagram-root"></g>
</svg>
</div>
<div id="tooltip"></div>
<script>
const DIAGRAM = { meta: {...}, nodes: [...], edges: [...] };
// Code de rendu + interactivité
</script>
</body>
</html>
Barre d'Outils
- Fixée en haut, 48px de haut, fond blanc, bordure inférieure
- Gauche : Bouton Ajuster à l'écran, dézoom, % de zoom, zoom avant
- Centre : Titre du diagramme (gras) + badge de type (pilule grise)
- Droite : Bouton Télécharger JSON (bleu)
Interactivité (tout en JS vanille)
- Zoom : La molette de la souris met à l'échelle le viewBox SVG. Plage : 0,2x à 5x. Zoom vers la position du curseur.
- Déplacement : Cliquer-glisser sur le canevas vide translate le viewBox.
- Survol : Le survol d'un nœud affiche son
sublabeldans une infobulle près du curseur. - Clic : Cliquer sur un nœud le met en surbrillance (bordure bleue) ainsi que toutes les arêtes connectées. Cliquez sur un espace vide pour désélectionner.
- Ajuster à l'écran : Le bouton calcule la boîte englobante de tous les nœuds et définit le viewBox avec un rembourrage de 60px.
- Télécharger JSON : Sérialise l'objet
DIAGRAMen JSON formaté et déclenche le téléchargement d'un fichier.
Création d'un Nouveau Diagramme
Lorsque l'utilisateur demande un nouvel organigramme ou une nouvelle maquette UI :
- Lisez le modèle : Lisez le fichier de référence du modèle HTML pour obtenir le code du moteur de rendu actuel
- Analysez la demande : Identifiez les nœuds (étapes, décisions, erreurs) et les arêtes (connexions)
- Attribuez les positions en utilisant les règles de disposition (grille de haut en bas, espacement standard)
- Appliquez les couleurs en utilisant la palette de couleurs (terminaux = vert, décisions = ambre, erreurs = rouge, etc.)
- Générez le fichier HTML complet : Copiez la structure du modèle, remplacez l'objet
DIAGRAMpar les nouvelles données - Enregistrez dans
docs/diagrams/{nom-en-kebab-case}.html - Dites à l'utilisateur : « Ouvrez
docs/diagrams/{nom}.htmldans votre navigateur pour voir le diagramme. »
Nommage des Fichiers
- Emplacement :
docs/diagrams/{nom}.html - Format :
kebab-case.html(p. ex.docs/diagrams/upload-flow.html,docs/diagrams/checkout-screen.html) - Définissez
meta.updatedà la date ISO d'aujourd'hui
Mise à Jour d'un Diagramme Existant
Lorsque l'utilisateur demande de modifier un diagramme :
- Lisez le fichier HTML existant
- Extrayez l'objet
DIAGRAMdu bloc<script> - Modifiez les nœuds/arêtes comme demandé
- Mettez à jour
meta.updatedà la date d'aujourd'hui - Régénérez le fichier HTML complet avec les données mises à jour (relisez le modèle pour le dernier moteur de rendu)
- Enregistrez au même chemin
Lecture d'un Diagramme
Lorsqu'on vous demande d'analyser ou de décrire un diagramme :
- Lisez le fichier HTML
- Trouvez le bloc
const DIAGRAM = { ... }; - Listez les nœuds par type et étiquette
- Tracez les arêtes pour décrire le flux en langage naturel
- Mettez en évidence les points de décision et leurs branches
Exemples
« Crée un organigramme pour le flux de connexion »
Action : Créez docs/diagrams/connexion-flow.html avec :
start(cercle, vert) →saisir_identifiants(boîte) →valider(losange, ambre)valider→ oui/gauche →tableau_de_bord(cercle, vert)valider→ non/droite →afficher_erreur(note, rouge) → flèche pointillée retour verssaisir_identifiants
« Mets à jour la maquette des paramètres pour ajouter un bouton de mode sombre »
Action : Lisez docs/diagrams/ecran-parametres.html, extrayez DIAGRAM, ajoutez un nouveau nœud boîte "section_mode_sombre" avec l'étiquette « Mode sombre » positionné après la section Thème, mettez à jour meta.updated, régénérez le HTML.
« Ajoute la gestion d'erreur à l'étape 3 du flux de téléchargement »
Action : Lisez le HTML, trouvez l'étape 3 dans le tableau des nœuds, ajoutez un nœud de note d'erreur à droite, ajoutez une arête rouge pointillée de l'étape 3 à la note d'erreur, régénérez.
Contraintes Importantes
- Zéro dépendance : Pas de npm, pas de liens CDN, pas de scripts/styles externes
- Fonctionne hors ligne : Doit s'afficher sans accès Internet
- Fichier unique : Chaque diagramme est UN seul fichier
.html - Natif du navigateur : HTML5 standard, CSS3, SVG et JavaScript ES6+ vanille uniquement
- Adapté aux LLM : Le JSON DIAGRAM doit être formaté proprement, non minifié
Auto-Maintenance
Si vous découvrez un motif utile lors de la création de diagrammes, une nouvelle astuce de disposition, une couleur qui fonctionne bien pour un usage spécifique, une amélioration du rendu, mettez à jour ce fichier de compétence pour l'inclure. Gardez la compétence précise et exploitable.