tufte-report

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tufte Report — Data-Driven Infographic Skill

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

Create standalone HTML reports that combine editorial narrative with interactive data visualization in Edward Tufte's style: high information density, minimal chart junk, typography-first design.

创建符合Edward Tufte风格的独立HTML报告，将编辑叙事与交互式数据可视化相结合：高信息密度、极简冗余图表、排版优先设计。

Design Philosophy

设计理念

Tufte's core principles drive every decision:

Data-ink ratio: every pixel of ink should represent data, not decoration
Small multiples: repeat a design to show comparison, not animation
Sparklines: word-sized graphics that live inside prose
Layering: overview first, then detail on demand
Integration: text and graphics share the same visual space (sidenotes, not footnotes)

The report should feel like a well-edited magazine feature — you read it top to bottom, narrative carries you through the data, and every chart earns its space by answering a specific question.

Tufte的核心原则主导每一项决策：

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

报告应给人一种精心编辑的杂志专题感——从上到下阅读，叙事引导你了解数据，每个图表都通过回答特定问题来证明其存在的价值。

Onboarding — Ask Before Building

入门须知 — 构建前需询问的问题

Before writing ANY code, ask these questions. Do not proceed until all are answered:

What data sources do you have? (CSV, JSON, SQLite, API endpoint, or raw numbers)
What is the primary question this report should answer? (one sentence — this becomes the title and drives all design decisions)
How many sections do you need? (cap at 8 — push back if more are requested; each section should answer one sub-question)
What's the output format? (standalone HTML file, or embedded component)
Time budget? Provide an estimate:
- 1-2 sections with tables only: ~200 LOC, ~5 min bypass / ~10 min manual
- 3-4 sections with 2-3 charts: ~500 LOC, ~15 min bypass / ~25 min manual
- 5-8 sections with charts + health data + sparklines: ~1200 LOC, ~30 min bypass / ~50 min manual

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

你有哪些数据源？（CSV、JSON、SQLite、API端点或原始数字）
这份报告需要回答的核心问题是什么？（一句话概括——这将成为报告标题并主导所有设计决策）
你需要多少个章节？（最多8个——如果用户要求更多，建议合并相关主题；每个章节应回答一个子问题）
输出格式是什么？（独立HTML文件或嵌入组件）
时间预算？ 提供估算：
- 仅含表格的1-2个章节：约200行代码，自动生成约5分钟/手动制作约10分钟
- 含2-3个图表的3-4个章节：约500行代码，自动生成约15分钟/手动制作约25分钟
- 含图表+健康数据+迷你图的5-8个章节：约1200行代码，自动生成约30分钟/手动制作约50分钟

Scope Protection

范围管控

This skill enforces hard limits to prevent scope creep:

Max 8 sections — if the user asks for more, suggest combining related topics
Max 2 chart types per section — a section gets one primary chart and optionally one supporting chart or table. More than that means the section should split
Max 3 colors per chart — beyond that, use small multiples instead of rainbow legends
No 3D charts, no pie charts, no donut charts — these violate Tufte principles
No gratuitous animation — scroll-reveal on enter is fine; spinning, bouncing, or pulsing is not
Every chart must have a caption — if you can't write a one-sentence caption explaining what the chart shows, the chart shouldn't exist

When the user asks for something outside these limits, respond with: "That would take the report from [current LOC estimate] to [new estimate]. The extra complexity adds [X] but risks [Y]. Shall I proceed, or can we [simpler alternative]?"

此技能设置严格限制以防止范围蔓延：

最多8个章节——如果用户要求更多，建议合并相关主题
每个章节最多2种图表类型——一个章节包含一个主图表，可选一个辅助图表或表格。超过此数量意味着章节应拆分
每个图表最多3种颜色——若需要更多颜色，使用小倍数图表而非彩虹图例
禁止3D图表、饼图、环形图——这些违反Tufte原则
禁止无意义的动画——进入页面时的滚动Reveal效果是允许的；旋转、弹跳或脉动效果则不允许
每个图表必须配有说明文字——如果你无法用一句话说明图表展示的内容，那么这个图表就不该存在

当用户要求超出上述限制的内容时，回复：“这会将报告从[当前代码行数估算]增加到[新估算]。额外的复杂度会带来[X]，但可能导致[Y]风险。我是否继续，或者我们可以采用[更简单的替代方案]？”

Architecture

架构

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)

No build tools, no frameworks, no npm. One file, opens in any browser.

report.html (独立文件，无需构建步骤)
├── Google Fonts CDN (EB Garamond)
├── jsDelivr CDN (Monaspace Argon woff2)
├── jsDelivr CDN (Chart.js 4.x UMD)
├── 内联<style>（设计系统CSS）
├── 内联HTML（语义化结构）
└── 内联<script>（数据 + Chart.js配置 + 迷你图 + 滚动Reveal）

无需构建工具、框架或npm。单个文件，可在任何浏览器中打开。

Design System

设计系统

