tufte-report

Tufte Report — データ駆動型インフォグラフィックスキル

Edward Tufte のスタイルに基づき、編集的なナラティブとインタラクティブなデータビジュアライゼーションを組み合わせた、単体で動作する HTML レポートを作成します。高い情報密度、最小限のチャート装飾、タイポグラフィを重視したデザインが特徴です。

デザイン哲学

Tufte の基本原則が、あらゆる判断の指針になります。

• データインク比：インクの各ピクセルは、装飾ではなくデータを表す必要があります
• スモールマルチプル：アニメーションではなく、デザインを繰り返して比較を示します
• スパークライン：文章の中に配置する、単語サイズのグラフィックです
• レイヤリング：まず概要を示し、必要に応じて詳細を提示します
• 統合：テキストとグラフィックを同じ視覚空間で共有します（脚注ではなくサイドノート）

レポートは、よく編集された雑誌記事のように感じられるべきです。上から下へ読み進め、ナラティブがデータを通して読者を導き、各チャートは具体的な問いに答えることで掲載する価値を示します。

オンボーディング — 作成前に質問する

コードを一切書く前に、次の質問をしてください。すべてに回答があるまで作業を進めないでください。

1. どのようなデータソースがありますか？（CSV、JSON、SQLite、API エンドポイント、または生の数値）
2. このレポートが答えるべき主な問いは何ですか？（1 文で回答してください。これがタイトルとなり、すべてのデザイン上の判断を導きます）
3. セクションはいくつ必要ですか？（上限は 8 です。それ以上を希望された場合は再検討を促してください。各セクションでは 1 つの副次的な問いに答える必要があります）
4. 出力形式は何ですか？（単体で動作する HTML ファイル、または埋め込みコンポーネント）
5. 作業時間の目安はどれくらいですか？ 次の見積もりを提示してください。
   • 表のみの 1～2 セクション：約 200 LOC、バイパスなら約 5 分／手動なら約 10 分
   • チャート 2～3 個を含む 3～4 セクション：約 500 LOC、バイパスなら約 15 分／手動なら約 25 分
   • チャート、健康データ、スパークラインを含む 5～8 セクション：約 1200 LOC、バイパスなら約 30 分／手動なら約 50 分

スコープの保護

このスキルでは、スコープの拡大を防ぐため、厳格な上限を設けています。

• セクションは最大 8 つ — それ以上を希望された場合は、関連するトピックをまとめることを提案します
• 1 セクションあたりのチャート種類は最大 2 つ — 各セクションには主役となるチャートを 1 つ配置し、必要に応じて補助チャートまたは表を 1 つ加えます。それ以上必要な場合は、セクションを分割してください
• 1 チャートあたりの色は最大 3 色 — それ以上必要な場合は、虹色の凡例ではなくスモールマルチプルを使用してください
• 3D チャート、円グラフ、ドーナツチャートは禁止 — これらは Tufte の原則に反します
• 不要なアニメーションは禁止 — スクロール時の表示は問題ありませんが、回転、バウンス、点滅は避けてください
• すべてのチャートにキャプションを付ける — チャートが何を示すのかを説明する 1 文のキャプションを書けない場合、そのチャートは不要です

これらの上限を超える依頼を受けた場合は、次のように答えてください。「それを追加すると、レポートの規模は [現在の LOC 見積もり] から [新しい見積もり] になります。複雑さが増すことで [X] が加わりますが、[Y] のリスクも高まります。進めますか？ それとも [よりシンプルな代替案] にできますか？」

アーキテクチャ

report.html (standalone, no build step)
├── Google Fonts CDN (EB Garamond)
├── jsDelivr CDN (Monaspace Argon woff2)
├── jsDelivr CDN (Chart.js 4.x UMD)
├── Inline <style> (design system CSS)
├── Inline HTML (semantic structure)
└── Inline <script> (data + Chart.js configs + sparklines + scroll-reveal)

ビルドツールもフレームワークも npm も不要です。1 つのファイルで、どのブラウザーでも開けます。

デザインシステム

CSS 変数、タイポグラフィのスケール、カラーパレットの全容については、references/design-tokens.md を読んでください。

再利用可能な各コンポーネントの HTML+CSS スニペットについては、references/components.md を読んでください。

Chart.js の設定パターンとインライン SVG スパークラインのコードについては、references/charts.md を読んでください。

レポート構成テンプレート

すべてのレポートで、次の構成を使用します。

1. Title + subtitle + data source tags (monospace, subtle)
2. [Optional] Status dashboard (4-column KPI strip)
3. Overview narrative with inline sparklines + TOC sidebar
4. Summary cards (2-4 KPI tiles with sparklines)
5. Sections (each: state-line → chart+narrative aside → table+narrative aside)
6. [Optional] Decision register (threshold table with status colors)
7. Footer (generation date, sources)

セクションのパターン

各セクションでは、次の流れに従います。

<h2> with ↑ back-to-top link
<p class="state-line"> — one italic sentence, the takeaway
<div class="aside-container"> — chart on left, narrative on right
<div class="aside-container"> — table on left, interpretation on right

チャート→ナラティブ→表→ナラティブと交互に配置することで、視覚的な余白を生み出し、「データの壁」による疲労を防ぎます。

ナラティブテキストのルール

