tufte-chart

name

tufte-chart

description

Render a real, publication-ready data graphic (SVG or HTML) that obeys Tufte's principles — minimal ink, range-frame axes, direct labels, honest proportions. Use when someone wants to design, build, create, draw, plot, or visualize a chart or graph the Tufte way, or to rebuild a chart after a critique found problems. This is the skill that outputs an actual chart file. Not for critiquing an existing graphic (`tufte-critique`).

Tufte Chart

Render an actual chart file. "Design / build / produce a chart" requests land here; to fix a cluttered or misleading chart, run tufte-critique first and rebuild here honoring its remedy tags (B1–B7).

Build checklist (apply every time)

These bake in the principles from references/tufte-principles.md so the chart never needs cleanup afterwards. Read that file for the full reasoning.

• Honest proportions (B1). Bars/columns start at a zero baseline. Encode a 1-D quantity with length or position, never with 2-D area or 3-D volume.
• Range-frame axes (B2). Axis lines span exactly the data range, ends labelled; no outward padding. Exception: keep zero baseline for bar value axes.
• Direct labels (B4). Label lines at their endpoints and bars beside the bars; do not emit a separate legend.
• Minimal ink (B5). White background, no gridlines (or faint hairlines at major ticks only), no border box, no 3-D, no shadows, no gradients.
• One encoding per datum (B6). Don't restate a value with fill + border + label; keep the strongest channel.
• Many series → small multiples (B3). Repeat one shrunken design with shared scales rather than overplotting; order frames meaningfully.
• Money over time (B7). If the series is currency across years, convert to real terms first (use scripts/deflate.py with retrieved CPI) and label the axis "real ".
• Wider than tall. Unless the data dictates otherwise, "move toward horizontal graphics about 50 percent wider than tall" (VDQI p.190). The bundled scripts default to this; hold hand-built SVGs to it too.
• Friendly type and color (Part H). Serif upper-and-lower-case type, words left-to-right, colors legible to color-deficient viewers — never red vs green for an essential contrast.
• Inert SVG. No <script>, no event-handler attributes (onload= etc.), no javascript: URLs, no <foreignObject>, no SMIL <animate>/<set>. The four scripts below never emit these; if you hand-build SVG for one of the "other genres", keep it inert too — wrap_html.py refuses to wrap anything carrying active content.

Pick the genre first

Before writing any code, check references/tufte-principles.md Part C and choose Tufte's genre that fits the data shape. The toolkit ships a working script for the four genres below; for the rest, build the SVG by hand following Part C's recipe.

Data shape	Tufte genre (Part C)	Script
1 × N over time	C10 time-series	render_line_svg.py
K series indexed by a category	C5 small multiples	small_multiples.py
Distributions of K groups	C1 quartile plot	quartile_plot.py
Bivariate / scatter	C2 range frame (+ optional C3 dot-dash marginals)	range_frame.py
Categorical 1-value	C9 white-grid bar / C6 supertable	hand-build SVG
≤20 numbers total	C6 supertable	hand-build HTML/SVG
Many variables, geographic	F (Minard / Snow / Cancer Atlas)	hand-build SVG

If the data is ≤20 numbers, prefer a table (VDQI p.56) — say so to the user before rendering. If forced to graph, use C6 supertable, not pie/bar.

Multi-render rule (when to produce N alternatives)

When the critique step flagged a "Multi-render trigger" (data shape with more than one correct Tufte answer), render both alternatives side-by-side in one output, then let the user pick. This is the discipline that prevents quiet defaulting to the obvious genre.

Data shape	Render BOTH
1 number / single ratio	(a) a one-sentence prose statement with the number inline, and (b) a tiny inline visual — a one-row proportion bar or a small two-color dot square
≤20 numbers	(a) a C6 supertable (with optional table-graphic sparkline column), and (b) a single Tufte chart (C8 + C2 range-frame dot plot, or C9 white-grid bar)
Many series of one x	(a) a C5 small-multiples grid, and (b) an overplotted line/dot chart with direct end-labels
Distributions across groups	(a) a C1 quartile plot, and (b) a strip plot or histogram
Bivariate scatter	(a) a C2 range frame, and (b) the C3 dot-dash variant adding marginals