Read

references/design-tokens.md

for the complete CSS variables, typography scale, and color palette.

Read

references/components.md

for the HTML+CSS snippet of every reusable component.

Read

references/charts.md

for Chart.js configuration patterns and inline SVG sparkline code.

阅读

references/design-tokens.md

获取完整的CSS变量、排版比例和调色板。

阅读

references/components.md

获取每个可复用组件的HTML+CSS代码片段。

阅读

references/charts.md

获取Chart.js配置模式和内联SVG迷你图代码。

Report Structure Template

报告结构模板

Every report follows this skeleton:

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)

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

1. 标题 + 副标题 + 数据源标签（等宽字体，样式低调）
2. [可选] 状态仪表盘（4列KPI条）
3. 包含内联迷你图的概述叙事 + 侧边栏目录（TOC）
4. 汇总卡片（2-4个带迷你图的KPI卡片）
5. 章节（每个章节：状态线 → 图表+叙事旁注 → 表格+叙事旁注）
6. [可选] 决策记录（带状态颜色的阈值表格）
7. 页脚（生成日期、数据源）

Section Pattern

章节模式

Each section follows this rhythm:

<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

The alternation of chart→narrative→table→narrative creates visual breathing room and prevents "wall of data" fatigue.

每个章节遵循以下节奏：

带↑返回顶部链接的<h2>
<p class="state-line"> — 一句斜体句子，即核心结论
<div class="aside-container"> — 左侧图表，右侧叙事
<div class="aside-container"> — 左侧表格，右侧解读

图表→叙事→表格→叙事的交替布局创造了视觉呼吸空间，避免“数据墙”带来的疲劳感。

Rules for Narrative Text

叙事文本规则

State-lines (the italic intro under each heading): one sentence, max 20 words, states the conclusion not the topic. "HRV down 13%, steps down 42%" not "This section covers health metrics"
Aside narratives: 3-4 short paragraphs, each starting with a bold keyword. Written like a newspaper sidebar — facts first, interpretation second
Flyouts: reserved for actionable insights or methodology notes. The ✦ symbol marks them as "pay attention"
No "tells its own story" or similar filler. Every sentence should contain a number or a decision

状态线（每个标题下的斜体引言）：一句话，最多20个单词，陈述结论而非主题。例如“HRV下降13%，步数减少42%”而非“本节涵盖健康指标”
旁注叙事：3-4个短段落，每个段落以加粗关键词开头。像报纸侧边栏一样撰写——先讲事实，再做解读
弹出框：用于可执行见解或方法说明。用✦符号标记，提示“请注意”
禁止使用“数据自明”之类的填充语。每句话都应包含数字或决策信息

Dual-Font Strategy

双字体策略

Context	Font	Why
All body text, headers, captions	EB Garamond	Classical editorial feel, excellent readability
All numbers in tables	Monaspace Argon	Tabular figures align in columns, monospace scannability
Big numbers in cards/dashboards	Monaspace Argon	Visual weight, distinct from prose
Status indicators, trend percentages	Monaspace Argon	Precision signaling
Data source tags, code references	Monaspace Argon	Technical register
Ornament separators (:::)	Monaspace Argon with ligatures	Programming aesthetic, replaces floral Unicode

场景	字体	原因
所有正文、标题、说明文字	EB Garamond	经典编辑风格，极佳可读性
表格中的所有数字	Monaspace Argon	等宽数字在列中对齐，便于扫描
卡片/仪表盘中的大数字	Monaspace Argon	视觉重量感，与散文文本区分开
状态指示器、趋势百分比	Monaspace Argon	精准传递信号
数据源标签、代码引用	Monaspace Argon	技术风格定位
装饰分隔符（:::）	启用连字的Monaspace Argon	编程美学，替代花卉Unicode符号

Color Principles

色彩原则

Use

--ink

(near-black) for text,

--bg

(warm white) for background. Chart colors must be semantically meaningful — don't assign colors randomly:

