chart-clarity

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.

1. 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".
2. Identify comparison context. Add a baseline, prior period, target, average, peer group, or distribution. A number without comparison context is weak evidence.
3. 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.
4. 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.
5. Read one library reference. For implementation code, read exactly one matching library file from references/rules/ unless the task compares multiple libraries.
6. Validate before presenting. Run the checklist at the end of this file against the final chart or review output.

Universal Rules

1. Remove top and right borders, spines, frames, and plot boxes.
2. Use direct labels instead of legends. Remove legend components unless the user explicitly requires one.
3. Remove gridlines by default. If precision reading requires gridlines, use horizontal-only rules at 8-12% opacity.
4. Use range-frame axes where the axis spans the data range rather than arbitrary empty space.
5. Use two-dimensional marks only. No 3D, shadows, bevels, gradients, or perspective effects.
6. Avoid pie charts. If explicitly requested, use no more than four slices, direct percentage labels, and 2D rendering only.
7. Aim for an aspect ratio near 1.5:1 for ordinary charts. Sparklines and small multiples are exceptions.
8. Start with gray data marks and one accent color for the key point, line, or series. Use no more than four distinct colors.
9. Use off-white light backgrounds (#fffff8) and intentional dark backgrounds (#151515). Avoid pure white and pure black.
10. Use serif fonts for titles, labels, annotations, and data values. Small axis ticks can use system sans-serif.
11. Do not use dual y-axes. Use small multiples with shared x-axis or shared scales.
12. Annotate peaks, troughs, inflection points, event boundaries, and outliers directly on the chart.
13. Show comparison context with a reference line, target, prior-period series, shaded band, or peer group.
14. Keep tooltips plain: label, value, unit, and minimal context. No shadows, arrows, decorative panels, or color blocks.
15. Use progressive disclosure. Keep the overview clean and reveal details through hover, focus, tap, or click.
16. Make charts accessible: 3:1 contrast for chart elements, 4.5:1 for text, text alternatives, keyboard access, and no color-only encoding.
17. Make charts responsive by changing layout, tick density, or chart type across viewport widths. Do not merely shrink dense desktop charts.
18. Animate data transformations only. Respect prefers-reduced-motion.
19. Treat dark mode as a separate palette. Never invert colors mechanically.
20. Make titles assert findings, not describe axes.
21. Format numbers for humans: $1.2M, 12,450, consistent precision, units stated once.
22. 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 #fffff8 or 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.