tufte-skill

Your agent's charts, maps and diagrams, drawn by Edward Tufte's rules. Every rule names its source in his books, and says so plainly when a rule is not his.

npx skills add mayar-ariss/tufte-skill

Works with Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI and any agent the skills CLI supports. Covers matplotlib, seaborn, Plotly, ggplot2, plotnine, Vega-Lite, Altair, Observable Plot, Recharts, ECharts, Chart.js and D3/SVG, plus maps and flowcharts, with accessibility, dark mode and responsive layout built in.

Live demo: toggle default and Tufte styling in ECharts, Chart.js, Plotly and D3, light and dark · Examples · What it does

Try it

Once installed, ask your agent for a chart the way you normally would. The skill applies itself:

• "Plot monthly revenue against target from sales.csv with matplotlib."
• "Build a Recharts bar chart of signups by channel, sorted."
• "Review this ECharts config and remove the chartjunk."
• "Make a dark-mode version of this Plotly dashboard."
• "Draw a flowchart of our order process in Mermaid."

Fair warning

This skill is opinionated by design. It will remove your gridlines, replace your legends with direct labels, reject your pie charts, and default to serif type. It enforces a specific visual philosophy — Tufte's — not a neutral one. If you want total creative freedom over your chart styling, this is not the skill for you. If you want every chart to come out clean, honest, and readable without thinking about it, read on.

Examples

Gridlines fade, legends become direct labels, chartjunk dissolves:

Line chart — direct labels, range-frame axes, annotation	Bar chart — sorted by value, leader highlighted
Slopegraph — before/after comparison	Small multiples — shared scale, minimal chrome
Sparklines — with beginning and ending values, Tufte's red first/last and blue low/high marks	Data table — whitespace, thin rules, outlier highlighted
Dark mode — designed palette, not inverted	Accessible scatter — shape + color, readable without color

Light & dark — the same chart in both themes

Data map — John Snow's 1854 cholera data drawn by rules/maps.md: one dot per death, a quiet base map, the only strong color on the Broad Street pump, and the source and limits on the map

Accessible palette

Every text and data color meets the skill's own contrast rule: 4.5:1 for text, 3:1 for data marks. scripts/check_contrast.py checks the documented palette so it can't drift.

What it does

