# Render Tufte Chart

> Render Tufte Chart is an Agent Skill for design published in the gnurio/tufte-vdqi-plugin repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Produce a real, publication-ready data graphic (SVG or HTML) that obeys Tufte's principles — minimal ink, range-frame axes, direct labels, honest proportions. Use whenever someone wants to design, build, create, draw, or actually produce a chart the Tufte way, or to rebuild a chart after assessment found problems. This is the only skill in the toolkit that outputs an actual chart file.

- Skill name: `render-tufte-chart`
- Category: [Design](https://www.openparable.com/skill/design/1)
- Source: https://github.com/gnurio/tufte-vdqi-plugin/blob/HEAD/skills/render-tufte-chart/SKILL.md
- Repository: gnurio/tufte-vdqi-plugin (267 GitHub stars when collected)

## SKILL.md

# Render Tufte Chart

This skill produces an actual chart file. It is the toolkit's output stage: the
router sends "design / build / produce a chart" requests here, and an
optimisation workflow ends here (assess to diagnose, render to rebuild).

The old version of this skill shipped Python that called undefined functions and
could not run. It is replaced by a working script plus clear construction guidance.

## 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 `assess-graphical-excellence/scripts/deflate.py` with
  retrieved CPI) and label the axis "real <base-year> <currency>".
- **Inert SVG (B8).** No `<script>`, no event-handler attributes (`onload=`
  etc.), no `javascript:` URLs, no `<foreignObject>`, no SMIL `<animate>`/
  `<set>`. The four scripts above never emit these; if you hand-build SVG for
  one of the "other genres" below, keep it inert too — `wrap_html.py` will
  refuse 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 assess 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)

```
python 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:

```
python 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:

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

```
python 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:

```
python 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.

**If wrap_html refuses your SVG.** The wrapper accepts SVGs produced by the
four scripts above (they carry a trusted marker). If it exits with
`ERROR[untrusted-svg]`, the SVG wasn't produced by one of those — re-render
the chart with the matching script and try again. If you genuinely need to
wrap a hand-built or third-party SVG, pass `--untrusted`; the wrapper will
then run a best-effort active-content check and exit with `ERROR[active-svg]`
if it finds anything script-bearing. Either way, the fix is to produce inert
SVG (see B8 above).

Always save the file and tell the user its path. Where useful, follow up with
`assess-graphical-excellence` 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 an `assess-graphical-excellence` review.

## Related skills
- `assess-graphical-excellence` — diagnose a chart and get the remedies to apply here.
- `orchestrate-tufte-vdqi` — routes design/produce/fix requests to this skill.

---

Source: https://www.openparable.com/skill/design/render-tufte-chart (OpenParable). Cite the canonical URL above.
