mviz

mviz v1.6.4

# 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 -y -q mviz` which auto-downloads from npm. The `-q` flag reduces npm output while still showing lint errors.

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)

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

### Dashboard from Markdown

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

### Dashboard from Folder

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

## 16-Column Grid System

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

````markdown
```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 columns** total width (both portrait and landscape)
- **Row height**: ~32px per row unit (approximate - charts have padding)
- **Page capacity**: Portrait [16c × 30r], Landscape [16c × 22r]
- 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:

````markdown
```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 title |
| `## H2` | Section title |
| `### H3` | Light inline header (subtle, smaller text) |
| `---` | Visual divider line |
| `===` | Page break for printing |
| `===` | 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 |
| `mermaid` | [8, 5] | Half width (use `ascii: true` for text art) |
| `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

````markdown
```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"}
```
````

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

### Example: Two Charts Side by Side

````markdown
```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, mermaid

**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")

```json
{
  "type": "table",
  "columns": [
    {"id": "product", "title": "Product", "bold": true},
    {"id": "category", "title": "Category", "italic": true},
    {"id": "sales", "title": "Sales", "fmt": "currency"},
    {"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:

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

### Specialized Chart Examples

**big_value** - Hero metrics with large display:
```json
{"type": "big_value", "value": 1250000, "label": "Revenue", "format": "currency0m"}
```
- Optional `comparison` object: `{"value": 10300, "format": "currency", "label": "vs last month"}` shows change with arrow

**dumbbell** - Before/after comparisons with directional coloring:
```json
{
  "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:
```json
{"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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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`, `currency0k`, `pct`)

