This is a complete public transfer package for the locally installed
tufte-viz Claude/Codex skill on this machine. It includes the exact installed
SKILL.md content plus both referenced files:
references/tufte-principles.mdreferences/analytical-design.md
To transfer it to another Claude or Codex environment, create this directory shape and copy the sections below into the matching files:
tufte-viz/
SKILL.md
references/
tufte-principles.md
analytical-design.md
File: SKILL.md
---
name: tufte-viz
description: >-
Critique and redesign data visualizations using Edward Tufte's principles.
Use when: designing new charts, critiquing existing visualizations, reducing
chartjunk, improving data-ink ratio, choosing between chart types, planning
small multiples or high-density displays, reviewing dashboards for graphical
integrity.
---
<!-- TOC: When to Use | Core Insight | Design Workflow | Critique Workflow | Checklist | References -->
# Tufte Visualization
> **When to Use:** Any time you're designing, critiquing, or choosing between data visualizations. Works for charts, dashboards, tables, maps, and explanatory graphics.
>
> **When NOT to Use:** Pure decoration with no data. Tufte principles apply to information graphics, not illustration.
>
> **Core Insight:** Every graphical element must earn its ink. If you can erase something without losing information, erase it. The goal is maximum data density with zero chartjunk — complexity from data, not from decoration.
---
## Best Models
| Tool | Config |
|------|--------|
| **Claude Code + Sonnet 4.6** | Standard reasoning |
| **Codex + o3** | High reasoning for complex multi-variable critique |
---
## Design Workflow (new visualizations)
### 1. Clarify the data story first
- What comparison does the viewer need to make?
- What's the single key insight?
- Answer: "compared to what?" — if you can't, the visualization isn't ready.
### 2. Select the right form
| Need | Form |
|------|------|
| Compare across categories | Bar chart (horizontal if many labels) |
| Show change over time | Line chart, minimal grid |
| Show distribution | Dot plot or strip plot (not histogram unless n > 1000) |
| Compare many slices | Small multiples, not a pie |
| Dense multi-variable | Scatter + layering, or table with sparklines |
### 3. Apply the eraser test
For every element — gridline, border, label, tick, legend, annotation — ask: can this be erased without losing information?
- Numeric label + bar height → keep one, not both
- Legend + direct labels → direct labels win
- Heavy grid + data line → lighten grid to near-invisible
### 4. Apply the collision test
For every text element, draw its bounding box mentally. Does anything else cross it?
- Move prose out of the plot into caption/figcaption
- Push reference-line labels to the left margin
- Add leader lines for dense scatter annotations
### 5. Ship with documentation
Every chart needs: source, date, what was measured, sample size. Provenance enables trust.
---
## Critique Workflow (existing visualizations)
1. **Lie factor check** — does the visual effect match the data effect? `Lie Factor = effect in graphic / effect in data`. Should be ≈ 1.0.
2. **Chartjunk scan** — heavy grids, 3D effects, moiré patterns, decorative color, drop shadows, clip art.
3. **Data-ink ratio** — what percentage of the ink is carrying data? Maximize it.
4. **Small multiples opportunity** — would splitting into panels enable direct comparison that's currently impossible?
5. **Integration check** — are words, numbers, and images segregated (bad) or interleaved (good)?
---
## Quick Checklist
- [ ] Lie Factor ≈ 1.0
- [ ] Maximum data-ink ratio
- [ ] Zero chartjunk
- [ ] Direct labeling (no legend if avoidable)
- [ ] Answers "compared to what?"
- [ ] Shows causality or mechanism, not just pattern
- [ ] Multivariate (not over-reduced to one variable)
- [ ] Words, numbers, images integrated
- [ ] Micro + macro: rewards both a glance and close reading
- [ ] Primary data dominates; grids/axes recede
- [ ] Source + scale + date documented
---
## References
- `references/tufte-principles.md` — lie factor, data-ink, chartjunk, small multiples, graphical integrity, data density
- `references/analytical-design.md` — sparklines, layering/separation, micro/macro design, range-frames, the 6 principles of analytical design, causality visualization, confections
File: references/tufte-principles.md
# Tufte's Principles for Data Visualization
## 1. Graphical Excellence
Excellence in statistical graphics consists of complex ideas communicated with clarity, precision, and efficiency.
**Core qualities:**
- Show the data
- Induce the viewer to think about substance, not methodology or design
- Avoid distorting what the data have to say
- Present many numbers in a small space
- Make large datasets coherent
- Encourage eye comparison of different pieces of data
- Reveal data at several levels of detail (broad overview to fine structure)
- Serve a reasonably clear purpose
- Integrate closely with statistical and verbal descriptions
**Questions to ask:**
- Does the graphic show the data clearly?
- Does it encourage thinking about content over decoration?
- Can the viewer compare data elements easily?
---
## 2. Graphical Integrity
Graphics must tell the truth about the data.
**The Lie Factor:**
Lie Factor = Size of effect shown in graphic / Size of effect in data
- Lie Factor = 1.0: Truthful
- Lie Factor > 1.05 or < 0.95: Distortion
**Six principles of graphical integrity:**
1. Representation of numbers should be directly proportional to quantities represented
2. Clear, detailed, thorough labeling defeats distortion
3. Show data variation, not design variation
4. In time-series displays, standardize money (deflate) and use consistent baselines
5. Dimensions of graphics should not exceed dimensions of data
6. Graphics must not quote data out of context
**Common violations:**
- 3D effects on 2D data (adds fake dimension)
- Truncated axes that exaggerate change
- Inconsistent intervals
- Area/volume encoding of linear data
- Missing context or baselines
---
## 3. Data-Ink Ratio
The data-ink ratio is the proportion of a graphic's ink devoted to the non-redundant display of data-information.
Data-Ink Ratio = Data-ink / Total ink used in graphic
**Maximize the data-ink ratio within reason:**
1. Erase non-data-ink (decoration, heavy grids, boxes)
2. Erase redundant data-ink (3D when 2D suffices)
3. Revise and edit
**Non-data-ink to eliminate:**
- Heavy gridlines
- Unnecessary borders and boxes
- Redundant labels
- Decorative elements
- Excessive tick marks
- 3D effects that add no information
**The eraser test:** If you can erase something without losing data information, erase it.
---
## 4. Chartjunk
Chartjunk is the interior decoration of graphics that does not convey information.
**Three categories of chartjunk:**
### A. Unintentional optical art (moiré vibration)
- Busy patterns that create visual noise
- Cross-hatching that vibrates
- Competing visual frequencies
### B. The Grid
- Heavy grids compete with data
- Grids should be muted or eliminated
- If needed, use light gray or dotted lines
### C. The Duck (self-promoting graphics)
- Graphics that draw attention to their own design
- Decoration masquerading as information
- Style over substance
**Chartjunk indicators:**
- Viewer notices the design before the data
- Colors/patterns used for decoration not encoding
- 3D effects, shadows, gradients without purpose
- Clip art, icons, or illustrations that don't carry data
---
## 5. Small Multiples
Small multiples are series of graphics showing the same combination of variables, indexed by changes in another variable.
**Characteristics:**
- Same design structure repeated
- Changes in data, not design
- Enables direct visual comparison
- High information density
- Eye moves across variations effortlessly
**When to use:**
- Comparing across categories, time periods, or conditions
- Showing change or variation
- Revealing patterns across groups
- When animation would work but static display is needed
**Design guidelines:**
- Identical scales across all panels
- Consistent visual encoding
- Minimal between-panel decoration
- Clear labeling of what varies
- Tight spacing (data should dominate)
---
## 6. Data Density & Information Resolution
**Data density = numbers plotted per unit area**
High data density is a sign of graphical quality. Maps and time-series can achieve thousands of numbers per square inch.
**Shrink principle:** Graphics can often be reduced significantly while maintaining readability and gaining impact. Consider:
- Sparklines (word-sized graphics)
- Condensed time-series
- Small multiple arrays
**Resolution thinking:**
- What's the minimum size that remains readable?
- Can we show more data in the same space?
- Are we wasting white space?
---
## 7. Multifunctioning Graphical Elements
Every graphical element should serve multiple purposes when possible.
**Data measures that can serve as:**
- Data point
- Label
- Scale marker
- Grid reference
**Examples:**
- Data points that also serve as labels (scatter plots with text)
- Axis that is also a data series
- Range frames (axis shows data range, not arbitrary extent)
---
## 8. Aesthetics and Technique
**Balance complexity and simplicity:**
- Simple design, complex data
- Complexity should come from data, not decoration
**Visual hierarchy:**
- Data > Labels > Annotations > Grids > Borders
- Prominent elements should carry the most information
**Color use:**
- Use sparingly and purposefully
- Ensure accessibility (colorblind-safe)
- Gray as default, color for emphasis or encoding
- Avoid "rainbow" color maps for sequential data
**Typography:**
- Clear, readable fonts
- Appropriate sizing hierarchy
- Horizontal text when possible
- Labels close to data they describe
---
## Quick Reference: The Tufte Test
For any visualization, ask:
1. **Data-Ink:** Can I erase any element without losing data? (Erase it)
2. **Integrity:** Does the visual effect match the data effect? (Lie Factor ≈ 1)
3. **Chartjunk:** Does any element exist for decoration only? (Remove it)
4. **Excellence:** Does it reveal the data at multiple levels? (Broad + detailed)
5. **Comparison:** Can the viewer easily compare data elements? (Enable it)
6. **Density:** Could this show more data in the same space? (Condense)
7. **Context:** Is all necessary context provided? (Labels, sources, scales)
File: references/analytical-design.md
# Analytical Design, Sparklines, and Layering
Extends `tufte-principles.md` with material from *Envisioning Information* (1990), *Visual Explanations* (1997), and *Beautiful Evidence* (2006).
---
## 1. The Six Principles of Analytical Design
From *Beautiful Evidence*. The most actionable framework Tufte produced — applies to any analytical presentation, not just charts.
1. **Show comparisons, contrasts, differences**
The fundamental analytical act. Every display should answer "compared to what?"
2. **Show causality, mechanism, structure, explanation**
Move beyond description. What's the *why* behind the pattern?
3. **Show multivariate data — more than 1 or 2 variables**
Real problems are multivariate. Reducing to a single variable hides interactions.
4. **Completely integrate words, numbers, images, diagrams**
Don't segregate by mode. Labels next to the data they describe; equations next to the curves they generate.
5. **Thoroughly describe the evidence**
Provenance, authorship, scales, sources, measurements. Documentation enables trust.
6. **Analytical presentations ultimately stand or fall depending on the quality, relevance, and integrity of their content.**
No amount of design fixes weak evidence. Content is paramount.
**Use in critique:** walk through all six. The lowest-scoring principle is usually the biggest improvement opportunity.
---
## 2. Sparklines
Word-sized, data-intense graphics. Tufte's signature *Beautiful Evidence* invention.
**Defining properties:**
- Typographic resolution — sized like text, embedded inline with prose or tables
- No axes, no labels, no decoration
- Endpoints often marked (start/end values, or min/max)
- Reveals shape, trend, variability at a glance
**Design rules:**
- Height ≈ x-height of surrounding text (~14-20px)
- Length ≈ a word or short phrase
- Use a single red/colored dot to flag a key point (current value, anomaly)
- Pair with the most recent numeric value: `120 ▁▂▃▅▇▇▆▅ 132`
- Stack in tables so eyes can scan vertically
**When to use:**
- Dashboards with many metrics (one row per metric: name | sparkline | current | delta)
- Inline prose: "revenue trended up ▁▂▄▆▇ over the quarter"
- Anywhere a full chart would dominate but trend matters
**When not to use:**
- When precise readings matter — sparklines show shape, not value
- For categorical or part-to-whole data
---
## 3. Layering and Separation
From *Envisioning Information*. The most useful concept for dense displays.
**The principle:** Visually distinct elements can coexist in the same space if they're *layered* — separated by value, weight, hue, or transparency rather than spatial isolation.
**Techniques:**
- **1+1=3 effect:** two heavy lines next to each other create a phantom third line. Lighten one to suppress this.
- **Hierarchy by weight:** primary data in dark/saturated; secondary in light gray; annotations even lighter.
- **Color for separation, not decoration:** distinct hues let overlapping data remain readable.
- **Whisper, don't shout:** grids, axes, reference lines should fade into the background — present but unobtrusive.
**Test:** squint at the graphic. The most important data should remain visible; chartjunk should disappear first.
---
## 4. Micro/Macro Design
Distinct from raw data density. A micro/macro graphic reveals **different stories at different viewing distances**.
- **Macro view** (zoomed out, peripheral): overall pattern, shape, trend
- **Micro view** (close inspection): individual data points, labels, exceptions
**Canonical examples:**
- Vietnam Memorial: macro = sweep of names; micro = a single name
- Galaxy maps: macro = structure; micro = individual stars
- Financial tables with sparklines: macro = which rows trended up; micro = the actual values
**Design implication:** don't choose between overview and detail — show both simultaneously by layering.
---
## 5. Escaping Flatland
The 2D page/screen is inherently flat; good information design adds dimensions *without* 3D gimmicks.
**Dimensions you can add on flat media:**
- Color (categorical or sequential)
- Size (continuous)
- Shape (categorical)
- Position (2-3 axes via projection)
- Time (small multiples, animation, or sparkline-style inline series)
- Layering (foreground/background via value)
**Anti-pattern:** 3D bar charts, pie charts with depth, isometric projections that distort proportions. These add visual dimension without adding information dimension — pure chartjunk.
---
## 6. Range-Frame and Dot-Dash Plot
Tufte's signature reinventions of standard chart elements. Direct applications of data-ink maximization.
**Range-frame:**
- Replace the full axis with a line that spans only the *range of actual data*
- Axis ends at min/max values, not arbitrary round numbers
- Tells the viewer the data extent without explicit annotation
**Dot-dash plot:**
- Scatter plot where the axes are replaced by marginal rug plots
- Each axis becomes a 1D distribution of the data on that variable
- Same ink, more information — the axes now show marginal density
**Pattern:** every standard chart element (axis, tick, gridline) can be redesigned to carry data.
---
## 7. Confections, Parallelism, Narrative
From *Visual Explanations*.
**Confections:** assemblages of disparate visual elements (images, maps, text, diagrams) into a single explanatory composition. Examples: Minard's Napoleon march, Snow's cholera map, exploded technical illustrations. They work when each element serves the argument.
**Parallelism:** repetition of visual structure to enable comparison — small multiples are one form, but parallelism extends to side-by-side maps, before/after states, repeated annotation styles.
**Narrative graphics of space and time:** combine spatial and temporal dimensions in one frame. Minard's Napoleon graphic encodes troop size, geography, direction, temperature, and time simultaneously.
---
## 8. Cause and Effect
From *Visual Explanations*. Causality is hard to visualize because it requires showing both the variables and the mechanism linking them.
**Techniques:**
- Show the intervention and the response in the same frame
- Annotate the causal mechanism directly on the data
- Use sequence (small multiples through time) to imply mechanism
- Pair the data display with a process diagram showing the proposed cause
**Worked example:** Challenger O-ring decision. The available data, plotted against temperature, showed catastrophic risk — but the engineers presented it in a way that hid the causal relationship. Tufte's redesign makes the causality unavoidable.
---
## Quick Reference: Extended Tufte Test
After applying the standard 7-question test in `tufte-principles.md`, add:
8. **Comparison:** Does the graphic answer "compared to what?"
9. **Causality:** Is the mechanism or explanation visible, not just the pattern?
10. **Multivariate:** Are interactions among variables shown, or has the problem been over-reduced?
11. **Integration:** Are words, numbers, and images interleaved — or segregated?
12. **Documentation:** Can a stranger evaluate the evidence (sources, scales, authorship)?
13. **Layering:** Do important elements dominate; do secondary elements recede?
14. **Micro/macro:** Does the display reward both a glance and a close read?