For all other data shapes, render one canonical Tufte form (don't manufacture alternatives when one obviously dominates). When emitting both alternatives, state in one sentence why each exists and what to look at in each — the goal is letting the reader see the toolkit's range, not flooding them with near-duplicates.

How to render

Line / time-series (C10)

python3 scripts/render_line_svg.py \
  --data '[{"x":2000,"y":12.1},{"x":2023,"y":22.9}]' \
  --title "Revenue (real 2023 USD, M)" --series "Revenue" --out chart.svg

(Pass --data-file path.json for larger data. For monetary series, deflate the values before passing them in.)

Small multiples (C5) — "inevitably comparative, deftly multivariate"

Input is a flat list of records keyed by facet, x, and y:

python3 scripts/small_multiples.py \
  --data '[{"facet":"NA","x":1,"y":1000},{"facet":"EU","x":1,"y":900}, ...]' \
  --facet-key facet --x-key x --y-key y \
  --title "Daily active users by region" --cols 3 --out chart.svg

Frames are sorted by total y (descending) unless --order "A,B,C" is passed. All frames share scales; axis end-labels appear only on the first frame to avoid repeating ink.

Quartile plot (C1) — Tufte's stripped-down box plot

Input is a JSON object mapping group name to list of values:

python3 scripts/quartile_plot.py \
  --data '{"Control":[2.3,2.5,...],"TreatmentA":[1.8,2.0,...]}' \
  --title "Reaction time (s) by condition" --out chart.svg

The box is erased; what remains is a single vertical stroke per group spanning the full range, the IQR offset horizontally from it, and a median tick.

Range-frame scatter (C2) — and optional dot-dash plot (C3)

python3 scripts/range_frame.py \
  --data '[{"x":1.2,"y":3.4},{"x":2.1,"y":4.5},...]' \
  --title "Body mass vs. wing span" \
  [--marginal-dash] --out chart.svg

--marginal-dash adds Tufte's dot-dash plot (VDQI p.133): marginal frequency dashes along each axis framing the bivariate distribution.

Other genres (bar, supertable, multivariate map, etc.)

Write the SVG/HTML directly, following Part C's recipe and the build checklist above. Keep it a single self-contained file. A minimal pattern: white canvas, thin dark data marks, range-frame axis lines with end labels, category/series text placed on the marks, no grid/box.

Optional: Tufte-styled HTML page

For a page that surrounds the chart with ET Book typography (and optional lede text or caption), wrap the SVG with scripts/wrap_html.py. It uses the bundled tufte-css (assets/tufte-css/, MIT-licensed) and copies the stylesheet and fonts into a sibling tufte-assets/ directory the first time so the result opens correctly in any browser with no network:

python3 scripts/wrap_html.py \
  --svg chart.svg --out chart.html \
  --title "Revenue, 2000–2023" \
  --caption "Inflation-adjusted to 2023 USD using BLS CPI-U."

Use the SVG output when you need a portable single file (charts in a paper, a slide deck, another site). Use the HTML wrapper when you want a self-contained, browser-ready Tufte page (sharing a link, hosting a report). Pass --no-assets if the page will be served from a site that already publishes tufte.css at the expected path.

wrap_html inspects every SVG before inlining. If it exits with ERROR[active-svg], the SVG carries script-bearing content (scripts, event handlers, animation, external references) — produce inert SVG instead (see the build checklist); the four bundled scripts always do.

Always save the file and tell the user its path. Where useful, follow up with tufte-critique to confirm the result scores well.

What good looks like

A file that renders in a browser, carries no chartjunk, labels data directly, uses honest proportions, and would itself pass a tufte-critique review.

Related skills

• tufte-critique — diagnose a chart and get the remedies to apply here.