matsonj/mviz

mviz v1.7.0

クリーンでデータ重視のチャートとダッシュボードを、コンパクトなJSONスペックまたはMarkdownから生成します。データインク比を最大化し、チャートジャンク、グリッドライン、装飾要素は最小限に抑えます。16カラムのグリッドレイアウトシステムを使用します。

セットアップ

インストールは不要です。npx -y -q mvizを使用すると、npmから自動ダウンロードされます。-qフラグはnpmの出力を減らしつつ、lintエラーは表示します。

頻繁に使用する場合は、グローバルインストール: npm install -g mviz

このスキルの機能

mvizは2つの要素で構成されています:

1. スペック言語 — コンポーネント（チャート、KPI、テーブル、メモなど）を記述するフェンスコードブロックを含むMarkdown。1つのMarkdownファイル（または単一のJSONスペック）で可視化全体を記述します。
2. レンダラーのセット — スペックをさまざまな表示コンテキスト向けのHTMLに変換します。現在2つあります:
   • visualize:show_widget（インライン）— claude.aiで可視化ツールが利用可能な場合、mvizスペックをwidget_code HTMLフラグメントとしてレンダリングします（claude.aiのデザインシステム、Chart.js、var(--color-*) トークンを使用）。ウィジェットは会話内にインライン表示されます。
   • mviz CLI（スタンドアロン）— mviz dashboard.md -o report.html で、mviz独自のデザインシステム（mdsinaboxテーマ、ECharts）を使用した完全なHTMLドキュメントを生成します。ダウンロード、iframeタイル、印刷/PDFに適しています。

mviz Markdownスペックが正規のものであり、レンダラーは可視化が表示される場所に基づいて選択されます。同じスペック、2つのレンダリング。サードパーティがスペックを変更せずに別のレンダラー（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レンダラーは、上記のmdsinaboxテーマでスタイル設定された完全なHTMLドキュメントを生成します。出力は、直接ブラウザ表示、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を削除、JSの最小化など）が適用されます。

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

埋め込みモードは完全なHTMLドキュメント（DOCTYPE + html + head + body そのまま）を出力します。visualize:show_widget には適していません。その場合は別のレンダラーを使用してください（下記参照）。

16カラムグリッドシステム

コンポーネントのサイズは size=[cols,rows] 構文で指定します:

```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カラム の総幅（ポートレートとランドスケープの両方）
• 行の高さ: 行単位あたり約32px（おおよそ - チャートにはパディングがあります）
• ページ容量: ポートレート [16c × 30r]、ランドスケープ [16c × 22r]
• 同じ行のコンポーネントは行を共有
• 空行 = 新しい行

高さのガイドライン:

行単位	おおよその高さ	適しているもの
2	~64px	KPI、1行のメモ
4	~128px	小さなテーブル、テキストブロック
5-6	~160-192px	標準的なチャート
8+	~256px+	密度の高いテーブル、詳細なチャート

多くのカテゴリ（10本以上の棒、10行以上のダンベル）を持つチャートの場合は、圧縮を防ぐためにより多くの行単位に増やします。

横並びレイアウト

重要: コンポーネントを横に並べるには、それらのコードブロックの間に空行を入れないでください:

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

これにより、Chart AとChart Bが同じ行にレンダリングされます。間に空行を入れると、別々の行に配置されます。

見出しとセクション区切り

構文	効果
# H1	ページタイトル
## H2	セクションタイトル
### H3	軽量インラインヘッダー（控えめ、小さいテキスト）
---	視覚的な区切り線
===	印刷用の改ページ
empty_space	非表示のグリッドセルスペーサー（デフォルト4カラム×2行）

見出しのガイドライン:

• ページタイトルは、frontmatter title: または 先頭の# H1のいずれかで設定し、両方を使用しないでください。
• ページ内のセクションタイトルには ## H2 を使用します（最も一般的）。
• 流れを中断しない軽量な小見出しには ### H3 を使用します。

セクション区切りと改ページ:

• --- を使用して、論理的なセクションを視覚的に区切ります。必要に応じてコンテンツは自然に次のページに流れます。
• === は、明示的に新しいページを強制する場合（例：PDF出力用に章や主要レポートセクションを分ける）にのみ使用します。
• デフォルトで === を使用しないでください。ユーザーが特別に要求した場合にのみ改ページを追加します。

デフォルトサイズ

コンポーネント	デフォルトサイズ	備考
big_value	[4, 2]	1行に4つ収まる
delta	[4, 2]	1行に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]	全幅、1行
empty_space	[4, 2]	非表示のスペーサー

推奨サイズの組み合わせ

レイアウトの目的	コンポーネント	サイズ
1行に4つのKPI	4× big_value	各[4,2]
1行に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カラム）の行が作成されます。

例：2つのチャートを横並び

```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の場合、テーブルの上に「任意の値でフィルター…」検索入力が表示されます。行は、すべてのセルで大文字小文字を区別しないcontains一致に基づいてライブフィルタリングされます。

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

メモタイプ

メモは、noteType を介して3つの重大度レベルをサポートしています:

タイプ	ボーダーカラー	使用目的
default	赤	重要な通知（デフォルト）
warning	黄色	注意事項、暫定データ
tip	緑	ベストプラクティス、プロのヒント

メモはオプションの label もサポートしており、太字の接頭辞テキストとして使用されます:

{"type": "note", "label": "プロのヒント:", "content": "キーボードショートカットを使用すると、より速くナビゲートできます。", "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フィールドは棒、2番目は折れ線としてレンダリング
• 独立したスケールのデュアルY軸

heatmap - 2Dマトリックス可視化:

{
  "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 をサポート

…

[truncated for translation]