diagram-design 2026 : les SVG/PNG exportés sont incorrects, comment valider un schéma d’architecture IA ?

Le viewBox d’un SVG se définit avec quatre valeurs numériques — origine horizontale, origine verticale, largeur et hauteur — comme le précise la spécification SVG 2 du W3C. Si votre export coupe un dessin ou le décale, commencez donc par comparer le fichier source, l’aperçu HTML et le fichier exporté : ne validez pas le résultat sur la seule base de l’aperçu.

Symptôme : l’aperçu paraît correct, mais le SVG ou le PNG livré est tronqué, illisible ou trompeur. Correction la plus rapide : identifiez où l’écart apparaît, contrôlez ensuite le format concerné et vérifiez les relations du diagramme à partir de sources techniques.

Cet article s’adresse aux ingénieurs qui intègrent des diagrammes générés par Claude Code, Codex ou GitHub Copilot dans leurs documents et dépôts. Il concerne aussi les responsables de documentation qui doivent valider des fichiers exportés et leur lisibilité. Les équipes plateforme y trouveront une méthode pour intégrer des contrôles de fichiers et de rendu à une chaîne d’intégration continue.

Où l’écart apparaît-il entre la source et le fichier livré ?

Un export incorrect ne désigne pas nécessairement un seul type de panne. Le défaut peut provenir du HTML généré, de la mise en page, de l’exporteur ou du logiciel qui ouvre le résultat. Si vous ne séparez pas ces étapes, vous risquez de modifier le diagramme alors que le problème vient du moteur de rendu, ou de corriger le rendu sans remarquer une relation d’architecture erronée.

Prenez un même schéma et confrontez les trois éléments suivants :

• Le HTML d’origine, tel qu’il a été produit, avec ses feuilles de style et les éventuelles ressources locales.
• L’aperçu dans le navigateur, en notant le navigateur, les polices disponibles et les dimensions de la fenêtre.
• Le fichier livré, ouvert dans le logiciel ou le contexte réel d’utilisation : documentation, dépôt, présentation ou autre outil de consultation.

Relevez l’endroit où le défaut apparaît pour la première fois. Si la source HTML est déjà mal organisée, l’export ne fait que reproduire un problème antérieur. Si le navigateur montre un résultat correct mais que le fichier SVG est amputé, concentrez votre diagnostic sur la structure ou les styles de l’export. Si seul le PNG diffère, examinez les conditions de capture avant de réécrire le diagramme.

Pour pouvoir reproduire le problème, consignez la commande exacte, le chemin d’entrée, le chemin de sortie et la version de l’outil. Le dépôt officiel de diagram-design et sa documentation de la commande d’export sont les références à consulter pour vérifier les options réellement documentées. Ne supposez pas qu’un agent, un navigateur ou un logiciel de lecture prend en charge les mêmes options qu’un autre.

Un cas fréquent dans une documentation technique est un aperçu HTML satisfaisant, mais une image destinée à une page de référence dont les libellés se superposent. Avant de retoucher les positions, réexportez sans changer l’entrée et comparez le résultat. Cette répétition permet de distinguer un défaut reproductible d’un écart introduit par une ressource ou une condition de rendu différente.

Quelles vérifications effectuer selon le format ?

Un SVG conserve une structure et des informations de style ; un PNG est une image matricielle obtenue par rendu. Les contrôles ne sont donc pas interchangeables. Un fichier vectoriel peut s’ouvrir tout en présentant des références manquantes, tandis qu’une image peut être complète mais trop peu lisible à la taille retenue.

Première vérification : examiner le SVG comme un fichier structuré

Ne vous contentez pas d’ouvrir le dessin : consultez également le contenu du fichier. Vérifiez que la zone viewBox couvre bien l’ensemble du schéma et que les valeurs décrivent un rectangle cohérent. Une zone de dessin incorrecte peut expliquer une découpe ou un grand espace vide, mais elle ne prouve pas que l’exporteur est défaillant : le HTML d’origine peut déjà définir une disposition problématique.

Repérez ensuite les éléments de texte, les règles de style et les références dont dépend l’affichage. La documentation MDN sur l’élément <style> dans un SVG décrit l’usage de règles CSS dans ce contexte. Si la présentation dépend de styles qui ne sont pas conservés dans le fichier, ou de ressources externes indisponibles à l’ouverture, le résultat peut changer selon l’application.

