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

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:

Cross-cutting references:

Chart Type Guidance

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.