matsonj/mviz

mviz v1.7.0

mviz 是做什麼的？

從簡潔的 JSON 規格或 Markdown 中生成乾淨、以資料為核心的圖表與儀表板。最大化資料-墨水比，盡可能減少圖表垃圾、網格線及裝飾性元素。使用 16 欄網格佈局系統。

設定

無需安裝。使用 npx -y -q mviz 即可自動從 npm 下載。-q 標記可減少 npm 的輸出訊息，同時仍會顯示 lint 錯誤。

如需更頻繁地重複使用，可進行全域安裝：npm install -g mviz

此技能的功能

mviz 包含兩個部分：

1. 一種規格語言 — 以 Markdown 搭配圍籬式程式碼區塊來描述元件（圖表、KPI、表格、備註等）。一個 Markdown 檔案（或單一 JSON 規格）即可描述整個視覺化作品。
2. 一組渲染器 — 將規格轉換為 HTML，以適應不同的顯示情境。目前有兩種渲染器：
   • visualize:show_widget（內嵌） — 當您在 claude.ai 且可用的視覺化工具時，將 mviz 規格渲染為 widget_code HTML 片段，使用 claude.ai 的設計系統（Chart.js、var(--color-*) 變數）。該 Widget 會直接內嵌在對話中顯示。
   • mviz CLI（獨立） — mviz dashboard.md -o report.html 會產生一份完整的 HTML 文件，採用 mviz 自身的設計系統（mdsinabox 主題、ECharts）。適用於下載、iframe 嵌入、列印/PDF 輸出。

mviz 的 Markdown 規格是標準格式；渲染器的選擇取決於視覺化內容將出現的位置。同一份規格，兩種呈現方式。第三方可以建立不同的渲染器（例如基於 Chart.js 的 CLI、Slack 主題渲染器等），而無需更改規格。

選擇渲染器

請務必先撰寫 mviz Markdown 規格，即使最終目標是內嵌渲染。規格是標準產出物——請在回應中以圍籬式程式碼區塊發出，以便使用者日後複製/重複使用/透過 CLI 傳遞。然後再根據需求選擇合適的渲染器進行渲染。

在渲染之前，請決定哪個渲染器更適合——並說明您的推斷，以便使用者可以糾正您。一些判斷線索：

內嵌（visualize:show_widget）：

• 「顯示 X」、「X 是什麼」、「X 如何變化」、「渲染」
• 小型視覺化（通常 1-4 個元件），與前後文順暢銜接
• 使用者正在探索資料，而非準備分享內容
• 此對話中可使用 visualize:show_widget

獨立（mviz CLI）：

• 「製作一份報告」、「寄檔案給我」、「匯出為 PDF」、「儲存」
• 多章節組合式檢視（5 個以上元件、分隔線、分頁符、全寬表格）
• 使用者想要儲存、分享、列印或嵌入到外部主機（iframe 嵌入、儀表板儲存格）
• visualize:show_widget 不可用（無內嵌渲染表面）

當不明確時，預設使用內嵌渲染。請明確說明您的推斷：

「由於您要求在對話中查看，我將使用內嵌渲染。如果您偏好可下載的檔案，我可以對同一份規格執行 mviz CLI——只要說一聲即可。」

如果之後使用者要求將內嵌渲染的內容轉為檔案版本，對話中已有規格——直接將其透過 mviz ... -o out.html 傳遞即可，無需重新撰寫。

視覺風格（mdsinabox 主題 — 適用於 CLI 渲染器）

• 字型：Helvetica Neue, Arial（乾淨的無襯線字體）
• 標誌：儀表板頂端的橘色強調線
• 調色盤：藍色為主色，橘色為強調色，語義色（綠色=正面，琥珀色=警告，紅色=錯誤）
• 背景：淺色為紙色（#f8f8f8）/ 深色為暗色（#231f20）
• 原則：高資料-墨水比，無圖表垃圾，最少的網格線，讓資料本身說話

渲染器：mviz CLI（獨立 HTML）

CLI 渲染器會產生一份完整的 HTML 文件，樣式採用上述的 mdsinabox 主題。輸出內容適用於直接以瀏覽器檢視、匯出為 PDF、透過 iframe 嵌入，或做為檔案分享。

單一圖表（JSON）

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

從 Markdown 建立儀表板

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

從資料夾建立儀表板

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

Iframe 嵌入輸出（--embed）

當渲染的 HTML 將會放在其他產品的 iframe 內（例如 mdw-turbo Prism 嵌入、儀表板儲存格等）時，請加上 --embed 參數以移除頁面外框（紅色強調列、標題列、主題切換器），並套用一系列後處理來精簡主體：CSS 修剪、透明背景（讓主機的卡片外框透出）、無圖表時移除 ECharts 腳本、無 marked.parse(...) 呼叫時移除 marked、JavaScript 壓縮等。

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

嵌入模式會產出完整的 HTML 文件（DOCTYPE + html + head + body 均完整）。它不適用於 visualize:show_widget——對於那種情況，請使用另一個渲染器（參見下方說明）。

16 欄網格系統

元件使用 size=[欄數,列數] 語法設定尺寸：

