household-finance-dashboard-builder

家計ダッシュボードビルダー

目次

• 概要
• 出力形式
• 入力仕様
• ワークフロー
• 6つのパネル
• 適用する認知原則
• ストーリーテリングのオーバーレイ
• HTMLのひな形
• ガードレール

概要

これは、より汎用的な d3-visualization スキルの静的出力版です。データとグラフのコードがすべてインライン化された、サーバーなしであらゆるブラウザーで開ける、自己完結型の単一HTMLファイルを生成します。このダッシュボードは、家計のJSONデータストアから毎週再生成され、reports/dashboards/YYYY-MM-DD-weekly.html にコミットされるよう設計されています。

このスキルでは、家計ファイナンスのスキーマ（口座、取引、残高、定期支出、目標、投資、住宅ローン、アラート）に準拠したJSONストアを前提とします。

出力形式

以下を含む単一のHTMLファイルです。

• インラインの <style> ブロック（外部CSSなし）。
• インラインのデータブロック：<script id="dashboard-data" type="application/json">{...}</script>。
• インラインに同梱されたD3 v7（または、オフラインでのレンダリングが許容される場合は、整合性ハッシュ付きの単一の <script> タグ）。
• CSS Gridでレンダリングされる6つのパネル。
• visual-storytelling-design で生成された短いナラティブヘッダー。
• 生成日時とソースデータのバージョンを記載したフッター。

ファイルサイズの目標：1 MB未満。これを超える場合は、埋め込む前に時系列データをダウンサンプリングしてください（通常は日次から週次に集計すれば十分です）。

入力仕様

呼び出し元は以下を指定します。

• data_root — 家計ファイナンスの data/ ディレクトリへのパス。
• output_path — HTMLの出力先。
• generated_for — weekly または monthly（期間と見出しが変わります）。
• as_of — スナップショットの日付を表すISO形式の日付。
• prior_snapshot_path（任意）— 前回のダッシュボードのデータブロック。前週比の差分に使用します。

このスキルは以下を読み込みます。

