tufte-report

What this skill does

# Tufte Report — Data-Driven Infographic Skill

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.

## 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.

## Onboarding — Ask Before Building

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

1. **What data sources do you have?** (CSV, JSON, SQLite, API endpoint, or raw numbers)
2. **What is the primary question this report should answer?** (one sentence — this becomes the title and drives all design decisions)
3. **How many sections do you need?** (cap at 8 — push back if more are requested; each section should answer one sub-question)
4. **What's the output format?** (standalone HTML file, or embedded component)
5. **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

## 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]?"

## 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.

## 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.

## 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)
```

### 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.

### 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

## 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 |

## 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.

## Session Lessons (What Goes Wrong)

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

1. **Chart.js CDN version**: Use `@4` not a specific patch version — specific versions may not exist
2. **Chart.js defaults**: Set individual properties, never replace entire objects (`Chart.defaults.scale.grid.color = '#eee'` not `Chart.defaults.scale.grid = {color: '#eee'}`)
3. **Legend circles**: Use `usePointStyle: false` with `boxWidth: 8, boxHeight: 8, borderRadius: 4` for true circles. `usePointStyle: true` creates ovals
4. **file:// protocol**: Charts won't load CDN scripts via file://. Always test via localhost
5. **Back-to-back charts**: Always separate consecutive charts with narrative, a table, or an ornament. Two charts in a row = "wall of data"
6. **Table overflow on mobile**: Wrap in `.table-wrapper` and add `.hide-mobile` to secondary columns
7. **Dual-axis charts**: Use sparingly — they invite false visual equivalence. Always label both axes clearly
8. **Narrative overreach**: Don't claim correlations without computing them. "r = 0.10" is more trustworthy than "strong relationship"

## 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:**
1. User provides data → identify source type
2. Transform into ReportData JSON (ask user for `meta.question` and desired sections)
3. Confirm the normalized structure with