Examinez enfin les identifiants et les références. La structure SVG repose sur des éléments et leurs attributs ; l’attribut id est destiné à identifier un élément dans le document, et les valeurs doivent être uniques dans cet arbre, selon la spécification du W3C. Des identifiants réutilisés peuvent rendre ambiguë une référence interne. Recherchez donc les répétitions ainsi que les références qui ne correspondent à aucun élément présent.

La documentation d’export de diagram-design doit servir à vérifier les formats et étapes annoncés par le projet. Lorsque le document ne confirme pas une compatibilité ou un comportement précis, ne l’attribuez pas à l’outil : établissez le constat en examinant votre fichier et en le rouvrant dans le logiciel de destination.

Deuxième vérification : reproduire le rendu PNG dans des conditions comparables

Pour un PNG, vérifiez d’abord le cadrage, la lisibilité des libellés et la présence de tous les éléments attendus. Ensuite, comparez les conditions de rendu : polices installées, dimensions de la fenêtre, échelle de capture et styles effectivement chargés. Une différence de police peut déplacer un libellé ou modifier la place nécessaire à une boîte, sans qu’une relation du diagramme ait changé.

Reproduisez l’export avec la même entrée dans l’environnement local et dans celui de livraison, puis conservez les images obtenues. Pour une capture automatisée au moyen de Playwright, la référence de l’interface de capture de page documente les paramètres disponibles, notamment l’échelle css ou device. Ces choix peuvent modifier la façon dont la capture est produite ; ils ne constituent pas une garantie d’identité entre tous les moteurs et toutes les polices.

Pour isoler le problème, changez une seule condition à la fois. Si vous modifiez simultanément la police, la taille de la fenêtre et la commande d’export, vous ne saurez pas laquelle a corrigé — ou aggravé — l’écart. L’objectif n’est pas d’obtenir une image simplement « plus jolie », mais de comprendre quelle différence de rendu explique l’anomalie et de savoir si elle affecte réellement le document livré.

Pour les documents illustrés de contenu créatif, notamment les supports de conception, de vidéo ou de production audio, vérifiez aussi l’usage final : une vue réduite peut rendre une légende illisible alors que l’image semble nette à sa taille native. Faites le contrôle dans la page ou la présentation où le PNG sera intégré, plutôt que de valider le fichier uniquement dans une fenêtre d’aperçu.

Comment séparer défaut d’export et erreur d’architecture ?

Un export techniquement valide peut représenter un système qui n’existe pas. Une flèche bien alignée, un code couleur cohérent et une typographie régulière n’établissent pas qu’un service appelle réellement un autre service, ni qu’un composant se trouve dans le bon périmètre.

Reprenez chaque élément du schéma séparément : nom de composant, frontière de système, sens de chaque liaison, protocole indiqué et éventuelle responsabilité attribuée. Cherchez une preuve dans le code, les contrats d’interface, une spécification ou une documentation validée. Si la preuve manque, notez la relation comme hypothèse à confirmer ; ne laissez pas un agent compléter les éléments absents à partir d’une convention qui vous semble vraisemblable.

Cette revue est particulièrement importante lorsque plusieurs outils participent à la production : un agent peut avoir produit la source, un autre l’avoir modifiée et un processus de documentation avoir exporté le résultat. Conservez la provenance du diagramme — entrée, modifications et version livrée — afin de pouvoir distinguer une erreur de génération d’une modification ultérieure.

La validation sémantique gagne à rester proche des éléments vérifiables. Pour une liaison, par exemple, associez le nom de la relation à un contrat ou à une référence précise dans la documentation interne. Si vous ne pouvez pas justifier la liaison, retirez-la ou marquez-la explicitement à revoir. Une correction de style ne doit jamais être utilisée comme substitut à cette vérification.

Installer une porte de contrôle avant la livraison

Une vérification utile sépare les contrôles automatisables de ceux qui exigent un jugement technique. Vous pouvez automatiser la présence des fichiers attendus, leur ouverture par un analyseur ou la conservation du journal de génération. En revanche, un script qui confirme qu’un SVG est lisible ne sait pas, à lui seul, si une flèche exprime la bonne dépendance.

Voici une séquence exploitable pour la livraison :