• accounts.json
• balances.json
• transactions.json（対象期間で絞り込み）
• recurring.json
• goals.json
• investments.json
• mortgage.json
• reports/alerts/ 内の最近のファイル
• ナラティブのコンテキスト用に、reports/monthly/*.json の中で最も新しいファイル。

ワークフロー

Dashboard Build Progress:
- [ ] Step 1: Read data; validate completeness; compute snapshot
- [ ] Step 2: Compute the six panel datasets
- [ ] Step 3: Apply cognitive-design principles to layout choices
- [ ] Step 4: Generate narrative header via visual-storytelling-design
- [ ] Step 5: Render HTML scaffold + inline data + D3 code per panel
- [ ] Step 6: Run cognitive-fallacies-guard self-check on charts
- [ ] Step 7: Write to output_path; emit data quality footer

ステップ1 — スナップショット

見出しとなる数値を計算します。

• net_worth_cents — 現金＋投資額＋住宅の推定持分−負債（住宅ローン＋その他）の合計。
• delta_vs_prior_cents — 前回のスナップショットがある場合は、その値との差分。
• month_to_date_spend_cents、month_to_date_income_cents、month_to_date_savings_rate。
• goals_on_track、goals_behind、goals_ahead の件数。
• alerts_open の件数。

必須ファイルが欠けている場合は、適切にフォールバックしてください。そのパネルを非表示にし、フッターに data_gap の行を表示します。

ステップ2 — パネルのデータセット

各パネルに必要なデータを正確に計算します（6つのパネルを参照）。配列は小さく保ち、グラフに必要な粒度に事前集計してください。

ステップ3 — 認知原則

以下のデフォルトを適用します（詳細な検討は cognitive-design に委ねます）。

• 視覚的階層。 ページ上で最も重要な数値は、純資産の増減です。最も大きく表示し、左上に配置します。
• チャンク化。 6つのパネルを3×2のグリッドに配置し、各パネルで示す洞察は1つに絞ります。
• 視覚表現の階層。 位置 > 長さ > 傾き > 面積 > 色相（ClevelandとMcGillによる）。比較パネルでは位置を使い、色はカテゴリの表現にのみ使用します。
• ワーキングメモリー。 1つのパネルでユーザーに比較させる項目は7つ以下にします。小さなカテゴリは「その他」にまとめます。
• 想起より認識。 すべての系列をグラフ上に直接ラベル付けします。凡例のみを使った表現は避けます。

ステップ4 — ナラティブヘッダー

visual-storytelling-design を呼び出し、3～5行のナラティブを生成します。

• トピックではなく洞察から始めます（「今週、純資産が4,200ドル増加しました。401kへの拠出と株式の値上がりが要因です」。 「週間アップデート」ではありません）。
• 前週／前月／前年との比較を示す文を1文入れます。
• アラートフィードから、注意が必要な事項を示す文を1文入れます。

ステップ 5 — レンダリング

HTML の骨組みを作成します（HTML scaffold を参照）。次をインラインに含めます。

• データブロック。
• 小さな D3 v7 バンドル（または整合性ハッシュ付きの外部 CDN）。
• パネルごとに 1 つの renderPanel*() 関数。

各レンダー関数では、d3-visualization の標準的な D3 データ結合パターンに従います。

ステップ 6 — セルフチェック

書き込む前に、レンダリングした SVG（またはそのデータと軸の設定）に対して cognitive-fallacies-guard を実行します。

• 変化を誇張する、途中で切れた軸がないこと。
• 3D 効果がないこと。
• ドーナツチャート：合計値を内側に表示すること。
• 円グラフ／ドーナツチャート：スライスは最大 6 つとし、残りは集約すること。
• 時系列：ゼロ基準線を含めること。ただし、シグナルが見えにくくなる場合を除きます。その場合は、基準線の変更を明示的に注記します。

セルフチェックで問題が見つかった場合は、修正して再レンダリングします。

ステップ 7 — 書き込み

output_path に書き込みます。生成日時、スキーマバージョン、最終ドロップ日、データの欠落を記載したフッターを出力します。

6 つのパネル

パネル 1 — 純資産の推移

データ：balances.json ＋ investments.json ＋ mortgage.json（負債としての current_principal）＋住宅資産の推定額（住宅価値 - current_principal）から算出した、月ごとの純資産データポイント。

チャート：重要なイベント（住宅ローンの組成、多額の拠出、市場の急変）を注記した折れ線グラフ。Y 軸は 0 から開始します（ここでは 0 が重要な純資産の尺度です）。X 軸は全履歴を対象とします。

見出しの注記：最新値 ＋ 前回のスナップショットとの差分。

パネル 2 — 月ごとのキャッシュフロー

データ：直近 12 か月分の月ごとの収入（正の棒）と支出（負の棒）、および 6 か月移動貯蓄率を示す折れ線。

チャート：収入を上向き、支出を下向きに表示する発散棒グラフに、貯蓄率の折れ線を重ねます。色：収入は落ち着いたティール、支出は落ち着いたコーラル。

ドリルダウン（任意、ホバー時）：最新月の支出カテゴリ上位 5 件。

パネル 3 — 定期支出とサブスクリプション

データ：recurring.json の有効な行をすべて、annualized_cost_cents の降順で並べます。

チャート：年換算コスト上位 15 件の横棒グラフ。各棒には、加盟店名 ＋ 頻度 ＋ 月額換算額をラベル表示します。

注記：すべての有効な定期支出の年換算コスト合計を上部に表示します。status: suspected_dormant のものや、金額変更イベントがあるものを強調表示します。

パネル 4 — 目標の進捗状況

データ：current_cents、target_cents、target_date を含む、goals.json のすべてのエントリ。

チャート：達成済みと残りを示す横向きの積み上げ棒グラフで、目標ごとに 1 行表示します。目標日までの直線的な進捗に基づき、各目標に「順調／遅れ／先行」と注記します。

見出し：「目標 X 件中 Y 件が順調です。」

パネル 5 — 資産配分

データ：investments.json の asset_class ごとに集計した保有資産（課税口座 ＋ 401k ＋ HSA）と、目標配分。

チャート：現在と目標のドーナツチャートを並べて表示するか、目標値のリングを重ねた単一のドーナツチャートを表示します。各スライスには資産クラス ＋ パーセンテージを直接ラベル表示します。

注記：最大乖離幅（パーセントポイント）。5pp を超える場合は警告します。

パネル 6 — 警戒フィード

データ：reports/alerts/ の最新 10 件を、重大度タグ付きで表示します。

表示形式：チャートではなく、スタイルを設定したリストです。各エントリには、重大度バッジ ＋ 根拠の要約（1 行）＋ 推奨アクションを表示します。

このパネルは、意図的にテキストを多くしています。ダッシュボードは情報提供と実務の両方を目的としているため、ユーザーがざっと目を通して、対応すべき項目を見つけられるようにします。

適用した認知原則

原則	このダッシュボードでの適用
前注意的属性	警戒パネルの重要度バッジには色相を使用し、それ以外はすべて位置で表します
ゲシュタルト近接	各パネルを余白で区切り、細い境界線と見出しを設けます
ゲシュタルト類似	すべての数値ラベルに同じ等幅フォントを使用し、すべてのグラフで同じ軸スタイルを使用します
読み順（Fパターン）	純資産を左上に、警戒事項を右下に配置します（読み進めた先で対応すべき項目を示します）
ワーキングメモリ	グラフごとのカテゴリは最大6つとし、残りは集約します
想起より認識	直接ラベルを付け、凡例だけのグラフは使用しません
データインク比	3D、チャートジャンク、装飾的なグラデーションは使用しません
メンタルモデル	キャッシュフローグラフでは、広く認知されている「増加は緑、減少は赤」の慣例を使用します

ストーリーテリングのオーバーレイ

ナラティブ見出しは、状況 → 変化 → 要因 → 注意が必要な点の順に構成します。

例：

純資産は1,247,300ドルで、今週は4,200ドル増加しました。 増加の大部分は、401kへの3,800ドルの拠出と、課税対象の証券口座での小幅な市場上昇によるものです。月初来の支出は7,840ドルで安定しており、目標の8,500ドルをわずかに下回っています。注意すべき点が1つあります。ポートフォリオの米国株比率が62.5％となり、目標の55％を7.5ポイント上回っています。今週のアラートにリバランス案が登録されています。

HTMLのひな形

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Household Finance — [date]</title>
  <style>
    /* layout: 3x2 grid; max-width 1280px; light theme */
    /* typography: Inter for text, JetBrains Mono for numbers */
    /* colors: muted, accessible, single accent for "needs attention" */
  </style>
