Skip to content
Back to search

tufte-data-viz

Agent skill: Edward Tufte's data visualization principles for clean, honest, high-data-ink-ratio charts. Recharts, ECharts, Chart.js, matplotlib, Plotly, D3/SVG.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/caylent--tufte-data-viz/badge.svg)](/listings/caylent--tufte-data-viz)

HTML

<a href="/listings/caylent--tufte-data-viz"><img src="/api/listings/caylent--tufte-data-viz/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add caylent/tufte-data-viz

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 233 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: tufte-data-viz
  3. description: >-
  4. Use when creating, reviewing, or styling charts, graphs, dashboards,
  5. sparklines, or any data visualization. Applies to Recharts, ECharts,
  6. Chart.js, matplotlib, Plotly, seaborn, D3.js, and SVG. Enforces Tufte
  7. principles (data-ink ratio, direct labeling, range-frame axes) plus
  8. modern screen-first standards (accessibility, responsive, dark mode).
  9. allowed-tools: Read, Glob, Grep
  10. ---
  11. # Tufte Data Visualization
  12. Apply Edward Tufte's principles whenever generating or reviewing code that renders data visually. This skill covers chart generation, not slide/presentation design.
  13. ## Workflow
  14. Follow these steps in order when creating any chart:
  15. ### Step 1: Identify the message
  16. Before writing code, determine:
  17. 1. The key finding or trend the chart must make visible.
  18. 2. The comparison context — a baseline, prior period, target, or peer group. A number without context is meaningless.
  19. 3. The chart type that best fits the data structure (see Chart type guidance below).
  20. ### Step 2: Apply universal rules
  21. Review the rules below. Every rule is a default — deviate only when the user explicitly requests otherwise.
  22. ### Step 3: Apply library-specific config
  23. Use the Library quick reference table to find the essential overrides for the target library. For complete code examples and helper functions, read ONE rule file from `rules/` matching the library.
  24. ### Step 4: Validate
  25. Run through the validation checklist at the bottom of this file before presenting the chart.
  26. ---
  27. ## Universal rules
  28. Rules 1–14 cover static principles; 15–19 extend them for screens; 20–22 address content and formatting.
  29. ### 1. Remove top and right borders
  30. No chart should have top or right axis lines, borders, or spines. The bottom and left axes are sufficient. Top and right lines are pure chartjunk.
  31. ### 2. Direct labels, not legends
  32. Label each data series directly — at the endpoint of a line, on or beside a bar, next to a cluster. Remove the `<Legend>` component entirely. If there is only one series, the chart title provides that context; no label is needed.
  33. ### 3. No gridlines by default
  34. The default is zero gridlines. For static charts where users need to read precise values, add horizontal-only gridlines at very low opacity (0.08–0.12). For interactive charts, prefer a contextual crosshair on hover instead (see rule 15). Never add vertical gridlines.
  35. ### 4. Range-frame axes
  36. Axis lines should span only the range of the data, not from zero to some arbitrary maximum. The axis starts at (or near) the minimum data value and ends at the maximum.
  37. ### 5. No 3D effects
  38. No perspective, no depth, no shadows on chart elements. Two-dimensional data gets two-dimensional representation.
  39. ### 6. No pie charts unless explicitly requested
  40. Default to a horizontal bar chart sorted by value. If the user explicitly asks for a pie chart: maximum 4 slices, 2D only, start at 12 o'clock, direct percentage labels on each slice.
  41. ### 7. Aspect ratio ~1.5:1
  42. Charts should be approximately 50% wider than tall. Standard sizes: 600x400, 750x500, 900x600. Exception: sparklines and small multiples may be more compact.
  43. ### 8. Gray first, highlight selectively
  44. The default data series color is medium gray (`#666`). Use a single accent color to highlight the most important series or data point. Never use more than 4 distinct colors. Choose the right palette type: **categorical** (4-color muted) for unordered groups, **sequential** (single-hue ramp) for ordered magnitude, **diverging** (two-hue from center) for deviation from a midpoint. See `rules/typography-and-color.md` for hex values.
  45. ### 9. Off-white background
  46. Light mode: `#fffff8`. Dark mode: `#151515`. Never use pure white (`#ffffff`) or pure black (`#000000`).
  47. ### 10. Serif fonts for data
  48. Use serif fonts for data labels, annotations, and chart titles: `"ET Book", "Palatino Linotype", Palatino, "Book Antiqua", Georgia, serif`. Sans-serif (system-ui, sans-serif) is acceptable only for small axis tick labels (11-12px).
  49. ### 11. No dual y-axes
  50. Two y-axes on one chart create false implied correlations. Use small multiples instead — two charts stacked vertically with shared x-axis.
  51. ### 12. Annotate the notable
  52. If the data contains a peak, trough, inflection point, or event boundary, add a text annotation pointing to it directly on the chart. Place annotations in the nearest clear space — offset from the data point with a short leader line if needed. When multiple annotations compete for space, keep only the most important; move others to a footnote or tooltip.
  53. ### 13. Show comparison context
  54. Include at least one reference element: a reference line (average, target, prior period), a shaded band, or a second series. A chart showing one line with no context fails the "Compared to what?" test.
  55. ### 14. Minimal tooltips
  56. Tooltips should be plain text with the data value and label. No colored background, no border, no arrow pointer, no shadow.
  57. ### 15. Progressive disclosure over static density
  58. Default to the Tufte-clean overview — high data-ink, minimal chrome. Layer details through hover, tap, and click (values, annotations, comparisons). Don't frontload everything onto a single static view. A contextual crosshair on hover replaces permanent gridlines.
  59. ### 16. Accessible by default
  60. 3:1 contrast ratio minimum for chart elements against their background; 4.5:1 for text in charts. Never use color as the sole differentiator — pair with shape, pattern, or direct label. Provide a text alternative for every chart (`aria-label` with key finding, or companion data table). Interactive charts must be keyboard-navigable.
  61. ### 17. Responsive, not just resized
  62. Charts must have a responsive strategy — fluid (percentage width + viewBox), adaptive (breakpoint-based layout changes), or hybrid. At narrow viewports, change chart type or layout (horizontal bars for categories, reduced tick density, abbreviated labels), don't just shrink.
  63. ### 18. Animate to explain, not to decorate
  64. Transitions for data changes (sorting, filtering, time progression) are good — they help the viewer track transformations. Gratuitous entrance animations, bouncing, and decorative motion are chartjunk. Duration: 200–500ms, ease-out. Always respect `prefers-reduced-motion`.
  65. ### 19. Dark mode as first-class citizen
  66. Design both light and dark palettes intentionally. Never invert colors. Reduce saturation in dark mode (bright colors "vibrate" on dark backgrounds). Respect `prefers-color-scheme`. Use semantic color tokens (`--tufte-bg`, `--tufte-text`, `--tufte-series-default`) so charts adapt automatically.
  67. ### 20. Titles assert findings
  68. The chart title states the key insight, not the axis description. "Revenue Surged 23% in Q3" not "Revenue by Quarter, 2024". The subtitle can provide context ("vs. prior year, USD millions"). If the data has no clear finding, the chart may not be needed (see rule 22).
  69. ### 21. Format numbers for humans
  70. Abbreviate large numbers: $1.2M not $1,200,000. Use thousand separators for mid-range numbers (12,450 not 12450). Match decimal precision to significance (don't show $4.2391M when $4.2M suffices). Right-align numbers in tables. Use consistent units and state them once (in the axis label or title), not on every data point.
  71. ### 22. Don't chart what a sentence can say
  72. If the data is 1–2 numbers, write a sentence with inline context ("Revenue was $4.2M, up 23% from Q2"). If the data is a simple ranking of 3–5 items, consider a table. Charts earn their space by revealing patterns, trends, or distributions that text and tables cannot. A chart of two bars is almost always worse than a sentence.
  73. ---
  74. ## Library quick reference
  75. The universal rules above are sufficient for most charts. For complete code examples and library-specific helpers, read the appropriate rule file from the `rules/` directory in this skill's folder. Only read ONE rule file per task.
  76. | Library | Rule file to read | Essential config (apply even without reading the file) |
  77. |---------|-------------------|--------------------------------------------------------|
  78. | Recharts | `rules/recharts.md` | `<CartesianGrid stroke="none" />`, remove `<Legend />`, `<YAxis axisLine={false} tickLine={false} />`, `<Line dot={false} strokeWidth={1.5} />` |
  79. | ECharts | `rules/echarts.md` | `splitLine: { show: false }`, `legend: { show: false }`, `grid: { show: false }`, use `endLabel` on series |
  80. | Chart.js | `rules/chartjs.md` | `grid: { display: false }`, `border: { display: false }`, `plugins.legend.display: false`, use `chartjs-plugin-datalabels` |
  81. | matplotlib | `rules/matplotlib.md` | `spines['top'].set_visible(False)`, `spines['right'].set_visible(False)`, `spines['bottom'].set_bounds(min, max)`, `font.family: serif` |
  82. | Plotly | `rules/plotly.md` | `showgrid=False`, `showlegend=False`, `plot_bgcolor='#fffff8'`, `zeroline=False` |
  83. | D3/SVG/HTML | `rules/svg-html.md` | `.domain { display: none }`, no `<rect>` backgrounds, `stroke-opacity: 0.1` for any gridlines |
  84. ---
  85. ## Chart type guidance
  86. | Type | Key settings |
  87. |---|---|
  88. | **Line** | 1.5–2px stroke, `dot={false}` unless <7 points (then r=2), direct label at rightmost point |
  89. | **Bar** | Prefer horizontal for categories, sort by value descending, direct value labels, `#7a7a7a` default fill |
  90. | **Scatter** | Gray dots `#999` r=3, highlight key cluster/outlier with accent, regression line if meaningful (dashed, thin) |
  91. | **Time series** | Label events on chart ("Recession", "Launch"), range-frame x-axis, YoY via opacity (current solid, prior 30%) |
  92. | **Small multiples** | Same scale ALL panels, shared axis labels (x on bottom row, y on left column), no panel borders |
  93. | **Sparklines** | ~80x20px, no axes/labels/gridlines, min/max dots r=1.5, embed inline in text or table cells |
  94. | **Data tables** | No zebra striping, whitespace + thin rules every 3–5 rows, right-align numbers, `font-feature-settings: 'onum' 1` |
  95. | **Slopegraph** | Before/after categories, label both endpoints (value + name), gray default + highlight key slopes |
  96. | **Area** | Prefer lines. If area: fillOpacity 0.03–0.08, no gradient, direct labels at endpoints |
  97. | **Stacked bar** | Avoid — use small multiples instead. If forced: sort by total, direct labels per segment, max 4 segments |
  98. | **Heatmap** | Sequential or diverging palette only, value labels in cells, companion data table for accessibility |
  99. For small multiples, sparklines, and slopegraph implementation patterns, see `rules/small-multiples-sparklines.md`.
  100. ---
  101. ## Color quick reference
  102. | Token | Light | Dark |
  103. |---|---|---|
  104. | Background | `#fffff8` | `#151515` |
  105. | Text | `#111` | `#ddd` |
  106. | Text secondary | `#666` | `#999` |
  107. | Axis/rule | `#ccc` | `#444` |
  108. | Grid (if used) | `#eee` (8-12% opacity) | `#333` |
  109. | Default series | `#666` | `#999` |
  110. | Highlight | `#e41a1c` | `#fc8d62` |
  111. **Categorical (max 4):** `#4e79a7` steel blue · `#f28e2b` tangerine · `#e15759` coral · `#76b7b2` sage
  112. Font stacks in rule 10. For full palettes (sequential, diverging), font loading, and old-style figures, see `rules/typography-and-color.md`.
  113. ---
  114. ## Anti-pattern detection
  115. When reviewing existing chart code, check for: legends (→ direct labels), pie charts (→ horizontal bars), 3D effects (→ flat 2D), dual y-axes (→ small multiples), heavy gridlines (→ remove or 0.1 opacity), rainbow palettes (→ gray + accent), gauge widgets (→ number + sparkline), gradient fills (→ solid color), rotated labels (→ flip axes or abbreviate), pure white/black backgrounds (→ `#fffff8`/`#151515`), hover-only information (→ tap/focus fallback), missing text alternatives (→ `aria-label`), color-only encoding (→ add shape/pattern).
  116. For the full table with per-library detection patterns and one-liner fixes, see `rules/anti-patterns.md`.
  117. ---
  118. ## Validation checklist
  119. Before presenting any chart, verify:
  120. - [ ] No top or right borders/spines
  121. - [ ] No Legend component — series labeled directly on the chart
  122. - [ ] Gridlines removed or horizontal-only at opacity <= 0.12
  123. - [ ] Aspect ratio approximately 1.5:1
  124. - [ ] Background is `#fffff8` (light) or `#151515` (dark), not pure white/black
  125. - [ ] Serif font for data labels and titles
  126. - [ ] Default series color is gray (`#666`); color used only for emphasis
  127. - [ ] No 3D effects, no pie chart (unless explicitly requested)
  128. - [ ] Axis lines span only the data range (range-frame)
  129. - [ ] Notable data features annotated directly on chart
  130. - [ ] Comparison context present (reference line, band, or second series)
  131. - [ ] Tooltips are plain text with no decorative styling
  132. - [ ] Interactive elements have tap/click/focus alternatives (no hover-only)
  133. - [ ] Contrast ratios meet 3:1 (elements) / 4.5:1 (text) minimums
  134. - [ ] Chart has a text alternative (aria-label, description, or data table)
  135. - [ ] Animations respect `prefers-reduced-motion`
  136. - [ ] Charts render usably at 320px and 1440px+ widths
  137. - [ ] Title states the finding, not the axis description
  138. - [ ] Numbers are formatted for readability (abbreviations, separators, consistent precision)
  139. - [ ] A chart is warranted — the data couldn't be communicated as a sentence or table
  140. ---
  141. ## Additional resources
  142. **Library rules** (read ONE per task): `rules/recharts.md`, `rules/echarts.md`, `rules/chartjs.md`, `rules/matplotlib.md`, `rules/plotly.md`, `rules/svg-html.md` — complete code examples, helpers, and theme registrations.
  143. **Cross-cutting** (read when specifically needed):
  144. - `rules/interactive-and-accessible.md` — progressive disclosure, WCAG, responsive, animation, dark mode
  145. - `rules/typography-and-color.md` — font loading, full palette tables, old-style figures
  146. - `rules/anti-patterns.md` — per-library detection heuristics and fixes
  147. - `rules/small-multiples-sparklines.md` — layout patterns for small multiples, sparklines, slopegraphs
  148. **Working examples** in `examples/` — one per library, plus an inline SVG sparkline.
README.md · README · 116 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # tufte-data-viz
  2. An agent skill that applies [Edward Tufte's](https://www.edwardtufte.com/) data visualization principles when generating charts, plots, and graphs. Produces clean, honest, high-data-ink-ratio visualizations across multiple charting libraries — extended with modern screen-first standards for accessibility, responsiveness, and interactivity.
  3. ## Fair warning
  4. This skill is **opinionated by design**. It will remove your gridlines, delete your legends, reject your pie charts, and insist on serif fonts. 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.
  5. ## Install
  6. ```bash
  7. npx skills add caylent/tufte-data-viz
  8. ```
  9. ## Before & After
  10. The same data, default styling vs. Tufte principles applied:
  11. ![Before and after comparison — default chart style vs. Tufte style](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/before-after.png)
  12. See it happen live — gridlines fade, legends become direct labels, chartjunk dissolves:
  13. ![Animated transition from default chart styling to Tufte principles](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/before-after-animated.gif)
  14. ## Interactive Demo
  15. **[Try the live demo](https://caylent.github.io/tufte-data-viz/)** — toggle between default and Tufte styling across ECharts, Chart.js, Plotly, and D3.js. Includes dark mode.
  16. ## Examples
  17. ### Line chart — direct labels, range-frame axes, annotation
  18. ![Tufte-styled line chart showing revenue vs. target with direct labels and peak annotation](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/tufte-line-chart.png)
  19. ### Horizontal bar chart — sorted by value, highlighted leader
  20. ![Tufte-styled horizontal bar chart with direct value labels and highlighted top product](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/tufte-bar-chart.png)
  21. ### Slopegraph — before/after comparison
  22. ![Slopegraph showing team size changes from 2024 to 2025, highlighting Engineering growth](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/tufte-slopegraph.png)
  23. ### Small multiples — shared scale, minimal chrome
  24. ![Small multiples showing revenue trend by region with shared y-axis](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/small-multiples.png)
  25. ### Sparklines — word-sized charts with min/max markers
  26. ![Five sparklines showing key metrics over 24 months with min and max markers](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/tufte-sparklines.png)
  27. ### Data table — whitespace, thin rules, highlighted outlier
  28. ![Tufte-styled data table with thin rules, right-aligned numbers, and highlighted growth leader](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/tufte-data-table.png)
  29. ### Dark mode — intentional palette, not inverted
  30. ![Dark mode line chart with desaturated highlight color on dark background](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/tufte-dark-mode.png)
  31. ### Accessible scatter — dual-encoded with shape + color
  32. ![Scatter plot using different shapes per segment so data is distinguishable without color](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/tufte-accessible-scatter.png)
  33. ### Light & dark — same chart, both themes
  34. ![Side-by-side bar chart in light and dark mode showing intentional palette design](https://raw.githubusercontent.com/caylent/tufte-data-viz/main/_docs/tufte-light-dark.png)
  35. ## What it does
  36. 22 universal rules applied to every chart, organized in three tiers:
  37. **Static principles (rules 1–14)** — the Tufte foundation:
  38. - Maximize data-ink ratio — remove gridlines, borders, legends, and decoration that don't convey data
  39. - Direct labeling, range-frame axes, no 3D, no pie charts (unless forced), no dual y-axes
  40. - Serif typography, off-white backgrounds, gray as primary color with selective highlighting
  41. - Annotate notable features, show comparison context, minimal tooltips
  42. **Screen-first principles (rules 15–19)** — modern interactive contexts:
  43. - Progressive disclosure (overview first, details on hover/tap/click)
  44. - WCAG accessibility (contrast ratios, dual encoding, keyboard nav, screen reader text alternatives)
  45. - Responsive design (fluid/adaptive strategies, touch targets, mobile-adapted chart types)
  46. - Purposeful animation (data transitions only, respect `prefers-reduced-motion`)
  47. - Intentional dark mode (semantic color tokens, never invert, reduce saturation)
  48. **Content & formatting (rules 20–22)** — what Tufte assumed but never codified:
  49. - Titles assert findings ("Revenue Surged 23%"), not axis descriptions
  50. - Numbers formatted for humans ($1.2M, thousand separators, matched precision)
  51. - Don't chart what a sentence or table can say better
  52. ## Supported libraries
  53. | Library | Rule file | Language |
  54. |---------|-----------|----------|
  55. | [Recharts](https://recharts.org/) | `rules/recharts.md` | React/JSX |
  56. | [ECharts](https://echarts.apache.org/) | `rules/echarts.md` | JavaScript |
  57. | [Chart.js](https://www.chartjs.org/) | `rules/chartjs.md` | JavaScript |
  58. | [matplotlib](https://matplotlib.org/) | `rules/matplotlib.md` | Python |
  59. | [Plotly](https://plotly.com/) | `rules/plotly.md` | Python/JS |
  60. | D3.js / SVG / HTML | `rules/svg-html.md` | Web |
  61. ## Additional references
  62. - `rules/interactive-and-accessible.md` — progressive disclosure, accessibility, responsive, animation, dark mode
  63. - `rules/typography-and-color.md` — font stacks, palettes, hex values
  64. - `rules/anti-patterns.md` — common violations and one-liner fixes
  65. - `rules/small-multiples-sparklines.md` — small multiples, sparklines, slopegraphs
  66. ## Based on
  67. - *The Visual Display of Quantitative Information* (1983)
  68. - *Envisioning Information* (1990)
  69. - *Visual Explanations* (1997)
  70. - *Beautiful Evidence* (2006)
  71. ## License
  72. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.