1. Figez l’entrée de contrôle. Conservez le HTML ou la source du diagramme, ainsi que les ressources nécessaires, dans le même état pour les reproductions.
2. Consignez l’exécution. Enregistrez la commande d’export, la version de l’outil et les chemins de sortie afin qu’un échec puisse être reproduit.
3. Vérifiez les fichiers attendus. Faites échouer la chaîne si un SVG ou un PNG requis manque ou si le fichier généré est vide.
4. Contrôlez l’ouverture et le rendu. Analysez la structure du SVG ; pour une capture PNG automatisée, conservez l’image produite et contrôlez qu’elle correspond à la destination prévue.
5. Comparez les livrables. Lorsqu’un rendu change, examinez le fichier exporté et l’image avant de remplacer les artefacts précédents.
6. Validez les faits. Faites relire les nœuds et relations par une personne qui peut les confronter aux références techniques.
7. Conservez les preuves. Archivez source, journaux et fichiers générés pour diagnostiquer une régression sans perdre la version qui l’a précédée.

Dans une CI, la différence d’image peut servir de signal de changement, non de décision automatique sur la justesse du schéma. L’aide GitHub Actions sur les artefacts de flux de travail explique comment conserver et récupérer des fichiers produits par un flux de travail. Vous pouvez ainsi rendre accessibles le PNG, le SVG et les journaux à la personne chargée de la revue, plutôt que de ne transmettre qu’un statut « réussi ».

Le contrôle visuel a lui aussi ses limites : un fichier lisible peut dissimuler une liaison non sourcée, tandis qu’une comparaison pixel à pixel peut signaler un changement inoffensif de police. Gardez donc des critères distincts : fichier présent et ouvrable, dessin cadré, texte lisible à l’usage, relations justifiées et artefacts disponibles pour une reproduction.

Pour organiser vos accès et vos questions de mise en œuvre, vous pouvez consulter le centre d’aide de kvmboot. Cette ressource ne remplace pas l’analyse des fichiers ; elle sert à traiter les questions liées à votre environnement de travail, sans attribuer à une machine distante un défaut qui pourrait venir de la source ou de l’exporteur.

Questions fréquentes sur l’export et la validation

Pourquoi le PNG exporté diffère-t-il de l’aperçu HTML ?

L’aperçu et le PNG peuvent être produits dans des conditions de rendu différentes : police disponible, échelle de capture, dimensions de la page ou styles chargés. Comparez le HTML d’origine et le PNG obtenu avec une même entrée, puis reproduisez l’export dans l’environnement de livraison. Si le décalage existe déjà dans le navigateur, recherchez plutôt un problème de source ou de mise en page.

Comment vérifier qu’un SVG exporté contient tous les éléments nécessaires ?

Ouvrez le fichier comme du texte et contrôlez sa zone visible, les éléments textuels, les styles et les références utilisées par le dessin. Repérez aussi les identifiants répétés et vérifiez que les références pointent vers des éléments présents. Enfin, ouvrez le SVG dans le logiciel réellement destiné à l’utiliser : un fichier qui s’affiche dans un navigateur n’est pas automatiquement validé pour tous vos outils.

Que faire si une liaison est incorrecte malgré un export réussi ?

Traitez cela comme une erreur de contenu, pas comme un défaut d’export. Vérifiez chaque nœud et chaque liaison à partir du code, des contrats d’interface ou d’une documentation approuvée. Lorsqu’aucune source ne confirme une relation, marquez-la comme hypothèse à valider au lieu de la laisser passer comme un fait, même si le diagramme est visuellement convaincant.

Comment intégrer l’export des diagrammes à une CI ?

Faites générer le diagramme dans une étape reproductible, vérifiez que les fichiers attendus existent et que le SVG peut être analysé, puis conservez les sorties et journaux comme artefacts. Une comparaison d’images peut aider à repérer un changement de rendu, mais elle ne valide pas le sens des relations : ajoutez une revue humaine ou des contrôles fondés sur les sources techniques.

Si votre méthode actuelle repose sur un poste local ou une machine partagée, elle peut compliquer la reproduction des différences d’environnement, l’accès aux fichiers de livraison et la disponibilité d’un environnement macOS pour tester des outils qui en dépendent. Un Mac loué via kvmboot peut être une option lorsque vous avez besoin d’un environnement distant pour exécuter un agent ou contrôler des livrables liés à macOS ; il ne corrigera toutefois ni un viewBox erroné ni une relation d’architecture inventée. Si cette contrainte correspond à votre usage, consultez les options Mac de kvmboot ; sinon, commencez par reproduire l’export dans votre environnement actuel et conservez les fichiers et journaux de validation.