</head>
<body>
  <header>
    <h1 class="net-worth-headline">$</h1>
    <p class="net-worth-delta">[+/-]$ this </p>
    <p class="narrative">[generated narrative]</p>
  </header>

  <main class="grid">
    <section id="panel-net-worth"></section>
    <section id="panel-cash-flow"></section>
    <section id="panel-recurring"></section>
    <section id="panel-goals"></section>
    <section id="panel-allocation"></section>
    <section id="panel-vigilance"></section>
  </main>

  <footer>
    <p>Generated [timestamp] from data/ as of [last-drop-date]. Schema version [X].</p>
    <p>Data gaps: [if any].</p>
  </footer>

  <script id="dashboard-data" type="application/json">
    { /* inlined data */ }
  </script>
  <script src="https://cdn.jsdelivr.net/npm/d3@7" integrity="sha384-..." crossorigin></script>
  <script>
    /* renderPanelNetWorth(), renderPanelCashFlow(), renderPanelRecurring(),
       renderPanelGoals(), renderPanelAllocation(), renderPanelVigilance() */
  </script>
</body>
</html>

完全なオフライン利用では、D3をCDN経由ではなくインラインで同梱してください。環境ごとの判断はダッシュボードエージェントが行います。

ガードレール

• 自己完結型のファイル。 外部データを取得しません。ユーザーはファイルをメールで送信したり、ディスクに保存したりしても、そのまま動作します。
• 誠実なグラフ。 棒グラフはゼロを基準とし、切り詰めたY軸、3D、チャートジャンクは使用しません。
• プライバシー。 このダッシュボードには世帯の財務情報が含まれます。口座番号はマスク（****1234）を埋め込み、完全な口座番号は決して使用しないでください。SSNは使用せず、マスクで十分な場合は氏名も記載しないでください。
• 再現性。 同じ入力データと同じ生成日であれば、タイムスタンプを除き、バイト単位で同一のHTMLを生成する必要があります。描画前にすべての配列を決定論的にソートしてください。
• パフォーマンス。 ファイルが1 MB未満に収まるよう、系列データをダウンサンプリングしてください。一般的なノートパソコンで、ダッシュボードが200ミリ秒未満で描画されるようにします。
• アクセシビリティ。 すべてのグラフにタイトルと概要を示すaria-labelsを設定します。各グラフの表形式の代替データには、「データを表示」トグルからアクセスできるようにします。
• モバイル対応。 幅768px未満ではグリッドを1列にし、フォントサイズを調整します。
• バージョン管理。 フッターにスキーマのバージョンと生成スクリプトのバージョンを記載し、将来の再生成を追跡できるようにします。