Orange (
```
--spark-claude
```
, #c45a28): primary data stream, effort/work metrics
Green (
```
--spark-wispr
```
, #2a7a5a): growth, positive health signals, English language
Purple (
```
--spark-social
```
, #5a5aaa): social/communication metrics
Blue (rgba(42,80,140)): secondary overlay lines on charts
Red (#a02a2a): alerts, negative trends, declining metrics
Amber (#c89000): warnings, watch-level signals
Green (#2a7a3a): healthy baselines, positive trends

Never use more than 3 colors in a single chart. If you need more, use opacity/saturation variations of the same hue.

文本使用

--ink

（近黑色），背景使用

--bg

（暖白色）。图表颜色必须具有语义意义——不要随机分配颜色：

橙色 (
```
--spark-claude
```
, #c45a28)：主数据流、工作量/工作指标
绿色 (
```
--spark-wispr
```
, #2a7a5a)：增长、健康积极信号、英文内容
紫色 (
```
--spark-social
```
, #5a5aaa)：社交/沟通指标
蓝色 (rgba(42,80,140))：图表上的次要叠加线
红色 (#a02a2a)：警报、负面趋势、下降指标
琥珀色 (#c89000)：警告、需关注的信号
绿色 (#2a7a3a)：健康基线、积极趋势

单个图表中使用的颜色不得超过3种。如果需要更多颜色，使用同一色调的透明度/饱和度变体。

Session Lessons (What Goes Wrong)

经验教训（常见问题）

Based on building the reference report, these are the recurring problems:

Chart.js CDN version: Use
```
@4
```
not a specific patch version — specific versions may not exist

Chart.js defaults: Set individual properties, never replace entire objects (

Chart.defaults.scale.grid.color = '#eee'

not

Chart.defaults.scale.grid = {color: '#eee'}

)

Legend circles: Use

usePointStyle: false

with

boxWidth: 8, boxHeight: 8, borderRadius: 4

for true circles.

usePointStyle: true

creates ovals

file:// protocol: Charts won't load CDN scripts via file://. Always test via localhost
Back-to-back charts: Always separate consecutive charts with narrative, a table, or an ornament. Two charts in a row = "wall of data"
Table overflow on mobile: Wrap in
```
.table-wrapper
```
and add
```
.hide-mobile
```
to secondary columns
Dual-axis charts: Use sparingly — they invite false visual equivalence. Always label both axes clearly
Narrative overreach: Don't claim correlations without computing them. "r = 0.10" is more trustworthy than "strong relationship"

基于参考报告的构建经验，以下是常见问题：

Chart.js CDN版本：使用
```
@4
```
而非特定补丁版本——特定版本可能不存在
Chart.js默认设置：设置单个属性，切勿替换整个对象（例如使用
```
Chart.defaults.scale.grid.color = '#eee'
```
而非
```
Chart.defaults.scale.grid = {color: '#eee'}
```
）

图例圆形：使用

usePointStyle: false

搭配

boxWidth: 8, boxHeight: 8, borderRadius: 4

以实现真正的圆形。

usePointStyle: true

会创建椭圆形

file://协议：通过file://协议无法加载CDN脚本。始终通过localhost测试
连续图表：始终用叙事文本、表格或装饰分隔符分隔连续的图表。两个图表连续排列会形成“数据墙”
移动端表格溢出：将表格包裹在
```
.table-wrapper
```
中，并为次要列添加
```
.hide-mobile
```
类
双轴图表：谨慎使用——它们容易引发错误的视觉等效性。始终清晰标记两个轴
叙事过度解读：未经计算不要声称存在相关性。“r = 0.10”比“强关联”更可信

Universal Data Adapter

通用数据适配器

When the user provides data from any source (CSV, JSON, SQLite, API, raw numbers), normalize it into the standard ReportData intermediate format before generating HTML. This decouples data ingestion from report rendering.

Read

references/data-adapter.md

for the ReportData JSON schema, field reference, and adapter instructions for each source type.

Workflow:

User provides data → identify source type
Transform into ReportData JSON (ask user for
```
meta.question
```
and desired sections)
Confirm the normalized structure with the user
Generate HTML from the ReportData using the block library

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

阅读

references/data-adapter.md

获取ReportData JSON schema、字段参考以及各数据源类型的适配说明。

工作流程：

用户提供数据 → 识别数据源类型
转换为ReportData JSON（询问用户
```
meta.question
```
和所需章节）
与用户确认标准化后的结构
使用块库从ReportData生成HTML

Composable Block Library

可组合块库

Reports are assembled from typed blocks, each with a defined data contract. This replaces ad-hoc HTML generation with a systematic approach.

Read

references/blocks.md

for the complete block catalog: sparkline-row, kpi-card, trend-chart, data-table, correlation-matrix, narrative, heatmap, strip-chart.

Each block defines:

Data contract (what JSON shape it expects)
HTML template (copy-paste ready)
Composition rules (how blocks pair and sequence)

报告由类型化块组装而成，每个块都有定义好的数据约定。这将临时HTML生成替换为系统化方法。

阅读

references/blocks.md

获取完整的块目录：sparkline-row、kpi-card、trend-chart、data-table、correlation-matrix、narrative、heatmap、strip-chart。

每个块定义：

数据约定（预期的JSON结构）
HTML模板（可直接复制粘贴）
组合规则（块如何配对和排序）

Preview Server

预览服务器

For iterative development, use the built-in live-reload server:

bash

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

Serves on

localhost:8042

, auto-reloads on file change with scroll position preserved. Zero dependencies — Python stdlib only.

Read

references/preview-server.md

for details. After generating a report, offer to start the preview server for the user.

用于迭代开发，使用内置的实时重载服务器：

bash

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

在

localhost:8042

提供服务，文件变更时自动重载并保留滚动位置。零依赖——仅使用Python标准库。

阅读

references/preview-server.md

获取详细信息。生成报告后，主动向用户提供启动预览服务器的选项。