matsonj/mviz

mviz v1.7.0

Que fait mviz ?

Générez des graphiques et des tableaux de bord clairs et axés sur les données à partir de spécifications JSON compactes ou de Markdown. Maximise le rapport données/encre avec un minimum d'éléments superflus (chartjunk), de lignes de grille et d'éléments décoratifs. Utilise un système de disposition en grille à 16 colonnes.

Configuration

Aucune installation requise. Utilisez npx -y -q mviz qui se télécharge automatiquement depuis npm. Le drapeau -q réduit la sortie npm tout en affichant les erreurs de lint.

Pour une utilisation répétée plus rapide, installez globalement : npm install -g mviz

Ce que fait cette compétence

mviz, c'est deux choses :

1. Un langage de spécification — du Markdown avec des blocs de code décrivant des composants (graphiques, KPI, tableaux, notes, etc.). Un seul fichier Markdown (ou une spécification JSON unique) décrit une visualisation entière.
2. Un ensemble de moteurs de rendu qui transforment cette spécification en HTML pour différents contextes d'affichage. Il en existe deux aujourd'hui :
   • visualize:show_widget (en ligne) — lorsque vous êtes sur claude.ai avec l'outil de visualisation disponible, affichez la spécification mviz sous la forme d'un fragment HTML widget_code utilisant le système de design de claude.ai (Chart.js, jetons var(--color-*)). Le widget apparaît en ligne dans la conversation.
   • CLI mviz (autonome) — mviz dashboard.md -o report.html produit un document HTML complet avec le propre système de design de mviz (thème mdsinabox, ECharts). Convient aux téléchargements, aux vignettes iframe, à l'impression/PDF.

La spécification Markdown mviz est canonique ; le moteur de rendu est choisi en fonction de l'endroit où la visualisation apparaîtra. Même spécification, deux rendus. Un tiers pourrait construire un moteur de rendu différent (CLI basé sur Chart.js, rendu thématisé Slack, etc.) sans modifier la spécification.

Choisir un moteur de rendu

Composez toujours la spécification Markdown mviz en premier, même lors d'un rendu en ligne. La spécification est l'artefact canonique — émettez-la dans un bloc de code dans votre réponse afin que l'utilisateur puisse la copier / réutiliser / l'envoyer vers la CLI plus tard. Ensuite, effectuez le rendu avec le moteur qui correspond à la demande.

Avant le rendu, décidez quel moteur de rendu convient — et indiquez votre déduction afin que l'utilisateur puisse vous corriger. Voici quelques indices :

En ligne (visualize:show_widget) :

• « montre-moi X » / « quel était X » / « comment X a-t-il changé » / « rendu »
• Une petite visualisation (généralement 1 à 4 composants) qui s'intègre au texte environnant
• L'utilisateur explore des données, il ne prépare pas quelque chose à partager
• visualize:show_widget est disponible dans cette conversation

Autonome (CLI mviz) :

• « fais un rapport » / « envoie-moi le fichier » / « exporter en PDF » / « sauvegarder »
• Vue composée de plusieurs sections (5+ composants, séparateurs, sauts de page, tableaux pleine largeur)
• L'utilisateur veut quelque chose à sauvegarder, partager, imprimer ou intégrer dans un hôte externe (vignette iframe, cellule de tableau de bord)
• visualize:show_widget n'est pas disponible (pas de surface de rendu en ligne)

Par défaut, optez pour le rendu en ligne en cas d'ambiguïté. Indiquez explicitement la déduction :

« Je vais faire un rendu en ligne puisque vous avez demandé à le voir dans le chat. Si vous préférez un fichier téléchargeable, je peux exécuter la CLI mviz sur la même spécification — dites-le simplement. »

Si l'utilisateur demande plus tard la version fichier après un rendu en ligne, la spécification est déjà dans la conversation — il suffit de la passer via mviz ... -o out.html sans la recomposer.

Style visuel (thème mdsinabox — pour le moteur de rendu CLI)

