/chart-clarity

name: chart-clarity
description: 'Create, review, and restyle data visualizations using Edward Tufte principles: high data-ink ratio, direct labels, range-frame axes, small multiples, accessible color, responsive charts, and honest comparisons. Triggers on: "create a chart", "style this chart", "review this graph", "Tufte chart", "data visualization", "Recharts", "Plotly", "matplotlib", "Chart.js", "ECharts", "D3". Use when generating or critiquing charts, dashboards, sparklines, and data tables.'
metadata:
  version: 1.0.0
  category: visualization
  tags: [charts, data-viz, tufte, accessibility, visualization]
  difficulty: intermediate
  complements:
    - static-web-artifacts-builder
    - ux-expert

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 com