mathews-tom Chart Clarity
Create and critique charts that make quantitative comparisons obvious without decorative chartjunk. This skill adapts Caylent's MIT-licensed tufte-data-viz skill into armory under the broader chart-clarity name. It applies Edward Tufte's core data visualization principles and adds screen-first requirements for accessibility, responsiveness, dark mode, progressive disclosure, and human-readable numbers.
Use this skill whenever the user asks for a chart, graph, plot, dashboard visualization, sparkline, slopegraph, data table, or visualization review. It covers Recharts, ECharts, Chart.js, matplotlib, Plotly, seaborn, D3.js, SVG, and HTML.
When to Use
| User need | Use chart-clarity |
Use instead |
|---|---|---|
| Generate chart code in Recharts, Plotly, matplotlib, Chart.js, ECharts, D3, SVG, or HTML | Yes | — |
| Review an existing chart for misleading design, clutter, accessibility, or readability | Yes | — |
| Restyle dashboard charts while keeping the dashboard structure unchanged | Yes | ux-expert for broader dashboard UX |
| Build a static infographic or rich HTML artifact around charts | No | static-web-artifacts-builder |
| Design a slide deck or presentation using charts | No | html-presentation, marp-slides, or pptx |
| Design logos, posters, icons, or non-data visuals | No | concept-to-image or canvas-design |
Trigger Families
- Chart creation: "create a chart", "plot this data", "make a graph", "build a sparkline", "generate a slopegraph".
- Chart review: "review this visualization", "what is wrong with this graph", "make this chart clearer", "remove chartjunk".
- Tufte-specific: "Tufte chart", "high data-ink ratio", "range-frame axes", "small multiples", "direct labels".
- Library-specific: "Recharts", "ECharts", "Chart.js", "matplotlib", "seaborn", "Plotly", "D3", "SVG chart".
Workflow
Follow this order for every chart task.
- Identify the message. Determine the finding the chart needs to make visible. A useful title states the finding: "Revenue Beat Target by 24% in Q2", not "Revenue by Month".
- Identify comparison context. Add a baseline, prior period, target, average, peer group, or distribution. A number without comparison context is weak evidence.
- Choose the chart type. Use the data shape to select line, horizontal bar, scatter, small multiple, sparkline, slopegraph, heatmap, or table. Refuse pie charts by default; use sorted horizontal bars unless the user explicitly asks for a pie chart.
- Apply the universal rules. Remove decorative ink, direct-label series, use gray-first color, annotate notable features, format numbers for humans, and ensure the chart earns its space.
- Read one library reference. For implementation code, read exactly one matching library file from
references/rules/unless the task compares multiple libraries. - Validate before presenting. Run the checklist at the end of this file against the final chart or review output.
Universal Rules
- Remove top and right borders, spines, frames, and plot boxes.
- Use direct labels instead of legends. Remove legend components unless the user explicitly requires one.
- Remove gridlines by default. If precision reading requires gridlines, use horizontal-only rules at 8-12% opacity.
- Use range-frame axes where the axis spans the data range rather than arbitrary empty space.
- Use two-dimensional marks only. No 3D, shadows, bevels, gradients, or perspective effects.
- Avoid pie charts. If explicitly requested, use no more than four slices, direct percentage labels, and 2D rendering only.
- Aim for an aspect ratio near 1.5:1 for ordinary charts. Sparklines and small multiples are exceptions.
- Start with gray data marks and one accent color for the key point, line, or series. Use no more than four distinct colors.
- Use off-white light backgrounds (
#fffff8) and intentional dark backgrounds (#151515). Avoid pure white and pure black. - Use serif fonts for titles, labels, annotations, and data values. Small axis ticks can use system sans-serif.
- Do not use dual y-axes. Use small multiples with shared x-axis or shared scales.
- Annotate peaks, troughs, inflection points, event boundaries, and outliers directly on the chart.
- Show comparison context with a reference line, target, prior-period series, shaded band, or peer group.
- Keep tooltips plain: label, value, unit, and minimal context. No shadows, arrows, decorative panels, or color blocks.
- Use progressive disclosure. Keep the overview clean and reveal details through hover, focus, tap, or click.
- Make charts accessible: 3:1 contrast for chart elements, 4.5:1 for text, text alternatives, keyboard access, and no color-only encoding.
- Make charts responsive by changing layout, tick density, or chart type across viewport widths. Do not merely shrink dense desktop charts.
- Animate data transformations only. Respect
prefers-reduced-motion. - Treat dark mode as a separate palette. Never invert colors mechanically.
- Make titles assert findings, not describe axes.
- Format numbers for humans:
$1.2M,12,450, consistent precision, units stated once. - Do not chart one or two numbers. Use a sentence or table when that communicates more clearly.
Library Quick Reference
Read one matching reference file for concrete implementation details:
| Library | Reference | Essential defaults |
|---|---|---|
| Recharts | references/rules/recharts.md |
Hide grid, remove <Legend />, direct labels, no top/right axes, minimal tooltip |
| ECharts | references/rules/echarts.md |
splitLine.show: false, legend.show: false, grid.show: false, endLabel |
| Chart.js | references/rules/chartjs.md |
grid.display: false, plugins.legend.display: false, direct labels plugin |
| matplotlib/seaborn | references/rules/matplotlib.md |
Hide top/right spines, set spine bounds, serif fonts, off-white figure background |
| Plotly | references/rules/plotly.md |
showgrid=False, showlegend=False, plot_bgcolor='#fffff8', zeroline=False |
| D3/SVG/HTML | references/rules/svg-html.md |
Minimal domains, no plot backgrounds, direct SVG text labels, accessible roles |
Cross-cutting references:
| Topic | Reference |
|---|---|
| Anti-pattern detection and one-line fixes | references/rules/anti-patterns.md |
| Accessibility, responsiveness, animation, dark mode | references/rules/interactive-and-accessible.md |
| Full palettes, font stacks, numeric typography | references/rules/typography-and-color.md |
| Small multiples, sparklines, slopegraphs | references/rules/small-multiples-sparklines.md |
| Working examples | references/examples/ |
| Interactive before/after demo, CDN-backed and reference-only | references/interactive-demo.html |
| Upstream license and provenance | references/upstream/ |
Chart Type Guidance
| Type | Default treatment |
|---|---|
| Line | 1.5-2px stroke, no dots unless fewer than seven points, direct label at endpoint, annotate notable events |
| Bar | Prefer horizontal bars for categories, sort descending, label values directly, use gray with one accent |
| Scatter | Small gray dots, highlight key cluster or outlier, add regression line only when analytically justified |
| Time series | Label events on the chart, compare against target or prior period, avoid dual axes |
| Small multiples | Same scale across panels, shared labels, no panel borders, direct panel titles |
| Sparkline | Word-sized, no axes or labels, min/max dots, endpoint value when useful |
| Table | Whitespace and thin rules, right-aligned numbers, no zebra striping, highlight meaningful outlier only |
| Slopegraph | Before/after endpoints labeled with names and values, gray slopes plus one highlight |
| Heatmap | Sequential or diverging palette, cell values where readable, companion table for accessibility |
Review Checklist
Before presenting code or critique, verify:
- No top or right border/spine/frame.
- No legend where direct labels work.
- Gridlines are absent or horizontal-only at opacity no greater than 0.12.
- Aspect ratio fits the data and target viewport.
- Background uses
#fffff8or an intentional dark palette, not pure white or black. - Data labels and titles use a serif font stack.
- Default series color is gray; accent color is selective.
- No 3D, decorative gradients, shadows, gauges, or chartjunk.
- No dual y-axis.
- The chart includes comparison context.
- The most important peak, trough, outlier, event, or inflection point is annotated.
- Tooltips are plain and accessible.
- Hover details have tap or focus alternatives.
- Text alternatives exist through
aria-label, nearby summary text, or data table. - Colors meet contrast requirements and are not the sole encoding.
- Animation is purposeful and respects reduced motion.
- The chart remains usable at narrow and wide viewports.
- The title states a finding.
- Numbers use readable units and consistent precision.
- The chart is warranted; a sentence or table would not communicate better.