• ステートメント（各見出しの下にある斜体の導入文）：1 文、最大 20 語で、トピックではなく結論を述べます。「HRV が 13％低下、歩数が 42％減少」とし、「このセクションでは健康指標を扱います」とはしません
• 補足ナラティブ：短い段落を 3～4 つ用意し、それぞれを太字のキーワードで始めます。新聞のサイドバーのように、まず事実を述べ、次に解釈を加えます
• フライアウト：実行可能なインサイトや手法に関する注記に使用します。✦ 記号は「注目してください」という意味を示します
• 「それ自体で物語を語る」などの空疎な表現は禁止。すべての文に、数値または判断を含めます

デュアルフォント戦略

コンテキスト	フォント	理由
すべての本文、見出し、キャプション	EB Garamond	古典的な編集デザインの雰囲気があり、非常に読みやすい
表内のすべての数値	Monaspace Argon	表形式の数字が列内で揃い、等幅フォントで一覧性が高まる
カード／ダッシュボード内の大きな数値	Monaspace Argon	視覚的な重みがあり、本文と区別できる
ステータス表示、トレンドのパーセンテージ	Monaspace Argon	精密な情報伝達に適している
データソースのタグ、コード参照	Monaspace Argon	技術的な印象を与える
装飾区切り（:::）	合字対応の Monaspace Argon	プログラミング風の美しさがあり、花柄の Unicode 文字に代わる

色の原則

テキストには --ink（ほぼ黒）、背景には --bg（温かみのある白）を使用します。グラフの色には意味を持たせ、ランダムに割り当てないでください。

• オレンジ（--spark-claude、#c45a28）：主要なデータストリーム、作業量／作業指標
• 緑（--spark-wispr、#2a7a5a）：成長、良好な健全性を示すシグナル、英語
• 紫（--spark-social、#5a5aaa）：ソーシャル／コミュニケーション指標
• 青（rgba(42,80,140)）：グラフ上の補助的なオーバーレイ線
• 赤（#a02a2a）：アラート、悪化傾向、低下する指標
• アンバー（#c89000）：警告、注意レベルのシグナル
• 緑（#2a7a3a）：健全なベースライン、良好な傾向

1つのグラフで使用する色は3色までにしてください。それ以上必要な場合は、同じ色相の不透明度や彩度を変えて使用してください。

セッションからの教訓（うまくいかないこと）

リファレンスレポートの作成を通じて明らかになった、繰り返し起きる問題は次のとおりです。

1. Chart.js CDN のバージョン：特定のパッチバージョンではなく @4 を使用してください。特定のバージョンは存在しない場合があります
2. Chart.js のデフォルト設定：プロパティを個別に設定し、オブジェクト全体を置き換えないでください（Chart.defaults.scale.grid = {color: '#eee'} ではなく Chart.defaults.scale.grid.color = '#eee'）
3. 凡例の円：真円にするには、usePointStyle: false と boxWidth: 8, boxHeight: 8, borderRadius: 4 を使用します。usePointStyle: true では楕円になります
4. file:// プロトコル：file:// 経由ではグラフの CDN スクリプトを読み込めません。必ず localhost 経由でテストしてください
5. グラフの連続配置：連続するグラフの間には、必ず説明文、表、または装飾区切りを入れてください。グラフが2つ続くと「データの壁」になります
6. モバイルでの表のはみ出し：.table-wrapper で囲み、補助的な列に .hide-mobile を追加してください
7. 2軸グラフ：誤った視覚的な同等性を招くため、使用は控えめにしてください。両方の軸に必ず明確なラベルを付けてください
8. 説明の行き過ぎ：相関を計算せずに相関関係を主張しないでください。「強い関係」より「r = 0.10」のほうが信頼できます

汎用データアダプター

ユーザーが任意のソース（CSV、JSON、SQLite、API、生の数値）からデータを提供した場合、HTML を生成する前に、標準の中間形式 ReportData に正規化してください。これにより、データの取り込みとレポートの描画を分離できます。

ReportData の JSON スキーマ、フィールドのリファレンス、ソースの種類ごとのアダプター手順については、references/data-adapter.md を参照してください。

ワークフロー：

1. ユーザーがデータを提供 → ソースの種類を特定する
2. ReportData JSON に変換する（meta.question と希望するセクションについてユーザーに確認する）
3. 正規化した構造をユーザーに確認する
4. ブロックライブラリを使用して ReportData から HTML を生成する

合成可能なブロックライブラリ

レポートは、データの契約が定義された型付きブロックを組み合わせて作成します。これにより、場当たり的な HTML 生成を体系的なアプローチに置き換えます。

ブロックの完全なカタログ（sparkline-row、kpi-card、trend-chart、data-table、correlation-matrix、narrative、heatmap、strip-chart）については、references/blocks.md を参照してください。

各ブロックには次の要素が定義されています。

• データの契約（想定する JSON の形式）
• HTML テンプレート（コピーしてすぐに使用可能）
• 組み合わせのルール（ブロックの組み合わせ方と順序）

プレビューサーバー

反復的な開発には、組み込みのライブリロードサーバーを使用します。

python3 ~/.claude/skills/tufte-report/scripts/serve.py report.html

localhost:8042 で配信し、ファイルが変更されるとスクロール位置を保持したまま自動で再読み込みします。依存関係は不要で、Python の標準ライブラリのみを使用します。

詳細は references/preview-server.md を参照してください。レポートを生成した後、ユーザーにプレビューサーバーを起動するか確認してください。