| name | tufte-viz |
| description | Designs and critiques data visualizations using Tufte's principles (data-ink ratio, chartjunk elimination, graphical integrity, small multiples, micro/macro, layering and separation). Use when the user asks to design a new chart, dashboard, or report; critique an existing visualization; reduce chartjunk; choose between viz approaches; plan sparkline placement, range-frame plots, slope charts, or layered annotations; or audit a graphic for lie factor. Produces a visual artifact via the zukai skill (HTML page with inline SVG or zukai primitives) when a before/after or redesign is warranted; replies in prose for purely conceptual questions. Don't use for general UI design, illustrations without quantitative content, brand-style decoration, marketing-page layout, or any task where the user is asking about typography/color/layout rather than data display. |
| license | MIT |
Tufte Visualization
Apply Tufte's principles to design clear, honest, high-density data visualizations. When a visual artifact is warranted, render it as a zukai HTML page so the critique itself is multivariate.
References
Read on demand. Do not load all at once.
| File | Read when |
|---|
| references/tufte-principles.md | Grounding an argument in source principles (lie factor, data-ink, chartjunk, small multiples, integrity). |
| references/analytical-design.md | Designing dashboards, dense displays, or explanatory graphics (six principles of analytical design, sparklines, range-frames, layering, micro/macro, causality, confections). |
| references/svg.md | Step 2 selects handcrafted SVG over <zk-diagram>. Path commands, range-frame plot, slope chart, animated draw-in, reduced-motion gating. |
Step 1: Frame the work
Three questions before any drawing or critique:
- What comparisons matter? A graphic that doesn't enable a comparison is a label.
- What's the key insight? If you cannot complete "The reader should leave knowing that ___," the chart has no thesis.
- What's already on the page? Tufte's most-violated rule is show data variation, not design variation. Match the new graphic's visual weight to the rest of the document.
Step 2: Pick the form
| Need | Form | Implementation |
|---|
| Single number in context of a series | <zk-sparkline> inline with prose (never standalone) | zukai primitive |
| Many small comparisons across the same scale | Small multiples: grid of identically-shaped sparklines or mini-plots | <zk-grid> of sparklines, or <zk-grid> of inline SVGs |
| Dense exact values | Well-typeset table with right-aligned tabular numerals (often beats a chart) | <zk-table> |
| Process or causal graph with typed nodes and labeled edges | Flowchart / sequence / state machine | <zk-diagram> (Mermaid) |
| Time series with one or two lines, no node-graph topology | Line chart with range-frame axes (no bounding box, no gridlines) | Handcrafted SVG in a <zk-card>. See references/svg.md |
| Slope chart (before/after, two-time-point comparison) | Two columns of paired values connected by lines, focus series highlighted | Handcrafted SVG. See references/svg.md |
| Annotated point with leader line | Direct label next to the data, never a separate legend | Handcrafted SVG. See references/svg.md |
| Part-to-whole on a small alphabet | Bar chart sorted by value, not category. Never pie. | Handcrafted SVG or <zk-table> with bar-encoded cells |
Decision rule (Mermaid vs SVG): Reach for <zk-diagram> only when the relationships are typed graph nodes (flowchart, sequence, ER, state) and the layout can be auto-computed. Reach for handcrafted SVG when position on a 2D plane carries the data, when the layout is the message, or when Tufte-style annotation (leader lines, layered opacity, range frames) is the point.
Anti-routes: pie charts, dual-axis line charts, 3D anything, donut variants, word clouds, treemaps for fewer than 30 leaves.
Step 3: The Tufte test
A graphic passes only if every item below answers "yes", or has a written reason to fail.
| # | Question |
|---|
| 1 | Lie factor. Is the visual proportion within 5% of the data proportion? Axes start at a defensible baseline? |
| 2 | Data-ink. Can any ink be erased without losing information? Heavy borders, gridlines, axis lines, redundant labels are all candidates. |
| 3 | Eraser test. For every label/tick/annotation: is it duplicated elsewhere? Keep one. |
| 4 | Collision test. Mentally box every text element. Does it overlap data or other text? If yes, push to figcaption, margin, or a leader line. |
| 5 | Compared to what? Is there a baseline, a benchmark, a peer series, or a band that gives the value meaning? A naked number is not a graphic. |
| 6 | Multivariate. Does the graphic carry at least two real dimensions of information? A bar chart of one variable in time is one variable. |
| 7 | Layering. Does primary data clearly dominate (full opacity, full chroma) while secondary recedes (lighter, smaller)? |
| 8 | Micro/macro. Does the reader get both the macro shape and the micro detail without zooming or scrolling? |
| 9 | Integrity. Words, numbers, and image integrated, not segregated? No legend that could have been a direct label? |
| 10 | Chartjunk. Zero decorative texture, moirรฉ, 3D, gradient fills, glow, drop shadows used for emphasis? |
Two or more failures โ redesign before delivering. One failure with a written reason is acceptable when a structural constraint forces it.
Step 4: Deliver
When the request is conceptual only (e.g. "should I use a pie chart here?"), reply in prose: short, with the principle named.
When the request is a critique or redesign, produce a zukai HTML artifact:
- Invoke the zukai skill to compose the page.
- Use
<zk-sparkline> inline with prose for word-sized series. Use <zk-table> for dense exact values. Use <zk-diagram> for causal flows.
- For before/after, render both as
<zk-grid cols="2"> of small multiples on the same scale (not two separate charts in different sizes; that is design variation, not data variation).
- The page must itself pass the Tufte test in Step 3.
When the request is a new visualization, scaffold it in <zk-card>-wrapped SVG inside a zukai page, with the Tufte-test row written into the page as a figcaption checklist the reader can verify.
zukai bridge
The zukai runtime ships three Tufte-aligned primitives. Reach for them before reaching for a chart library.
| zukai element | Tufte primitive | Use when |
|---|
<zk-sparkline> | Sparkline | A number needs context of recent history, in-line with prose |
<zk-table> (striped, tabular-nums) | Well-typeset table | More than ~12 exact values matter |
<zk-diagram> (Mermaid, layered hover) | Process/causality diagram | Explaining a flow or dependency |
Never invent a new chart type when one of these will do. Tufte's harshest critiques target the proliferation of novel chart forms that obscure the data.
Anti-patterns
- "I'll add a chart so the page has a chart." If the chart isn't load-bearing, delete it.
- Adding a legend when a direct label would do.
- Identical chart-junk on every chart in the document (decorative grids, glowing borders). Repeating chartjunk is still chartjunk.
- Dashboard widget syndrome: a grid of single KPIs without supporting series or comparison.
- Pretty wrappers around bad encoding. A glassmorphism panel does not rescue a 3D pie chart.