Every rule names its source: Tufte (cited by book and chapter), convention (common Tufte-style practice he did not state), or extension (added by this skill's authors). Tufte's principles are never mixed with the skill's own choices.

Graphical integrity — Tufte's six principles from The Visual Display of Quantitative Information, checked before anything else:

• Proportional representation (the lie factor), clear labeling, data variation rather than design variation
• Deflated units for money over time, no more dimensions than the data has, no data out of context

Data-ink — Tufte's five data-ink principles ("within reason"), his three forms of chartjunk (moiré vibration, dark grids, the duck), and what he asks for beyond erasing: data density, multifunctioning elements, micro/macro readings.

Analytical design — the six principles of Beautiful Evidence ch. 5, including documentation: every chart states its source and units.

Then 22 universal rules in three tiers, plus guidance on chart types and diagrams:

Show the rules

Static principles (rules 1–14) — mostly Tufte's data-ink principles, with a few conventions labeled as such:

• Maximize data-ink ratio — remove gridlines, borders, legends, and decoration that don't convey data
• Direct labeling, range-frame axes, no 3D, no pie charts (unless forced), no dual y-axes
• Serif type in upper-and-lower case with words spelled out (Tufte's friendly data graphic), gray as primary color with selective highlighting, off-white backgrounds (a convention)
• Annotate notable features, show comparison context, minimal tooltips

Screen-first principles (rules 15–19) — extensions for modern interactive contexts. Where one pulls against Tufte (progressive disclosure vs. his data density), the rule says so:

• Progressive disclosure (overview first, details on hover/tap/click)
• WCAG accessibility (contrast ratios, dual encoding, keyboard nav, screen reader text alternatives)
• Responsive design (fluid/adaptive strategies, touch targets, mobile-adapted chart types)
• Purposeful animation (data transitions only, respect prefers-reduced-motion)
• Intentional dark mode (semantic color tokens, never invert, reduce saturation)

Content & formatting (rules 20–22) — extensions, except rule 22, which is Tufte's:

• Titles assert findings ("Revenue Surged 23%"), not axis descriptions
• Numbers formatted for humans ($1.2M, thousand separators, matched precision)
• Don't chart what a sentence or table can say better (Tufte: a sentence is poor for more than two numbers; tables suit many small data sets)

Chart types — Tufte's own designs where he made one: sparklines with end values, normal-range band and banking to 45°, slopegraphs, the quartile plot and the dot-dash plot.

Flowcharts and diagrams — guidance drawn only from Tufte: connectors that state their meaning (Beautiful Evidence ch. 3), type instead of boxes, layering and separation (Envisioning Information ch. 3), and the smallest effective difference (Visual Explanations ch. 4). Where Tufte gives no rule (shapes, swimlanes, layout direction), none is added. Includes Mermaid and Graphviz notes.

Maps — guidance drawn only from Tufte's writing on data maps: area must not stand for importance, rate maps beside dot maps, testing the effect of aggregation, light-to-dark value scales instead of rainbows, Imhof's muted fields, layered base maps, map small multiples, and documentation on the map (VDQI ch. 1, EI ch. 2–6, VE ch. 2, BE ch. 5). Where Tufte gives no rule (projection, class breaks, cartograms), none is added.

Supported libraries

Library	Rule file	Language
Recharts	rules/recharts.md	React/JSX
ECharts	rules/echarts.md	JavaScript
Chart.js	rules/chartjs.md	JavaScript
matplotlib (and seaborn)	rules/matplotlib.md	Python
Plotly	rules/plotly.md	Python/JS
ggplot2 and plotnine	rules/ggplot2-plotnine.md	R / Python
Vega-Lite and Altair	rules/vega-lite-altair.md	JSON / Python
Observable Plot	rules/observable-plot.md	JavaScript
D3.js / SVG / HTML	rules/svg-html.md	Web

How it's organized

Path	What it holds
SKILL.md	The 22 rules, chart-type guidance, color tokens and a validation checklist. The agent always reads this.
rules/<library>.md	Full configuration and complete examples for one library, with the version it was written for. The agent reads only the one it needs.
rules/interactive-and-accessible.md	Progressive disclosure, accessibility, responsive layout, animation, dark mode
rules/typography-and-color.md	Font stacks, palettes and hex values; the source of truth for colors
rules/anti-patterns.md	Common violations, per-library detection patterns and one-line fixes
rules/small-multiples-sparklines.md	Small multiples, sparklines, slopegraphs, rug plots
rules/diagrams-flowcharts.md	Flowcharts, process maps, org charts and networks, drawn only from Tufte's writing on connectors, layering and explanation
rules/maps.md	Choropleth, dot, flow and small-multiple maps, drawn only from Tufte's writing on data maps
examples/	Runnable reference implementations for Recharts, ECharts, Chart.js, matplotlib, Plotly and SVG
scripts/check_contrast.py	Checks the documented palette against the contrast minimums
_docs/	Showcase figures and the script that generates them

Contributing

Issues and pull requests are welcome. Before opening a PR:

• Changed a color? Update rules/typography-and-color.md, then run python3 scripts/check_contrast.py. It exits non-zero if any text or data color misses its minimum.
• Changed the showcase figures? Run python3 _docs/generate_showcase.py to regenerate every image in _docs/.
• Changed a chart title? Check it against the data. Rule 20 asks titles to state the finding, so a title that misstates the data is a bug.

Credits

tufte-skill began as a fork of caylent/tufte-data-viz by Caylent, and all credit for the original skill goes to its authors (npx skills add caylent/tufte-data-viz). Since then it has added rules for data maps (rules/maps.md) and analytical diagrams (rules/diagrams-flowcharts.md), an accessible palette with a contrast checker, bug fixes across the library guides, audited showcase figures, and a source label on every rule, with misattributions corrected and two rules that were stricter than Tufte brought back to his text.

Based on

• The Visual Display of Quantitative Information (1983)
• Envisioning Information (1990)
• Visual Explanations (1997)
• Beautiful Evidence (2006)

License

MIT; see LICENSE. Original work © 2026 Caylent; additions and changes in this repository © 2026 Mayar Ariss, under the same license.