tufte-report

Tufte 报告 — 数据驱动的信息图技能

创建独立的 HTML 报告，将编辑式叙事与交互式数据可视化相结合，采用 Edward Tufte 的风格：信息密度高、图表装饰极少、以排版为先。

设计理念

Tufte 的核心原则指导每一个决策：

• 数据墨水比：每个墨水像素都应表示数据，而非装饰
• 小多图：重复使用同一种设计来展示对比，而非动画
• 迷你图：融入文字中的词语大小的图形
• 分层：先展示概览，再按需呈现细节
• 融合：文字和图形共享同一视觉空间（旁注，而非脚注）

报告应如同一篇精心编辑的杂志专题——读者从上到下阅读，叙事引导读者了解数据，每张图表都通过回答一个具体问题来证明其版面价值。

入门 — 构建前先提问

编写任何代码之前，先询问以下问题。所有问题都得到回答后再继续：

1. 你有哪些数据源？（CSV、JSON、SQLite、API 端点或原始数字）
2. 这份报告要回答的首要问题是什么？（用一句话说明——这将成为标题，并指导所有设计决策）
3. 需要多少个章节？（最多 8 个——如果用户要求更多，请提出异议；每个章节应回答一个子问题）
4. 输出格式是什么？（独立 HTML 文件或嵌入式组件）
5. **时间预算是多少？**提供预估：
   • 只有表格的 1-2 个章节：约 200 LOC，绕过流程约 5 分钟 / 手动约 10 分钟
   • 包含 2-3 张图表的 3-4 个章节：约 500 LOC，绕过流程约 15 分钟 / 手动约 25 分钟
   • 包含图表、健康数据和迷你图的 5-8 个章节：约 1200 LOC，绕过流程约 30 分钟 / 手动约 50 分钟

范围保护

此技能设定了硬性限制，以防止范围蔓延：

• 最多 8 个章节——如果用户要求更多，建议合并相关主题
• 每个章节最多 2 种图表类型——每个章节包含一张主要图表，可选一张辅助图表或表格。超过这个数量，就应该拆分章节
• 每张图表最多 3 种颜色——超出时使用小多图，而非彩虹图例
• 禁止 3D 图表、饼图和环形图——这些都违背 Tufte 原则
• 禁止无意义的动画——进入视口时的滚动显示可以接受；旋转、弹跳或脉动效果不可以
• 每张图表都必须配有说明文字——如果无法用一句话说明图表展示的内容，就不应该制作这张图表

当用户提出超出这些限制的要求时，请回复：“这会使报告从[当前 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。只需一个文件，即可在任何浏览器中打开。

设计系统

阅读 references/design-tokens.md，了解完整的 CSS 变量、排版比例和调色板。

阅读 references/components.md，查看每个可复用组件的 HTML+CSS 代码片段。

阅读 references/charts.md，了解 Chart.js 配置模式和内联 SVG 迷你图代码。

报告结构模板

每份报告都遵循以下骨架：

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

图表→叙事→表格→叙事的交替安排，能营造视觉上的呼吸感，避免读者因“数据墙”而疲劳。

叙述文本规则

• 结论句（各标题下方的斜体引言）：一句话，最多 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）：健康基线、正向趋势

单个图表中使用的颜色不得超过 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. 连续排列的图表：相邻图表之间务必插入叙述文字、表格或装饰分隔符。连续两个图表会形成“数据墙”
6. 移动端表格溢出：使用 .table-wrapper 包裹，并为次要列添加 .hide-mobile
7. 双轴图表：谨慎使用——它们容易造成错误的视觉等同。务必清晰标注两个坐标轴
8. 过度解读叙述：未经计算，不要声称存在相关性。“r = 0.10”比“强相关”更可信

通用数据适配器

当用户提供来自任何来源的数据（CSV、JSON、SQLite、API、原始数字）时，在生成 HTML 之前，先将其规范化为标准的 ReportData 中间格式。这样可以将数据导入与报告渲染解耦。

阅读 references/data-adapter.md，了解 ReportData JSON 架构、字段参考，以及各类数据源的适配说明。

工作流：

1. 用户提供数据 → 确定来源类型
2. 转换为 ReportData JSON（向用户询问 meta.question 和所需章节）
3. 与用户确认规范化后的结构
4. 使用区块库，根据 ReportData 生成 HTML

可组合区块库

报告由具有类型的区块组成，每个区块都有定义好的数据契约。这种方式以系统化流程取代临时生成 HTML。

阅读 references/blocks.md，了解完整的区块目录：sparkline-row、kpi-card、trend-chart、data-table、correlation-matrix、narrative、heatmap、strip-chart。

每个区块定义：

• 数据契约（所需的 JSON 结构）
• HTML 模板（可直接复制粘贴）
• 组合规则（区块如何配对和排序）

预览服务

在迭代开发过程中，使用内置的实时重载服务：

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

在 localhost:8042 上提供服务，文件更改时自动重新加载，并保留滚动位置。零依赖——仅使用 Python 标准库。

详情请阅读 references/preview-server.md。生成报告后，主动询问用户是否要启动预览服务。