mviz

mviz v1.7.0

Was macht mviz?

Erstelle saubere, datenfokussierte Diagramme und Dashboards aus kompakten JSON-Spezifikationen oder Markdown. Maximiert das Daten-Tinten-Verhältnis mit minimalem Chart-Junk, Gitterlinien und dekorativen Elementen. Verwendet ein 16-Spalten-Rastersystem.

Einrichtung

Keine Installation erforderlich. Verwende npx -y -q mviz, das automatisch von npm herunterlädt. Das Flag -q reduziert die npm-Ausgabe, während weiterhin Lint-Fehler angezeigt werden.

Für schnellere wiederholte Nutzung global installieren: npm install -g mviz

Was diese Fähigkeit tut

mviz ist zweierlei:

1. Eine Spezifikationssprache — Markdown mit umrandeten Code-Blöcken, die Komponenten (Diagramme, KPIs, Tabellen, Notizen usw.) beschreiben. Eine einzige Markdown-Datei (oder eine einzelne JSON-Spezifikation) beschreibt eine gesamte Visualisierung.
2. Ein Satz von Renderern, die diese Spezifikation für verschiedene Anzeigekontexte in HTML umwandeln. Derzeit gibt es zwei:
   • visualize:show_widget (inline) — wenn du in claude.ai mit dem Visualisierungstool bist, rendere die mviz-Spezifikation als widget_code-HTML-Fragment unter Verwendung des Designsystems von claude.ai (Chart.js, var(--color-*)-Tokens). Das Widget erscheint inline in der Unterhaltung.
   • mviz CLI (eigenständig) — mviz dashboard.md -o report.html erzeugt ein vollständiges HTML-Dokument mit mvizs eigenem Designsystem (mdsinabox-Theme, ECharts). Geeignet für Downloads, iframe-Kacheln, Druck/PDF.

Die mviz-Markdown-Spezifikation ist kanonisch; der Renderer wird basierend darauf ausgewählt, wo die Visualisierung erscheinen wird. Gleiche Spezifikation, zwei Darstellungen. Ein Dritter könnte einen anderen Renderer bauen (Chart.js-basierte CLI, Slack-thematisierter Renderer usw.), ohne die Spezifikation zu ändern.

Auswahl eines Renderers

Erstelle immer zuerst die mviz-Markdown-Spezifikation, selbst wenn du inline renderst. Die Spezifikation ist das kanonische Artefakt — gib sie in einem umrandeten Code-Block in deiner Antwort aus, damit der Benutzer sie später kopieren / wiederverwenden / an die CLI weiterleiten kann. Rendere sie dann mit dem Renderer, der zur Anfrage passt.

Bevor du renderst, entscheide, welcher Renderer passt — und teile deine Schlussfolgerung mit, damit der Benutzer dich korrigieren kann. Einige Signale:

Inline (visualize:show_widget):

• „zeige mir X“ / „was war X“ / „wie hat sich X verändert“ / „darstellen“
• Eine kleine Visualisierung (typischerweise 1–4 Komponenten), die mit dem umgebenden Text fließt
• Der Benutzer erkundet Daten, bereitet nichts zum Teilen vor
• visualize:show_widget ist in dieser Unterhaltung verfügbar

Eigenständig (mviz CLI):

• „mache einen Bericht“ / „sende mir die Datei“ / „exportiere nach PDF“ / „speichern“
• Mehrteilige, zusammengesetzte Ansicht (5+ Komponenten, Trennstriche, Seitenumbrüche, vollbreite Tabellen)
• Der Benutzer möchte etwas speichern, teilen, drucken oder in einem externen Host einbetten (iframe-Kachel, Dashboard-Zelle)
• visualize:show_widget ist nicht verfügbar (keine Inline-Rendering-Oberfläche)

Standardmäßig bei Unklarheit inline verwenden. Gib die Schlussfolgerung explizit an:

„Ich werde dies inline rendern, da du darum gebeten hast, es im Chat zu sehen. Falls du lieber eine herunterladbare Datei möchtest, kann ich die mviz-CLI auf derselben Spezifikation ausführen — sag einfach Bescheid.“

Wenn der Benutzer später nach der Dateiversion fragt, nachdem eine Inline-Darstellung gezeigt wurde, ist die Spezifikation bereits in der Unterhaltung — leite sie durch mviz ... -o out.html, ohne sie neu zu erstellen.

