write-data-viz

name	write-data-viz
description	Produces data visualizations and dashboards as code — matplotlib/seaborn/plotly static and interactive charts, plus D3.js/HTML dashboards — picking chart types that fit the data.
when_to_use	When the user asks to visualize data or build a chart/dashboard — plot a trend, comparison, distribution, or relationship, generate an interactive Plotly/D3 chart, or assemble a multi-panel dashboard from a dataset.

When to Use

Use when the request is to turn data into a visual artifact in code: plot a trend/comparison/distribution/relationship, build an interactive Plotly/D3 chart, or assemble a multi-panel dashboard from a dataset (CSV/JSON/DataFrame/SQL result).

Not this skill: native Excel/Sheets charts embedded in a workbook (that is the spreadsheet skill — this one emits code and web artifacts, png/svg/html).

Steps

1. Inspect the data first — do not guess. Load it and check shape before plotting: row count, dtypes, null counts, cardinality of categorical columns, min/max of numerics. In pandas: df.info(), df.describe(), df.isna().sum(), df[col].nunique(). Decide here whether aggregation is needed (e.g. >5k points → sample/bin; >12 categories → top-N + "Other").

2. Map analytical goal → chart type (the goal is in the request verb, not the user's wording):

   • trend over time → line (or area for cumulative)
   • compare categories → bar (horizontal bar if labels are long or >7 categories)
   • distribution of one variable → histogram or box/violin; KDE if smooth shape matters
   • relationship between two numerics → scatter; add trendline/hexbin if dense
   • part-of-whole → stacked bar or treemap — avoid pie for >3 slices
   • correlation matrix → heatmap
   • ranking → sorted horizontal bar When unsure between two, default to the one with less ink (bar over pie, line over stacked area).

3. Pick the engine by output requirement, not by habit:

   • static report image (png/svg) → matplotlib + seaborn
   • interactive (hover/zoom/toggle) needed → plotly (plotly.express for speed, graph_objects for control)
   • embeddable/standalone web dashboard, custom interaction, or no-Python-runtime delivery → D3.js in a single self-contained HTML file Confirm the library is installed (python -c "import plotly") before writing the full script; if missing, install or fall back to matplotlib and say so.

4. Annotate every chart — non-negotiable, in this order: title (states the takeaway, not "Chart of X"), axis labels with units, legend only when >1 series, source/date note if relevant. Format axis ticks for humans (thousands separators, %, dates as %b %Y). Sort bars by value unless the x-axis is inherently ordered (time, ordinal).

5. Style: use a colorblind-safe palette (matplotlib tab10/viridis, seaborn colorblind, plotly default Safe). Strip chartjunk: no 3D, no gridlines on bars, no background fill, no redundant legend. One accent color for the series that matters; grey out the rest. Set dpi=150+ for static export.

6. Multi-panel dashboard when ≥3 related metrics: matplotlib plt.subplots() / GridSpec, plotly make_subplots, or D3 a CSS-grid of <svg> panels. Share axes where comparable, give each panel its own clear title, keep one consistent palette across panels.

7. Save the artifact and tell the user how to view it. Static → fig.savefig("chart.png", dpi=150, bbox_inches="tight") (use bbox_inches="tight" or labels clip). Interactive plotly → fig.write_html("dashboard.html"). D3 → one HTML file with the data inlined or fetched. State the absolute path and the open command (e.g. open the .html in a browser).

Common Errors

• Overplotting — thousands of scatter points become a blob. Fix with alpha=0.3, hexbin/2D-density, or sampling. Do not ship a solid ink cloud.
• Misleading dual axes — two y-axes invite false correlation and can be scaled to tell any story. Prefer two stacked panels sharing the x-axis; only use twin axes when units are genuinely paired and label both clearly.
• Categorical read as numeric — IDs/year-codes/zip codes loaded as int get a continuous color scale or spaced as numbers. Cast to str/category first.
• Truncated/non-zero bar baseline — bar charts MUST start the value axis at 0 or they exaggerate differences. Line charts may zoom; bars may not.
• bbox clipping — long tick/axis labels get cut off in saved PNGs. Always bbox_inches="tight" and rotate or horizontal-bar long labels.
• Too many colors / rainbow — >7 hues are unreadable. Group, use top-N + Other, or a sequential scale.
• Time not parsed — date strings on the x-axis sort lexically (2026-01 after 2026-1). Parse to datetime before plotting.
• Plotly HTML huge/blank offline — default embeds the full lib (~3MB) and a blank page if CDN is blocked; pass include_plotlyjs="cdn" for size or =True for offline-safe.

Verify

1. Script runs to completion with no exception, and the output file exists on disk (check the path).
2. Open/inspect the rendered artifact — title, both axis labels+units, and legend are present and not clipped.
3. Chart type matches the analytical goal from Step 2 (a trend is a line, not a bar; bars start at 0).
4. No overplotting/rainbow/dual-axis trap from Common Errors slipped through.
5. For interactive output, confirm hover/zoom actually works (open the HTML); for a dashboard, every panel rendered and shares a consistent palette.