---

name: mviz description: Generate clean, data-focused charts and dashboards from compact JSON specs

mviz

Generate clean, data-focused charts and dashboards from compact JSON specs or markdown. Maximizes data-ink ratio with minimal chartjunk, gridlines, and decorative elements. Uses a 16-column grid layout system.

Setup

No installation required. Use npx mviz which auto-downloads from npm.

For faster repeated use, install globally: npm install -g mviz

What This Skill Does

Converts minimal JSON specifications into standalone HTML visualizations using ECharts. Instead of writing 50-100 lines of chart code, write a compact spec that gets expanded into a full HTML artifact with professional styling.

Visual Style (mdsinabox theme)

• Font: Helvetica Neue, Arial (clean sans-serif)
• Signature: Orange accent line at top of dashboards
• Palette: Blue primary, orange secondary, semantic colors (green=positive, amber=warning, red=error)
• Background: Paper (#f8f8f8 light) / Dark (#231f20 dark)
• Principles: High data-ink ratio, no chartjunk, minimal gridlines, data speaks for itself

How to Use

Single Chart (JSON)

echo '<json_spec>' | npx mviz > chart.html

Dashboard from Markdown

npx mviz dashboard.md > dashboard.html

Dashboard from Folder

npx mviz my-dashboard/ > dashboard.html

16-Column Grid System

Components are sized using size=[cols,rows] syntax:

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

• 16 columns total width
• Row height: ~32px per row unit (approximate - charts have padding)
• Components on same line share the row
• Empty line = new row

Height Guidelines: | Row Units | Approximate Height | Good For | |-----------|-------------------|----------| | 2 | ~64px | KPIs, single-line notes | | 4 | ~128px | Small tables, text blocks | | 5-6 | ~160-192px | Standard charts | | 8+ | ~256px+ | Dense tables, detailed charts |

For charts with many categories (10+ bars, 10+ rows in dumbbell), increase row units to prevent compression.

Side-by-Side Layout

Critical: To place components side-by-side, their code blocks must have NO blank lines between them:

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

This renders Chart A and Chart B on the same row. Adding a blank line between them would put them on separate rows.

Headings and Section Breaks

| Syntax | Effect | |--------|--------| | # H1 | Major section with page break (for print/PDF) | | ## H2 | Section title, visual divider, no page break | | ### H3 | Light inline header (subtle, smaller text) | | --- | Untitled section break: visual divider only | | === | Explicit page break: forces new page in PDF | | empty_space | Invisible grid cell spacer (default 4 cols × 2 rows) |

Heading Guidelines:

• Use # H1 for major document sections that warrant their own page when printed
• Use ## H2 for content sections within a page (most common)
• Use ### H3 for lightweight subheadings that don't interrupt flow
• In continuous: true mode, H1 page breaks are suppressed

Section vs Page Breaks:

• Use --- to separate logical sections visually. Content flows naturally to the next page when needed.
• Use === only when you explicitly want to force a new page (e.g., separating chapters or major report sections for PDF output).
• Never use === by default. Only add page breaks when the user specifically requests them.

Default Sizes

| Component | Default Size | Notes | |-----------|-------------|-------| | big_value | [4, 2] | Fits 4 per row | | delta | [4, 2] | Fits 4 per row | | sparkline | [4, 2] | Compact inline chart | | bar, line, area | [8, 5] | Half width | | pie, scatter, bubble | [8, 5] | Half width | | funnel, sankey, heatmap | [8, 5] | Half width | | histogram, boxplot, waterfall | [8, 5] | Half width | | combo | [8, 5] | Half width | | dumbbell | [12, 6] | 3/4 width | | table | [16, 4] | Full width | | textarea | [16, 4] | Full width | | calendar | [16, 3] | Full width | | xmr | [16, 6] | Full width, tall | | alert, note, text | [16, 1] | Full width, single row | | empty_space | [4, 2] | Invisible spacer |

Recommended Size Pairings

| Layout Goal | Components | Sizes | |-------------|------------|-------| | 4 KPIs in a row | 4× big_value | [4,2] each | | 5 KPIs in a row | 4× big_value + 1 wider | [3,2] + [4,2] | | KPI + context | big_value + textarea | [3,2] + [13,2] | | KPI + chart | big_value + bar | [4,2] + [12,5] |

Example: Dense KPI Row

```big_value size=[3,2]
{"value": 1250000, "label": "Revenue", "format": "usd0m"}
```
```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"}
```

This creates a row with 5 KPIs (3+3+3+3+4 = 16 columns).

Example: Two Charts Side by Side

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

Supported Types

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

UI Components: big_value, delta, alert, note, text, textarea, empty_space, table

Table Formatting

Tables support column-level and cell-level formatting:

Column options: bold, italic, type ("sparkline" or "heatmap")

{
  "type": "table",
  "columns": [
    {"id": "product", "title": "Product", "bold": true},
    {"id": "category", "title": "Category", "italic": true},
    {"id": "sales", "title": "Sales", "fmt": "usd"},
    {"id": "margin", "title": "Margin", "type": "heatmap", "fmt": "pct"},
    {"id": "trend", "title": "Trend", "type": "sparkline", "sparkType": "line"}
  ],
  "data": [
    {"product": "Widget", "category": "Electronics", "sales": 125000, "margin": 0.85, "trend": [85, 92, 88, 95, 102, 125]}
  ]
}

Cell-level overrides: Use {"value": "text", "bold": true} to override column defaults.

Heatmap: Applies color gradient from low to high values. Text auto-switches to white on dark backgrounds.

Sparkline types: line, bar, area, pct_bar (progress bar), dumbbell (before/after comparison)

Note Types

Notes support three severity levels via noteType:

| Type | Border Color | Use For | |------|--------------|---------| | default | Red | Important notices (default) | | warning | Yellow | Cautions, preliminary data | | tip | Green | Best practices, pro tips |

Notes also support an optional label for bold prefix text:

{"type": "note", "label": "Pro Tip:", "content": "Use keyboard shortcuts for faster navigation.", "noteType": "tip"}

Specialized Chart Examples

big_value - Hero metrics with large display:

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

• Optional comparison object: {"value": 10300, "format": "usd", "label": "vs last month"} shows change with arrow

dumbbell - Before/after comparisons with directional coloring:

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

• Green = improvement, Red = decline, Grey = no change
• higherIsBetter: false for rankings (lower = better)
• Labels auto-abbreviate large numbers (7450 → "7k")

delta - Change metrics with directional coloring:

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

• Positive values show green with ▲, negative show red with ▼
• Optional comparison object: {"value": 0.05, "label": "vs Target"}

area - Filled line chart for cumulative/volume data:

{
  "type": "area",
  "title": "Daily Active Users",
  "x": "date",
  "y": "users",
  "data": [{"date": "Mon", "users": 1200}, {"date": "Tue", "users": 1450}]
}

combo - Bar + line with dual Y-axis:

{
  "type": "combo",
  "title": "Revenue vs Growth Rate",
  "x": "quarter",
  "y": ["revenue", "growth_rate"],
  "data": [
    {"quarter": "Q1", "revenue": 1000000, "growth_rate": 0.15},
    {"quarter": "Q2", "revenue": 1200000, "growth_rate": 0.20}
  ]
}

• First y-field renders as bars, second as line
• Dual Y-axes with independent scales

heatmap - 2D matrix visualization:

{
  "type": "heatmap",
  "title": "Activity by Hour",
  "xCategories": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "yCategories": ["9am", "12pm", "3pm", "6pm"],
  "format": "num0",
  "data": [[0, 0, 85], [1, 0, 90], [2, 0, 72]]
}

• format option applies to cell labels (e.g., num0k, usd0k, pct)

funnel - Conversion or elimination flows:

{
  "type": "funnel",
  "title": "Sales Pipeline",
  "format": "num0",
  "data": [
    {"stage": "Leads", "value": 1000},
    {"stage": "Qualified", "value": 600},
    {"stage": "Proposal", "value": 300},
    {"stage": "Closed", "value": 100}
  ]
}

• format option applies to labels/tooltips (e.g., usd_auto, pct, num0)

waterfall - Cumulative change visualization:

{
  "type": "waterfall",
  "title": "Revenue Bridge",
  "x": "item",
  "y": "value",
  "data": [
    {"item": "Start", "value": 1000, "isTotal": true},
    {"item": "Growth", "value": 200},
    {"item": "Churn", "value": -50},
    {"item": "End", "value": 11