• Police : Helvetica Neue, Arial (propre sans-serif)
• Signature : Ligne d'accent orange en haut des tableaux de bord
• Palette : Bleu primaire, orange secondaire, couleurs sémantiques (vert = positif, ambre = avertissement, rouge = erreur)
• Arrière-plan : Papier (#f8f8f8 clair) / Sombre (#231f20 foncé)
• Principes : Rapport données/encre élevé, pas de chartjunk, lignes de grille minimales, les données parlent d'elles-mêmes

Moteur de rendu : CLI mviz (HTML autonome)

La CLI produit un document HTML complet stylisé avec le thème mdsinabox ci-dessus. La sortie convient à la visualisation directe dans un navigateur, à l'export PDF, à l'intégration iframe ou au partage en tant que fichier.

Graphique unique (JSON)

echo '<json_spec>' | npx -y -q mviz -o chart.html

Tableau de bord depuis Markdown

npx -y -q mviz dashboard.md -o dashboard.html

Tableau de bord depuis un dossier

npx -y -q mviz my-dashboard/ -o dashboard.html

Sortie intégrée dans une iframe (--embed)

Lorsque le HTML généré sera placé dans une iframe d'un autre produit (vignettes Prism mdw-turbo, cellules de tableau de bord, etc.), passez --embed pour supprimer le chrome de la page (barre d'accent rouge, ligne de titre, bouton de changement de thème) et appliquez une série de post-traitements qui allègent le corps : élagage CSS, arrière-plans transparents pour que le chrome de la carte hôte apparaisse, script ECharts supprimé lorsqu'aucun graphique n'est présent, marked supprimé lorsqu'aucun appel marked.parse(...), minification JS, etc.

npx -y -q mviz dashboard.md --embed -o tile.html

Le mode embed émet un document HTML complet (DOCTYPE + html + head + body intacts). Ce n'est pas l'outil approprié pour visualize:show_widget — pour cela, utilisez l'autre moteur de rendu (voir ci-dessous).

Système de grille à 16 colonnes

Les composants sont dimensionnés à l'aide de la syntaxe size=[colonnes, lignes] :

```big_value size=[4,2]
{"value": 1250000, "label": "Revenu", "format": "currency0m"}
```
```bar size=[8,6]
{"title": "Ventes", "x": "month", "y": "sales", "file": "data/sales.json"}
```

• 16 colonnes de largeur totale (portrait et paysage)
• Hauteur de ligne : ~32px par unité de ligne (approximatif - les graphiques ont des marges)
• Capacité de la page : Portrait [16c × 30l], Paysage [16c × 22l]
• Les composants sur la même ligne partagent la ligne
• Ligne vide = nouvelle ligne

Directives de hauteur :

Unités de ligne	Hauteur approximative	Bon pour
2	~64px	KPI, notes d'une seule ligne
4	~128px	Petits tableaux, blocs de texte
5-6	~160-192px	Graphiques standard
8+	~256px+	Tableaux denses, graphiques détaillés

Pour les graphiques avec de nombreuses catégories (10+ barres, 10+ lignes dans un dumbbell), augmentez les unités de ligne pour éviter la compression.

Disposition côte à côte

Critique : Pour placer des composants côte à côte, leurs blocs de code ne doivent PAS avoir de lignes vides entre eux :

```bar size=[8,5]
{"title": "Graphique A", ...}
```
```line size=[8,5]
{"title": "Graphique B", ...}
```

Cela affiche le Graphique A et le Graphique B sur la même ligne. L'ajout d'une ligne vide entre eux les placerait sur des lignes séparées.

Titres et sauts de section

Syntaxe	Effet
# H1	Titre de page
## H2	Titre de section
### H3	En-tête léger en ligne (subtile, texte plus petit)
---	Ligne de séparation visuelle
===	Saut de page pour l'impression
empty_space	Espaceur de cellule de grille invisible (par défaut 4 col × 2 lignes)

Directives pour les titres :

• Définissez le titre de la page soit avec le title: du frontmatter, soit avec un # H1 en tête, pas les deux.
• Utilisez ## H2 pour les titres de section au sein d'une page (le plus courant).
• Utilisez ### H3 pour les sous-titres légers qui n'interrompent pas le flux.

Sauts de section vs de page :

• Utilisez --- pour séparer visuellement les sections logiques. Le contenu passe naturellement à la page suivante si nécessaire.
• Utilisez === uniquement lorsque vous voulez explicitement forcer une nouvelle page (par exemple, séparer des chapitres ou des sections principales de rapport pour la sortie PDF).
• N'utilisez jamais === par défaut. Ajoutez des sauts de page uniquement lorsque l'utilisateur le demande explicitement.