```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 欄（直向與橫向均適用）
• 行高：每列單位約 32 像素（近似值——圖表會有內距）
• 頁面容量：直向 [16 欄 × 30 列]、橫向 [16 欄 × 22 列]
• 同一行的元件會共用該列
• 空行 = 新的一列

高度參考指南：

列單位	大約高度	適用於
2	~64px	KPI、單行備註
4	~128px	小型表格、文字區塊
5-6	~160-192px	標準圖表
8+	~256px+	密集表格、細節圖表

對於具有多個類別（10+ 長條、10+ 啞鈴圖列）的圖表，請增加列單位以防止壓縮。

並排佈局

重要： 要將元件並排放置，它們的程式碼區塊之間不能有空白行：

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

這會讓圖表 A 和圖表 B 顯示在同一列。在它們之間加入空白行會使它們分開成不同列。

標題與區段分隔

語法	效果
# H1	頁面標題
## H2	區段標題
### H3	輕量級內聯標題（不明顯、較小文字）
---	視覺分隔線
===	列印分頁
empty_space	不可見的網格儲存格間距（預設 4 欄 × 2 列）

標題使用指南：

• 使用 frontmatter 中的 title: 或 開頭的 # H1 來設定頁面標題，兩者擇一，不要同時使用。
• 在頁面內使用 ## H2 作為區段標題（最常見）。
• 使用 ### H3 作為不中斷流程的輕量級子標題。

區段分隔 vs 分頁：

• 使用 --- 在視覺上分隔邏輯區段。內容會自然流動到下一頁（如有需要）。
• 僅在明確需要強制換頁時使用 ===（例如分隔章節或 PDF 輸出中的主要報告部分）。
• 預設情況下絕不使用 ===。僅在使用者明確要求時才加入分頁。

預設尺寸

元件	預設尺寸	備註
big_value	[4, 2]	每列可放 4 個
delta	[4, 2]	每列可放 4 個
sparkline	[4, 2]	緊湊的內聯圖表
bar, line, area	[8, 5]	半寬
pie, scatter, bubble	[8, 5]	半寬
funnel, sankey, heatmap	[8, 5]	半寬
histogram, boxplot, waterfall	[8, 5]	半寬
combo	[8, 5]	半寬
dumbbell	[12, 6]	3/4 寬度
table	[16, 4]	全寬
textarea	[16, 4]	全寬
calendar	[16, 3]	全寬
xmr	[16, 6]	全寬、高
mermaid	[8, 5]	半寬（使用 ascii: true 可產生文字藝術）
alert, note, text	[16, 1]	全寬、單行
empty_space	[4, 2]	不可見的間距元件

推薦的尺寸配對

佈局目標	元件	尺寸
同一列 4 個 KPI	4× big_value	每個 [4,2]
同一列 5 個 KPI	4× big_value + 1 個較寬	[3,2] + [4,2]
KPI + 說明文字	big_value + textarea	[3,2] + [13,2]
KPI + 圖表	big_value + bar	[4,2] + [12,5]

範例：密集 KPI 列

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

這會建立一列包含 5 個 KPI（3+3+3+3+4 = 16 欄）。

範例：兩個圖表並排

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

支援的類型

圖表： bar, line, area, pie, scatter, bubble, boxplot, histogram, waterfall, xmr, sankey, funnel, heatmap, calendar, sparkline, combo, dumbbell, mermaid

UI 元件： big_value, delta, alert, note, text, textarea, empty_space, table

表格格式化

表格支援欄位層級和儲存格層級的格式化：

欄位選項： bold, italic, type（"sparkline" 或 "heatmap"）

{
  "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]}
  ]
}

儲存格層級覆寫： 使用 {"value": "text", "bold": true} 來覆寫欄位的預設值。

熱力圖：根據數值高低套用顏色漸層。文字在深色背景上會自動切換為白色。

走勢圖類型： line, bar, area, pct_bar（進度條）, dumbbell（前/後比較）

排序與篩選：

欄位	值	預設值	效果
sortable	true / false	true	點選欄位標題即可排序。循環切換：升序 → 降序 → 取消排序。數值欄位依原始數值排序。
filter	true / false	false	設為 true 時，在表格上方顯示「依任何值篩選…」的搜尋輸入框。系統會即時對所有儲存格進行不區分大小寫的包含比對來篩選列。

範例：{"type": "table", "filter": true, "columns": [...], "data": [...]}

備註類型

備註支援三種嚴重程度，透過 noteType 指定：

類型	邊框顏色	用途
default	紅色	重要通知（預設）
warning	黃色	警告、初步資料
tip	綠色	最佳實踐、專業提示

備註也支援可選的 label 欄位，用於粗體前綴文字：

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

特殊圖表範例

big_value - 大型顯示的關鍵指標：

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

• 可選的 comparison 物件：{"value": 10300, "format": "currency", "label": "vs last month"} 會顯示帶有箭頭的變化量

dumbbell - 具方向性顏色編碼的前後比較：

{
  "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}
  ]
}

• 綠色 = 改善，紅色 = 下滑，灰色 = 無變化
• higherIsBetter: false 適用於排名（越低越好）
• 標籤會自動縮寫大數字（7450 → "7k"）

delta - 具方向性顏色編碼的變化指標：

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

• 正值以綠色顯示並附 ▲，負值以紅色顯示並附 ▼
• 可選的 comparison 物件：{"value": 0.05, "label": "vs Target"}

area - 用於累積/量體資料的填滿折線圖：

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

combo - 具有雙 Y 軸的長條圖 + 折線圖：

{
  "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}
  ]
}

• 第一個 y 欄位渲染為長條，第二個渲染為折線
• 雙 Y 軸，各自獨立縮放

heatmap - 二維矩陣視覺化：

{
  "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 選項適用於儲存格標籤（例如 num0k, currency0k, pct）

funnel - 轉換或淘汰流程：

{
  "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 選項適用於標籤/工具提示（例如 currency_auto, pct, num0）

waterfall - 累積變化視覺化：

{
  "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 - 帶有尺寸維度的散佈圖。支援 series 進行顏色分組和 showLabels。