Visueller Stil (mdsinabox-Theme — für den CLI-Renderer)

• Schriftart: Helvetica Neue, Arial (saubere serifenlose Schrift)
• Markenzeichen: Orangefarbene Akzentlinie oben auf Dashboards
• Palette: Blau primär, Orange sekundär, semantische Farben (Grün = positiv, Bernstein = Warnung, Rot = Fehler)
• Hintergrund: Papier (#f8f8f8 hell) / Dunkel (#231f20 dunkel)
• Prinzipien: Hohes Daten-Tinten-Verhältnis, kein Chart-Junk, minimale Gitterlinien, die Daten sprechen für sich

Renderer: mviz CLI (eigenständiges HTML)

Der CLI-Renderer erzeugt ein vollständiges HTML-Dokument, das im obigen mdsinabox-Theme gestaltet ist. Die Ausgabe eignet sich für die direkte Ansicht im Browser, den PDF-Export, die iframe-Einbettung oder das Teilen als Datei.

Einzelnes Diagramm (JSON)

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

Dashboard aus Markdown

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

Dashboard aus Ordner

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

In iframe eingebettete Ausgabe (--embed)

Wenn das gerenderte HTML innerhalb des iframes eines anderen Produkts (mdw-turbo Prism-Kacheln, Dashboard-Zellen usw.) leben wird, übergib --embed, um die Seitenverzierung (roter Akzentbalken, Titelzeile, Theme-Umschalter) zu entfernen und eine Reihe von Nachbearbeitungen anzuwenden, die den Inhalt verschlanken: CSS-Bereinigung, transparente Hintergründe, damit die Kartenverzierung des Hosts durchscheint, ECharts-Skript entfernt, wenn keine Diagramme vorhanden sind, marked entfernt, wenn kein marked.parse(...)-Aufrufer vorhanden ist, JS-Minifizierung usw.

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

Der Einbettungsmodus gibt ein vollständiges HTML-Dokument aus (DOCTYPE + html + head + body intakt). Es ist nicht das richtige Werkzeug für visualize:show_widget — verwende dafür den anderen Renderer (siehe unten).

16-Spalten-Rastersystem

Komponenten werden mit der size=[cols,rows]-Syntax dimensioniert:

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

• 16 Spalten Gesamtbreite (sowohl Hoch- als auch Querformat)
• Zeilenhöhe: ~32px pro Zeileneinheit (ungefähr – Diagramme haben Polsterung)
• Seitenkapazität: Hochformat [16c × 30r], Querformat [16c × 22r]
• Komponenten in derselben Zeile teilen sich die Reihe
• Leere Zeile = neue Reihe

Höhenrichtlinien:

Zeileneinheiten	Ungefähre Höhe	Geeignet für
2	~64px	KPIs, einzeilige Notizen
4	~128px	Kleine Tabellen, Textblöcke
5-6	~160-192px	Standarddiagramme
8+	~256px+	Dichte Tabellen, detaillierte Diagramme

Erhöhe bei Diagrammen mit vielen Kategorien (10+ Balken, 10+ Zeilen im Dumbbell) die Zeileneinheiten, um eine Komprimierung zu vermeiden.

Nebeneinander-Layout

Kritisch: Um Komponenten nebeneinander zu platzieren, dürfen ihre Code-Blöcke KEINE Leerzeilen zwischen sich haben:

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

Dies rendert Diagramm A und Diagramm B in derselben Zeile. Das Hinzufügen einer Leerzeile zwischen ihnen würde sie in separate Zeilen setzen.

Überschriften und Abschnittsumbrüche

Syntax	Wirkung
# H1	Seitentitel
## H2	Abschnittstitel
### H3	Leichter Inline-Header (dezent, kleinerer Text)
---	Visuelle Trennlinie
===	Seitenumbruch für den Druck
empty_space	Unsichtbarer Gitterzellen-Abstandshalter (Standard 4 Spalten × 2 Zeilen)

Überschriftenrichtlinien:

• Lege den Seitentitel entweder mit dem Frontmatter title: oder einer führenden # H1 fest, nicht beides.
• Verwende ## H2 für Abschnittstitel innerhalb einer Seite (am häufigsten).
• Verwende ### H3 für leichte Unterüberschriften, die den Fluss nicht unterbrechen.

Abschnitts- vs. Seitenumbrüche:

• Verwende ---, um logische Abschnitte visuell zu trennen. Der Inhalt fließt bei Bedarf natürlich zur nächsten Seite.
• Verwende === nur, wenn du explizit eine neue Seite erzwingen möchtest (z. B. um Kapitel oder wichtige Berichtsabschnitte für die PDF-Ausgabe zu trennen).
• Verwende niemals === standardmäßig. Füge Seitenumbrüche nur hinzu, wenn der Benutzer sie explizit anfordert.

Standardgrößen

Komponente	Standardgröße	Hinweise
big_value	[4, 2]	Passt 4 pro Reihe
delta	[4, 2]	Passt 4 pro Reihe
sparkline	[4, 2]	Kompaktes Inline-Diagramm
bar, line, area	[8, 5]	Halbe Breite
pie, scatter, bubble	[8, 5]	Halbe Breite
funnel, sankey, heatmap	[8, 5]	Halbe Breite
histogram, boxplot, waterfall	[8, 5]	Halbe Breite
combo	[8, 5]	Halbe Breite
dumbbell	[12, 6]	3/4 Breite
table	[16, 4]	Volle Breite
textarea	[16, 4]	Volle Breite
calendar	[16, 3]	Volle Breite
xmr	[16, 6]	Volle Breite, hoch
mermaid	[8, 5]	Halbe Breite (verwende ascii: true für Textkunst)
alert, note, text	[16, 1]	Volle Breite, einzelne Reihe
empty_space	[4, 2]	Unsichtbarer Abstandshalter

Empfohlene Größenpaarungen

Layout-Ziel	Komponenten	Größen
4 KPIs in einer Reihe	4× big_value	[4,2] jeweils
5 KPIs in einer Reihe	4× big_value + 1 breiter	[3,2] + [4,2]
KPI + Kontext	big_value + textarea	[3,2] + [13,2]
KPI + Diagramm	big_value + bar	[4,2] + [12,5]

Beispiel: Dichte KPI-Reihe

```big_value size=[3,2]
{"value": 1250000, "label": "Revenue", "format": "currency0m"}
```
```big_value size=[3,2]
{"value": 8450, "label": "Orders", "format": "num0k"}
```
```big_value size=[3,2]
{"value": 2400000000, "label": "Queries", "format": "num0b"}
```
```delta size=[3,2]
{"value": 0.15, "label": "MoM", "format": "pct0"}
```
```delta size=[4,2]
{"value": 0.08, "label": "vs Target", "format": "pct0"}
```

Dies erzeugt eine Reihe mit 5 KPIs (3+3+3+3+4 = 16 Spalten).

Beispiel: Zwei Diagramme nebeneinander

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

Unterstützte Typen

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

UI-Komponenten: big_value, delta, alert, note, text, textarea, empty_space, table

Tabellenformatierung

Tabellen unterstützen Formatierung auf Spalten- und Zellebene:

Spaltenoptionen: bold, italic, type ("sparkline" oder "heatmap")

{
  "type": "table",
  "columns": [
    {"id": "product", "title": "Produkt", "bold": true},
    {"id": "category", "title": "Kategorie", "italic": true},
    {"id": "sales", "title": "Verkäufe", "fmt": "currency"},
    {"id": "margin", "title": "Marge", "type": "heatmap", "fmt": "pct"},
    {"id": "trend", "title": "Trend", "type": "sparkline", "sparkType": "line"}
  ],
  "data": [
    {"product": "Widget", "category": "Elektronik", "sales": 125000, "margin": 0.85, "trend": [85, 92, 88, 95, 102, 125]}
  ]
}

Überschreibungen auf Zellebene: Verwende {"value": "text", "bold": true}, um Spaltenstandards zu überschreiben.

Heatmap: Wendet einen Farbverlauf von niedrigen zu hohen Werten an. Text wechselt automatisch auf weiß bei dunklen Hintergründen.

Sparkline-Typen: line, bar, area, pct_bar (Fortschrittsbalken), dumbbell (Vorher/Nachher-Vergleich)

Sortieren und Filtern:

Feld	Werte	Standard	Wirkung
sortable	true / false	true	Klicke auf eine Spaltenüberschrift zum Sortieren. Durchläuft aufsteigend → absteigend → aus. Numerische Spalten sortieren nach Rohwert.
filter	true / false	false	Wenn true, wird ein Suchfeld „Filtern nach einem beliebigen Wert…" über der Tabelle dargestellt. Zeilen werden live nach einer case-insensitiven Enthält-Übereinstimmung in allen Zellen gefiltert.

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

Notiztypen

Notizen unterstützen drei Schweregrade über noteType:

Typ	Rahmenfarbe	Verwendung
default	Rot	Wichtige Hinweise (Standard)
warning	Gelb	Vorsichtsmaßnahmen, vorläufige Daten
tip	Grün	Best Practices, Profi-Tipps

Notizen unterstützen auch ein optionales label für fetten Präfixtext:

{"type": "note", "label": "Profi-Tipp:", "content": "Verwende Tastenkombinationen für schnellere Navigation.", "noteType": "tip"}

Spezialisierte Diagrammbeispiele

big_value - Hero-Metriken mit großer Anzeige:

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

• Optionales comparison-Objekt: {"value": 10300, "format": "currency", "label": "vs letzten Monat"} zeigt Änderung mit Pfeil

dumbbell - Vorher/Nachher-Vergleiche mit Richtungsfarbgebung:

{
  "type": "dumbbell",
  "title": "ELO-Änderungen",
  "category": "team",
  "start": "before",
  "end": "after",
  "startLabel": "Woche 1",
  "endLabel": "Woche 2",
  "higherIsBetter": true,
  "data": [
    {"team": "Chiefs", "before": 1650, "after": 1720},
    {"team": "Bills", "before": 1600, "after": 1550}
  ]
}

• Grün = Verbesserung, Rot = Verschlechterung, Grau = keine Änderung
• higherIsBetter: false für Ranglisten (niedriger = besser)
• Beschriftungen kürzen große Zahlen automatisch (7450 → "7k")

delta - Änderungsmetriken mit Richtungsfarbgebung:

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

• Positive Werte zeigen grün mit ▲, negative zeigen rot mit ▼
• Optionales comparison-Objekt: {"value": 0.05, "label": "vs Ziel"}

area - Gefülltes Liniendiagramm für kumulative/Mengendaten:

{
  "type": "area",
  "title": "Täglich aktive Benutzer",
  "x": "date",
  "y": "users",
  "data": [{"date": "Mo", "users": 1200}, {"date": "Di", "users": 1450}]
}

combo - Balken + Linie mit dualer Y-Achse:

{
  "type": "combo",
  "title": "Umsatz vs. Wachstumsrate",
  "x": "quarter",
  "y": ["revenue", "growth_rate"],
  "data": [
    {"quarter": "Q1", "revenue": 1000000, "growth_rate": 0.15},
    {"quarter": "Q2", "revenue": 1200000, "growth_rate": 0.20}
  ]
}

• Das erste y-Feld wird als Balken dargestellt, das zweite als Linie
• Duale Y-Achsen mit unabhängigen Skalen

heatmap - 2D-Matrixvisualisierung:

{
  "type": "heatmap",
  "title": "Aktivität nach Stunde",
  "xCategories": ["Mo", "Di", "Mi", "Do", "Fr"],
  "yCategories": ["9 Uhr", "12 Uhr", "15 Uhr", "18 Uhr"],
  "format": "num0",
  "data": [[0, 0, 85], [1, 0, 90], [2, 0, 72]]
}

• Die Option format gilt für Zellenbeschriftungen (z. B. num0k, currency0k, pct)

funnel - Konvertierungs- oder Eliminierungsabläufe:

{
  "type": "funnel",
  "title": "Verkaufspipeline",
  "format": "num0",
  "data": [
    {"stage": "Leads", "value": 1000},
    {"stage": "Qualifiziert", "value": 600},
    {"stage": "Angebot", "value": 300},
    {"stage": "Abgeschlossen", "value": 100}
  ]
}

• Die Option format gilt für Beschriftungen/Tooltips (z. B. currency_auto, pct, num0)

waterfall - Kumulative Änderungsvisualisierung:

{
  "type": "waterfall",
  "title": "Umsatzbrücke",
  "x": "item",
  "y": "value",
  "data": [
    {"item": "Start", "value": 1000, "isTotal": true},
    {"item": "Wachstum", "value": 200},
    {"item": "Abwanderung", "value": -50},
    {"item": "Ende", "value": 1150, "isTotal": true}
  ]
}

bubble - Streuung mit Größenausdehnung. Unterstützt series für Farbgruppierung und showLabels