Tailles par défaut

Composant	Taille par défaut	Remarques
big_value	[4, 2]	4 par ligne
delta	[4, 2]	4 par ligne
sparkline	[4, 2]	Graphique compact en ligne
bar, line, area	[8, 5]	Demi-largeur
pie, scatter, bubble	[8, 5]	Demi-largeur
funnel, sankey, heatmap	[8, 5]	Demi-largeur
histogram, boxplot, waterfall	[8, 5]	Demi-largeur
combo	[8, 5]	Demi-largeur
dumbbell	[12, 6]	3/4 de largeur
table	[16, 4]	Pleine largeur
textarea	[16, 4]	Pleine largeur
calendar	[16, 3]	Pleine largeur
xmr	[16, 6]	Pleine largeur, haute
mermaid	[8, 5]	Demi-largeur (utilisez ascii: true pour le texte artistique)
alert, note, text	[16, 1]	Pleine largeur, une seule ligne
empty_space	[4, 2]	Espaceur invisible

Appariements de taille recommandés

Objectif de disposition	Composants	Tailles
4 KPI sur une ligne	4× big_value	[4,2] chacun
5 KPI sur une ligne	4× big_value + 1 plus large	[3,2] + [4,2]
KPI + contexte	big_value + textarea	[3,2] + [13,2]
KPI + graphique	big_value + bar	[4,2] + [12,5]

Exemple : Ligne KPI dense

```big_value size=[3,2]
{"value": 1250000, "label": "Revenu", "format": "currency0m"}
```
```big_value size=[3,2]
{"value": 8450, "label": "Commandes", "format": "num0k"}
```
```big_value size=[3,2]
{"value": 2400000000, "label": "Requêtes", "format": "num0b"}
```
```delta size=[3,2]
{"value": 0.15, "label": "MoM", "format": "pct0"}
```
```delta size=[4,2]
{"value": 0.08, "label": "vs Objectif", "format": "pct0"}
```

Cela crée une ligne avec 5 KPI (3+3+3+3+4 = 16 colonnes).

Exemple : Deux graphiques côte à côte

```bar size=[8,6] file=data/region-sales.json
```
```line size=[8,6] file=data/monthly-trend.json
```

Types pris en charge

Graphiques : bar, line, area, pie, scatter, bubble, boxplot, histogram, waterfall, xmr, sankey, funnel, heatmap, calendar, sparkline, combo, dumbbell, mermaid

Composants d'interface : big_value, delta, alert, note, text, textarea, empty_space, table

Formatage des tableaux

Les tableaux prennent en charge le formatage au niveau des colonnes et des cellules :

Options de colonne : bold, italic, type ("sparkline" ou "heatmap")

{
  "type": "table",
  "columns": [
    {"id": "product", "title": "Produit", "bold": true},
    {"id": "category", "title": "Catégorie", "italic": true},
    {"id": "sales", "title": "Ventes", "fmt": "currency"},
    {"id": "margin", "title": "Marge", "type": "heatmap", "fmt": "pct"},
    {"id": "trend", "title": "Tendance", "type": "sparkline", "sparkType": "line"}
  ],
  "data": [
    {"product": "Widget", "category": "Électronique", "sales": 125000, "margin": 0.85, "trend": [85, 92, 88, 95, 102, 125]}
  ]
}

Surcharges au niveau des cellules : Utilisez {"value": "texte", "bold": true} pour remplacer les valeurs par défaut des colonnes.

Heatmap : Applique un dégradé de couleurs des valeurs faibles aux valeurs élevées. Le texte passe automatiquement en blanc sur les arrière-plans foncés.

Types Sparkline : line, bar, area, pct_bar (barre de progression), dumbbell (comparaison avant/après)

Tri et filtre :

Champ	Valeurs	Défaut	Effet
sortable	true / false	true	Cliquez sur un en-tête de colonne pour trier. Cycle asc → desc → désactivé. Les colonnes numériques trient par valeur brute.
filter	true / false	false	Quand true, affiche une entrée de recherche « Filtrer par n'importe quelle valeur… » au-dessus du tableau. Les lignes sont filtrées en direct par correspondance insensible à la casse dans toutes les cellules.