**funnel** - Conversion or elimination flows:
```json
{
  "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., `currency_auto`, `pct`, `num0`)

**waterfall** - Cumulative change visualization:
```json
{
  "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": 1150, "isTotal": true}
  ]
}
```

**bubble** - Scatter with size dimension. Supports `series` for color grouping and `showLabels` for persistent labels:
```json
{
  "type": "bubble",
  "title": "Market Analysis",
  "x": "growth",
  "y": "profit",
  "size": "revenue",
  "series": "region",
  "label": "company",
  "data": [
    {"growth": 5, "profit": 20, "revenue": 100, "region": "US", "company": "Acme"},
    {"growth": 10, "profit": 15, "revenue": 200, "region": "EU", "company": "Beta"}
  ]
}
```

**sankey** - Flow diagrams showing relationships:
```json
{
  "type": "sankey",
  "title": "Traffic Sources",
  "data": [
    {"source": "Organic", "target": "Landing", "value": 500},
    {"source": "Paid", "target": "Landing", "value": 300},
    {"source": "Landing", "target": "Signup", "value": 400}
  ]
}
```

**mermaid** - Diagrams from Mermaid syntax (flowcharts, sequence, state, class, ER). Use array for multi-line code:
```json
{
  "type": "mermaid",
  "title": "User Flow",
  "code": [
    "graph TD",
    "  A[Start] --> B{Decision}",
    "  B -->|Yes| C[Action]",
    "  B -->|No| D[End]"
  ]
}
```

**mermaid (ASCII)** - ASCII/Unicode text-based diagrams (set `ascii: true`):
```json
{
  "type": "mermaid",
  "title": "Process Flow",
  "code": ["graph LR", "  A[Input] --> B[Process] --> C[Output]"],
  "ascii": true
}
```

**Mermaid lint rules** (errors that will fail validation):
- No `<br/>` tags in labels (render as literal text, not line breaks)
- No quoted labels like `A["text"]` in flowcharts (quotes appear in output)

## Number Format Options

| Format | Example | Use For |
|--------|---------|---------|
| `auto` | 1.000m, 10.00k | **Smart auto-format (recommended)** |
| `currency_auto` | $1.000m, $10.00k | Smart auto-format with $ prefix |
| `currency0m` | $1.2m | Millions |
| `currency0b` | $1.2b | Billions |
| `currency0k` | $125k | Thousands |
| `currency` | $1,250,000 | Detailed amounts |
| `num0m` | 1.2m | Millions |
| `num0b` | 1.2b | Billions |
| `num0k` | 125k | Thousands |
| `num0` | 1,250,000 | Detailed counts |
| `pct` | 15.0% | Percentage with decimal |
| `pct0` | 15% | Percentage integer |
| `pct1` | 15.0% | Percentage with 1 decimal |

**Important:** Percentage formats expect decimal values (0.25 = 25%), not whole numbers.

**Smart formatting (`auto`/`currency_auto`) is recommended.** The `format` option applies to both axis labels and data labels on bar charts. It automatically picks the right suffix (k, m, b) based on magnitude and always shows 4 significant digits. Negative values are wrapped in parentheses: `(1.000m)`.

When no format is specified, smart formatting is used by default.

### Auto-Detected Axis Formatting

Chart axes automatically detect the appropriate format based on field names:

| Field Pattern | Auto Format | Example |
|---------------|-------------|---------|
| revenue, sales, price, cost, profit, amount | `currency_auto` | $1.250m |
| pct, percent, rate, ratio | `pct` | 15.0% |
| All other numeric fields | `auto` | 1.250m |

Override with an explicit `format` field in the chart spec.

## Columnar Data Format

The chart generator auto-detects columnar query results. Instead of manually converting `columns`/`rows` to `data`, pass the result directly:

```json
{
  "type": "bar",
  "title": "Sales by Region",
  "x": "region",
  "y": "sales",
  "columns": ["region", "sales"],
  "rows": [["North", 45000], ["South", 32000], ["East", 28000]]
}
```

This is automatically converted internally. No manual JSON reconstruction needed.

## Axis Bounds (yMin/yMax)

For line, area, bar, and combo charts, control y-axis range with `yMin` and `yMax`:

```json
{
  "type": "line",
  "title": "Elo Rating Trend",
  "x": "date",
  "y": "elo",
  "yMin": 1400,
  "data": [{"date": "Oct", "elo": 1511}, {"date": "Jan", "elo": 1636}]
}
```

Use `yMin` when:
- Data doesn't start at 0 (ratings, stock prices, temperatures)
- You want to emphasize relative changes over absolute values

Use `yMax` when:
- Labels are being cut off at the top of the chart
- You need headroom above the highest data point

## Validation & Lint Rules

The CLI validates specs automatically using built-in lint rules. Use `--lint` flag for validation-only mode:

```bash
npx -y -q mviz --lint dashboard.md  # Validate without generating HTML
```

### Lint Rules

| Rule | Severity | Trigger |
|------|----------|---------|
| `required-fields` | warning | Missing required fields like `x`, `y`, or `data` |
| `unknown-field` | warning | Field not recognized for the chart type |
| `time-series-sorted` | error | Time series data not in chronological order |
| `sankey-wrong-keys` | error | Using `from`/`to` instead of `source`/`target` |
| `big-value-string` | error | Passing `"62.5%"` string instead of `0.625` number |
| `duplicate-x-values` | warning | Duplicate values on x-axis |
| `mermaid-no-br-tags` | error | `<br/>` tags in mermaid code (render as literal text) |
| `mermaid-no-quoted-labels` | error | Quoted labels like `A["text"]` in flowcharts |

**Errors** exit with code 1. **Warnings** log to stderr but don't fail.

### Common Fixes

**Time series error:** Sort your data by date before passing to the chart.

**Sankey wrong keys:** Use `source`, `target`, `value` in your data:
```json
{"source": "A", "target": "B", "value": 100}
```

**big_value string:** Pass numeric value with format option:
```json
{"type": "big_value", "value": 0.625, "format": "pct0", "label": "Rate"}
```

## Troubleshooting

### Warning Messages

The generator outputs helpful warnings to stderr when issues are detected:

| Warning | Cause | Solution |
|---------|-------|----------|
| `Invalid JSON in 'bar' block` | Malformed JSON syntax | Check JSON syntax, ensure proper quoting |
| `Unknown component type 'bars'` | Typo in chart type | Use suggested type (e.g., `bar` not `bars`) |
| `Cannot resolve 'file=...'` | File reference without base directory | Use file path argument or inline JSON |
| `Row exceeds 16 columns` | Too many components in one row | Reduce component widths or split into rows |

Warnings include context like content previews, similar type suggestions, and section/row info.

### Labels Cut Off at Chart Edges

If data labels on bar, line, or area charts are being cut off at the top:

1. Find the maximum value in your data
2. Set `yMax` to ~10-15% higher than that value

**Example:** If max value is 200, set `"yMax": 220`

```json
{
  "type": "bar",
  "title": "Sales",
  "x": "month",
  "y": "sales",
  "yMax": 250,
  "data": [{"month": "Jan", "sales": 180}, {"month": "Feb", "sales": 220}]
}
```

This provides headroom for the label text above the bars.

## Data Generation Best Practice

**Use SQL to generate data files** instead of manually authoring JSON. This reduces errors and ensures data accuracy:

```sql
-- Generate chart data file
COPY (
  SELECT month, SUM(sales) as sales, SUM(revenue) as revenue
  FROM orders
  GROUP BY month
  ORDER BY month
) TO 'data/monthly-sales.json' (FORMAT JSON, ARRAY true);
```

Then reference the generated file:

````markdown
```bar file=data/monthly-sales.json
{"title": "Monthly Sales", "x": "month", "y": "sales"}
```
````

This approach:
- Ensures data accuracy (no manual transcription errors)
- Keeps data in sync with source systems
- Reduces token usage (SQL is more compact than JSON arrays)
- Makes updates easy (re-run query to refresh)

## File References (JSON and CSV)

Reference external data files to save tokens and enable data/visualization separation:

### JSON Files
````markdown
```bar size=[8,6] file=data/sales.json
```
````

### CSV Files (DuckDB Workflow)

CSV files work great with DuckDB for data exploration:

```bash
# Export query results to CSV
duckdb -csv -c "SELECT quarter, revenue FROM sales" > data/quarterly.csv
```

````markdown
```bar file=data/quarterly.csv
{"title": "Quarterly Revenue", "x": "quarter", "y": "revenue"}
```
````

- **CSV provides data**, inline JSON provides chart options (title, x, y, format)
- **Auto-detection**: If no inline options, first column = x, second column = y
- **Type conversion**: Numeric strings auto-convert to int/float

### Benefits of File References

| Approach | Best For |
|----------|----------|
| Inline JSON | Small, static specs |
| JSON files | Reusable chart configs |
| CSV files | DuckDB workflows, frequently updated data |

## Dashboard Markdown Format

````markdown
---
theme: light
title: My Dashboard
---

# Page Title

## Section Name

```big_value size=[4,2]
{"value": 125000, "label": "Revenue", "format": "currency0k"}
```
```bar size=[12,6] file=data/sales.json
```
````

**Rules:**
- `# Title` sets the page title (first occurrence only)
- `## Section` creates a new section with divider (border, spacing)
- `### Header` creates a soft header within the current section (no divider)
- `---` creates a section break (untitled, visual divider only)
- `===` creates a page break (forces new page when printing to PDF)
- `size=[cols,rows]` controls layout (16-column grid)
- `size=auto` auto-calculates size from data
- `file=path` references external JSON
- Empty lines = new rows

