HTML View
node <skill-dir>/scripts/htmlview est le point d'entrée en ligne de commande multi-plateforme ; ci-après abrégé en htmlview. Nécessite Node.js 22+ ; la vérification du navigateur, la capture d'écran, l'exportation et le rendu de graphiques isolés nécessitent également Chrome ou Chromium. Si aucun navigateur n'est trouvé, suivre error.next.
HTML existant : changement de thème uniquement
- Artéfacts htmlview : documents, rapports ou pages de graphiques isolés : utiliser
htmlview style file.html --theme cloudmusic(consulter les thèmes avechtmlview style --list) ; pour les maquettes d'interface : utiliser--schemeou--brand.stylemet à jour le fichier sur place, ne réorganise que l'enveloppe et les graphiques dérivés. Pour obtenir un nouveau fichier, copier d'abord dans le même répertoire vers un nom de fichier non utilisé, exécuterstylesur la copie, puis utiliserhtmlview diffpour comparer le contenu. - HTML classique :
stylen'accepte pas le HTML classique. Lorsqu'il est nécessaire d'utiliser l'enveloppe de la compétence, créer un nouveau document thématique (voir flux document et composants document), déplacer le contenu existant dans le nouveau fichier ; ne pas réutiliser le CSS et les scripts de l'ancienne enveloppe. En cas de simple changement de style, conserver les chiffres, la granularité temporelle et les conclusions d'origine ; ne pas recalculer les données, ni supprimer les détails des graphiques originaux pour passer la vérification d'affichage.
Choix de l'entrée selon la tâche
| Résultat attendu par l'utilisateur | Procédure | Quand développer |
|---|---|---|
| Proposition technique, rapport, notice, compte rendu ou fiche lisible et annotable | Avec Markdown : doc build ; édition directe HTML : doc new | Lire d'abord flux document ; en cas d'écriture manuelle de composants HTML, d'ajout de références croisées ou de traitement de commentaires, lire composants document |
| Rapport ou tableau de bord nécessitant la vérification des chiffres, des définitions et des graphiques | Créer un paquet de données à partir du fichier de synthèse amont ; data validate puis data build | Lire d'abord flux rapport ; pour modifier les champs, indicateurs, graphiques ou commentaires, lire paquet de données ; pour un tableau de bord, lire conception de tableau de bord |
| Maquette filaire, haute-fidélité ou prototype montrant un écran, un état ou un flux d'interaction | ui new puis renseigner chaque écran avec des composants réels et leurs valeurs | Lire d'abord flux maquette UI ; pour choisir des composants ou écrire des interactions, lire index des composants ; pour la mise en page, les couleurs ou l'écriture de composants personnalisés, lire conception UI ; pour dessiner un tableau de bord, lire conception de tableau de bord |
| Graphique SVG unique ou page de graphique hors ligne | Choisir une famille de graphiques dans le tableau ci-dessous, écrire la déclaration, puis viz render | Pour les graphiques de données, lire d'abord règles générales de déclaration, puis la famille choisie ; pour les diagrammes de structure, lire directement la famille correspondante |
| Lire, vérifier, capturer ou exporter un HTML local | Utiliser read, check, shot, export ou embed | Voir Affichage et export pour les paramètres et les résultats de vérification |
- Lorsque le matériau n'est pas une structure de page prête (notes éparses, comptes rendus, JSON, CSV, logs, ou Markdown à réorganiser), lire Du matériau à la page avant d'écrire le contenu.
- Les artéfacts HTML sont des fichiers uniques ouvrables hors ligne. Lors de l'écriture manuelle, ne modifier que le titre et le contenu entre
<!-- htmlview:content -->et<!-- /htmlview:content -->; ne conserver qu'une occurrence de chaque marqueur. La mise en page, le thème et les scripts d'exécution sont assemblés par la CLI. - Les documents construits à partir de Markdown doivent être modifiés en Markdown ; les rapports de données via le paquet de données, sans modifier directement le texte, les graphiques ou les chiffres générés. Ne pas inventer de données sans source ; les données de démonstration doivent être clairement indiquées comme des exemples fictifs.
- Pour écraser un artéfact isolé existant, confirmer la cible avant d'utiliser
--force; la mise à jour d'un document de même source ne nécessite pas--force. - Sans
--lang, les commandes de génération déterminent la langue des éléments d'enveloppe (numérotation des figures, table des matières, légendes, etc.) en fonction du titre et du corps : si le nombre de mots anglais est au moins le double du nombre de caractères chinois/japonais, l'anglais est utilisé ; sinon, le chinois. Pour d'autres langues ou un contenu moitié anglais moitié chinois, passer explicitement--lang.
Choix du graphique selon ce que le lecteur veut voir
Utiliser par défaut des graphiques statiques. Pour les graphiques de données, utiliser le format JSON KChart ; pour les diagrammes de structure, utiliser Mermaid ou une déclaration native. Consulter d'abord Règles générales de configuration, style, liens et diagnostic, puis le type de graphique correspondant ; KChart ne copie pas l'apparence de Mermaid. Ne remplir que les données, la sémantique et l'intention de lecture ; ne pas écrire de coordonnées, de tailles de police, de couleurs ou de scripts de dessin. Les graphiques peuvent défiler à l'intérieur si nécessaire, mais la page elle-même ne doit pas déborder horizontalement.
| Question du lecteur | Type de graphique | Lecture selon les besoins |
|---|---|---|
| Comment ça évolue, quand ça change ? | line, area, sparkline, small-multiples, stream, combo, bump, candlestick, launch-fan | Tendance |
| Lequel est plus grand, écart, distance à l'objectif ? | bar, column, dumbbell, slope, bullet, gauge, interval, split-compare | Comparaison |
| De quoi est composé le total, pertes par étape ? | share, pie, donut, radial-share, rose, funnel, waterfall, waffle, tally, treemap, sunburst | Composition |
| Distribution des valeurs, valeurs aberrantes, corrélations ? | histogram, boxplot, violin, strip, scatter | Distribution |
| Anomalies dans une matrice multi-dimensionnelle ou un calendrier ? | heatmap, bubble-matrix, calendar, radar, parallel | Matrice |
| Qui est connecté à qui, flux de quantités ? | network, sankey, threads | Réseau |
| Distribution géographique ? | choropleth, geo-scatter | Cartes |
| Classification, déploiement à partir d'un thème ? | KChart tree, mindmap ; Mermaid mindmap, ishikawa, treeView-beta | Hiérarchie et mindmap |
| Processus d'une entité à une autre, transition d'états ? | flowchart, stateDiagram-v2, journey, swimlane-beta, eventmodeling, agentflow-beta, natif swimlane | Processus |
| Ordre d'appels et participants ? | sequenceDiagram, usecase-beta | Séquence |
| Planification, colonnes, numérotation ? | gantt, timeline, gitGraph, kanban, packet, quadrantChart | Temps et grille |
| Relations entre entités, classes, exigences ? | erDiagram, classDiagram, requirementDiagram | Modèle de données |
| Correspondance d'une règle de syntaxe avec des symboles ? | railroad-beta, railroad-ebnf-beta, railroad-abnf-beta, railroad-peg-beta | Modèle de données |
| Architecture système, couches, conteneurs, dépendances ? | C4Context, C4Container, C4Component, C4Dynamic, C4Deployment, architecture-beta, block, wardley-beta, natif layers, blocks | Architecture |
| Vue d'ensemble d'une page : cartes d'un groupe, processus principal, légende ? | blocks natif (cartes, badges, légendes, lignes de mise en valeur) ; block si un diagramme en boîtes Mermaid existe déjà | Architecture |
| Graphiques de valeurs Mermaid existants ? | pie, xychart, sankey, radar-beta, treemap | Graphiques de valeurs Mermaid ; pour les nouveaux graphiques de données, utiliser les types KChart ci-dessus |
| Chevauchement d'ensembles, classification de situations ? | venn-beta, cynefin-beta | Ensembles, Situations |
| Diagramme d'appels avec la syntaxe ZenUML ? | zenuml (rendu natif KChart, sans plugin externe) | ZenUML |
| Vérification de version du moteur de rendu ? | Mermaid info (pas pour livraison) | Règles générales Mermaid |
En Markdown, utiliser les blocs kchart, mermaid, layers, blocks, swimlane ; en HTML manuel, utiliser <pre data-viz="syntax">, en échappant les caractères HTML spéciaux. Les titres des figures sont écrits dans la déclaration : pour KChart : title, pour les diagrammes de structure : title: dans le préambule ou la déclaration de titre prise en charge par la syntaxe. Les titres des figures et le texte des figures sont dans la même langue que le corps du texte. En cas d'impossibilité de représentation avec les familles intégrées (imbrication trop profonde, relations trop nombreuses, schémas de mécanisme), diviser d'abord en vue d'ensemble et vues détaillées ; si un dessin manuel reste nécessaire, lire SVG personnalisé.
Aide-mémoire des commandes
| Action | Commande |
|---|---|
| Brouillon de document / génération à partir d'une source | htmlview doc new plan.html --type plan --title 'Plan d'évaluation de capacité' ou htmlview doc build spec.md --out spec.html --type tech-spec |
| Paquet de données et rapport | htmlview data init example → htmlview data validate example/report.json → htmlview data build example/report.json --out report.html |
| Structure de maquette UI | htmlview ui new prototype.html --title 'Traitement des demandes' --device mobile --screens 'Liste,Détail' |
| Audit silencieux, comparaison de contenu | htmlview audit file.html ; htmlview diff old.html new.html |
| Réassemblage des modules de graphiques pour un document ou une maquette | htmlview style file.html (conserve le thème et le contenu existants) |
| Vérification d'affichage, capture d'écran, export | htmlview check file.html ; htmlview shot file.html --select 'figure' ; htmlview export file.html --format pdf ; capture longue page htmlview export file.html --format png |
| Lecture du contenu, intégration de ressources locales | htmlview read file.html [--outline ou --section id] ; htmlview embed file.html |
| Graphique isolé, contraintes de champ, couleur de thème, mesure de texte de graphique manuel | htmlview viz render spec.json --out chart.svg ; htmlview viz schema bar ; htmlview viz palette --theme paper ; htmlview viz measure 'Service de commandes' --size 13 |
Lorsque l'utilisateur fournit sa propre palette de couleurs, utiliser --theme-file <JSON> ; les champs et exemples sont dans Fichier de thème. Le thème est intégré dans le HTML ; les maquettes d'interface utilisent une palette de couleurs de marque indépendante.
htmlview <sous-commande> --help donne les paramètres précis. Pour les commandes de vérification, pass:false signifie que la vérification est terminée mais que des problèmes ont été détectés ; les corriger selon failures[].fix. ok:false signifie que la commande n'a pas pu aboutir ; suivre error.next.
Validation avant livraison
- Après la création ou la modification d'un artéfact, exécuter
audit. S'il manque des modules de graphiques, exécuterstylepour réassembler, puis auditer à nouveau ; si le rapport présente des incohérences de preuves, corriger le paquet de données. - Pour les modifications qui changent l'affichage, exécuter
check, puisshotpour ouvrir la capture d'écran réelle. Vérifier la hiérarchie des titres, l'appartenance du texte, l'espacement et le premier écran mobile ; pour les graphiques larges, ouvrir le SVG complet pour inspection. Pour les prototypes interactifs, cliquer sur les chemins critiques réels. - Lors de la livraison en PDF, ouvrir le PDF réel pour vérifier que les titres des figures et les figures sont sur la même page et que les bords sont complets. En cas d'avis d'impression, choisir un format de papier approprié ou ajuster la mise en page, en conservant une taille de police lisible ; si l'impression complète est impossible, expliquer la limitation.