Exemple : {"type": "table", "filter": true, "columns": [...], "data": [...]}

Types de notes

Les notes prennent en charge trois niveaux de gravité via noteType :

Type	Couleur de bordure	Utilisation
default	Rouge	Avis importants (par défaut)
warning	Jaune	Précautions, données préliminaires
tip	Vert	Bonnes pratiques, astuces

Les notes prennent également en charge un label optionnel pour un texte de préfixe en gras :

{"type": "note", "label": "Astuce :", "content": "Utilisez les raccourcis clavier pour une navigation plus rapide.", "noteType": "tip"}

Exemples de graphiques spécialisés

big_value - Métriques vedettes avec grand affichage :

{"type": "big_value", "value": 1250000, "label": "Revenu", "format": "currency0m"}

• Objet comparison optionnel : {"value": 10300, "format": "currency", "label": "vs mois dernier"} affiche le changement avec une flèche

dumbbell - Comparaisons avant/après avec couleur directionnelle :

{
  "type": "dumbbell",
  "title": "Changements ELO",
  "category": "equipe",
  "start": "avant",
  "end": "après",
  "startLabel": "Semaine 1",
  "endLabel": "Semaine 2",
  "higherIsBetter": true,
  "data": [
    {"equipe": "Chiefs", "avant": 1650, "après": 1720},
    {"equipe": "Bills", "avant": 1600, "après": 1550}
  ]
}

• Vert = amélioration, Rouge = déclin, Gris = pas de changement
• higherIsBetter: false pour les classements (plus bas = mieux)
• Les étiquettes abrègent automatiquement les grands nombres (7450 → "7k")

delta - Métriques de changement avec couleur directionnelle :

{"type": "delta", "value": 0.15, "label": "Croissance MoM", "format": "pct0"}

• Les valeurs positives s'affichent en vert avec ▲, les négatives en rouge avec ▼
• Objet comparison optionnel : {"value": 0.05, "label": "vs Objectif"}

area - Graphique en aires rempli pour les données cumulatives/volumes :

{
  "type": "area",
  "title": "Utilisateurs actifs quotidiens",
  "x": "date",
  "y": "utilisateurs",
  "data": [{"date": "Lun", "utilisateurs": 1200}, {"date": "Mar", "utilisateurs": 1450}]
}

combo - Barres + courbes avec double axe Y :

{
  "type": "combo",
  "title": "Revenu vs Taux de croissance",
  "x": "trimestre",
  "y": ["revenu", "taux_croissance"],
  "data": [
    {"trimestre": "T1", "revenu": 1000000, "taux_croissance": 0.15},
    {"trimestre": "T2", "revenu": 1200000, "taux_croissance": 0.20}
  ]
}

• Le premier champ y s'affiche sous forme de barres, le second sous forme de courbe
• Doubles axes Y avec échelles indépendantes

heatmap - Visualisation matricielle 2D :

{
  "type": "heatmap",
  "title": "Activité par heure",
  "xCategories": ["Lun", "Mar", "Mer", "Jeu", "Ven"],
  "yCategories": ["9h", "12h", "15h", "18h"],
  "format": "num0",
  "data": [[0, 0, 85], [1, 0, 90], [2, 0, 72]]
}

• L'option format s'applique aux étiquettes des cellules (par exemple, num0k, currency0k, pct)

funnel - Flux de conversion ou d'élimination :

{
  "type": "funnel",
  "title": "Pipeline de vente",
  "format": "num0",
  "data": [
    {"stage": "Prospects", "value": 1000},
    {"stage": "Qualifiés", "value": 600},
    {"stage": "Proposition", "value": 300},
    {"stage": "Conclu", "value": 100}
  ]
}

• L'option format s'applique aux étiquettes/infobulles (par exemple, currency_auto, pct, num0)

waterfall - Visualisation des changements cumulatifs :

{
  "type": "waterfall",
  "title": "Pont de revenu",
  "x": "élément",
  "y": "valeur",
  "data": [
    {"élément": "Début", "value": 1000, "isTotal": true},
    {"élément": "Croissance", "value": 200},
    {"élément": "Attrition", "value": -50},
    {"élément": "Fin", "value": 1150, "isTotal": true}
  ]
}

bubble - Nuage de points avec dimension de taille. Prend en charge series pour le regroupement par couleur et showLabels