## Theme Toggle

Dashboards include a theme toggle button (top right) that switches between light and dark modes. All charts dynamically update when the theme changes.

Set the default theme in frontmatter:

```yaml
---
title: My Dashboard
theme: dark
orientation: landscape
print: true
---
```

| Option | Description |
|--------|-------------|
| `title` | Dashboard title displayed at top |
| `theme` | `light` (default) or `dark` |
| `orientation` | `portrait` (default) or `landscape` for print layout |
| `print` | When `true`, requires explicit `size=[cols,rows]` on all components |
| `continuous` | When `true`, removes section breaks between `#` headers for flowing layout |

**Page capacity:** Portrait fits 30 row units, landscape fits 22 row units (Letter paper, 0.5" margins).

The theme toggle affects all charts globally - individual chart `theme` settings are ignored in favor of the global toggle.

## Custom Themes

Load custom brand colors and fonts from a YAML file:

```bash
npx -y -q mviz --theme my_theme.yaml dashboard.md -o dashboard.html
```

Example theme file:
```yaml
name: brand-colors
extends: light

colors:
  primary: "#1a73e8"
  secondary: "#ea4335"

palette:
  - "#1a73e8"
  - "#ea4335"
  - "#fbbc04"

fonts:
  family: "'Roboto', sans-serif"
  import: "https://fonts.googleapis.com/css2?family=Roboto&display=swap"
```

Custom themes merge with defaults - only specify what you want to override.

## Print and PDF Support

Charts are optimized for printing to PDF:

- **High-Quality Rendering**: Uses SVG renderer for crisp vector graphics at any zoom level
- **No Page Breaks**: CSS prevents charts and tables from being split across pages
- **All Labels Visible**: Category labels always shown with 45° rotation to fit

When printing dashboards to PDF, all content stays intact without being cut off mid-chart.

## JSON Formatting for Editability

**Use formatted (multi-line) JSON** when data may need editing. This enables smaller, more precise edits:

````markdown
```bar size=[8,5]
{
  "title": "Monthly Sales",
  "x": "month",
  "y": "sales",
  "data": [
    {"month": "Jan", "sales": 120},
    {"month": "Feb", "sales": 150},
    {"month": "Mar", "sales": 180}
  ]
}
```
````

**Benefits:**
- Each data point on its own line enables targeted edits
- Changing one value: ~30 chars vs ~200+ chars with compact JSON
- Easier to review diffs in version control

**When to use compact JSON:**
- Very small specs (< 100 chars)
- Data that won't change
- Single-line values like `{"value": 1250000, "label": "Revenue"}`

## JSON Schema

mviz specs can be validated using the JSON Schema at:

```
https://raw.githubusercontent.com/matsonj/mviz/main/schema/mviz.schema.json
```

Add `$schema` to enable editor autocomplete and validation:

```json
{
  "$schema": "https://raw.githubusercontent.com/matsonj/mviz/main/schema/mviz.schema.json",
  "type": "bar",
  "title": "Sales",
  ...
}
```

## Color Palette (mdsinabox theme)

| Color | Hex | Use |
|-------|-----|-----|
| Primary Blue | `#0777b3` | Primary series |
| Secondary Orange | `#bd4e35` | Secondary series, accent |
| Info Blue | `#638CAD` | Tertiary, informational |
| Positive Green | `#2d7a00` | Success, positive values |
| Warning Amber | `#e18727` | Warnings |
| Error Red | `#bc1200` | Errors, negative emphasis |

See `reference/chart-types.md` for complete documentation.

## Your Role

You are an analytics assistant helping a human who has decision-making context that you lack. Your job is to present data clearly and surface patterns worth investigating—not to draw conclusions or make recommendations.

**Key principles:**
- Use a matter-of-fact tone. State what the data shows, not what it means.
- Design analysis that invites further questions, not analysis that closes them.
- Surface anomalies and patterns without assuming their cause or significance.
- Let the human add context and make decisions.

For additional guidance on creating effective data visualizations—including Tufte-inspired principles, anti-patterns to avoid, and layout examples—see `Best_practices.md`.

## Feedback

Having issues with mviz? Ask Claude to create a friction log documenting the problem, then open it as an issue at https://github.com/matsonj/mviz/issues