| name | visualize |
| description | Turn data, concepts, or processes into a polished standalone visualization — chart, table, diagram, dashboard, KPI scorecard, timeline, or explainer — written as self-contained code, saved locally, and exported to an image at a 16:9 aspect ratio by default (any ratio on request). Use whenever the user wants to visualize, chart, graph, plot, diagram, or "show" numbers / metrics / a report / a comparison / a breakdown / a trend / a timeline / a flow; pastes a report or table and wants it turned into a graphic; or asks for an infographic, dashboard, scorecard, or a shareable picture of data. Also use for "make this a visual", "render this", "turn this into a chart/graph", or "export a diagram". Do NOT use for editing existing raster images (photo retouching), for a plain in-conversation markdown table with no image export, for live embedded app UI components (use a frontend skill), or for full slide decks (use pptx). |
Visualize
Turn an input — pasted data, a report, a set of numbers, a concept, or a process — into a single, polished visualization, saved as self-contained code and exported to an image at 16:9 by default (any aspect ratio on request).
The design ethos is borrowed from generative UI: read the input, pick the right representation (don't default to a bar chart for everything), and render one self-contained artifact that looks intentional, not auto-generated.
What every run produces
Inside ./visualizations/<slug>/ (relative to the user's working directory unless they give a path):
index.html — the self-contained source (open in any browser, edit by hand)<slug>.png — the rendered image, 1600×900 (16:9) at 2× scale by default
Always end by telling the user both paths and surfacing the PNG.
Workflow
Follow these in order. Each step links to detail only where you need it.
1. Read the input and choose the representation
Match the input to a representation using the decision matrix below. The single most common mistake is reaching for a bar chart when the data wants something else — a few big numbers want a KPI scorecard, a part-to-whole wants a donut, a ranking wants horizontal bars, a process wants a diagram, raw rows want a styled table. Pick deliberately.
| The input is… | Best representation | How to build it |
|---|
| A few headline numbers / metrics | KPI scorecard (big-number cards) | HTML + CSS |
| Categories compared in size / a ranking | Bar chart (vertical or horizontal) | inline SVG |
| A value changing over time / a trend | Line or area chart | inline SVG |
| Parts of a whole (≤6 slices) | Donut / pie + legend | inline SVG |
| Several series across periods (daily/weekly/monthly) | Grouped bars or small multiples, or a scorecard + bars combo | inline SVG + CSS grid |
| Rows of structured records | Styled data table | HTML + CSS |
| A two-variable relationship | Scatter / bubble | inline SVG |
| A process, flow, pipeline, or architecture | Diagram (nodes + connectors) | inline SVG |
| A sequence of dated events | Timeline | inline SVG + CSS |
| Hierarchy / nesting | Treemap or indented tree | inline SVG |
| An abstract concept needing explanation | Annotated explainer (labels + arrows over a diagram) | HTML + SVG |
| Genuinely interactive code deliverable, or 100+ data points | Chart.js (escalation) | CDN, see recipes |
| 3D scene | Three.js (escalation) | CDN, see recipes |
When the input has multiple natural cuts (e.g. the social-analytics example with Daily / Weekly / Monthly across platforms), prefer one composed layout — a header KPI row plus a small set of comparison charts — over three disconnected charts. A dashboard reads as one artifact; three loose charts read as three.
Default to inline SVG + HTML/CSS. It renders pixel-crisp at any resolution, needs no network, and never half-draws during export. Only escalate to Chart.js / Three.js when interactivity in the openable HTML or sheer data volume genuinely calls for it (see references/recipes.md).
2. Set up the output folder
Pick a short kebab-case <slug> from the subject (e.g. social-analytics, q4-revenue, auth-flow). Create ./visualizations/<slug>/.
3. Author index.html
Start from the template — it gives you a correct 16:9 stage, light/dark theming, web-safe typography, and the export-ready signal already wired:
cp <this-skill>/assets/stage.html ./visualizations/<slug>/index.html
Then fill it in (the template has labelled FILL: regions):
- Title / subtitle / source — a real headline, not "Chart". Include the period or date range if the data has one. Put any attribution in the footer slot.
- The viz — replace the
#viz region with your representation. Build charts as inline SVG using the recipes; lay out scorecards/tables with CSS grid/flex.
- The data — transcribe the user's numbers exactly. Double-check every figure against the input; wrong numbers make the whole artifact worthless. Don't invent data to fill space.
- Signal ready — call
vizReady() once the final frame is painted (the template auto-calls it after fonts load + two animation frames, so you only need to call it manually if you draw asynchronously, e.g. a Chart.js onComplete).
Design bar (see references/recipes.md for the full checklist and snippets):
- Fill the stage — no large empty margins, no tiny chart marooned in a sea of background.
- Type scales with the stage using
clamp() / cqmin units (already set up), so it stays legible at any export size.
- A restrained palette: one accent hue + neutrals, or the provided categorical ramp. Avoid rainbow defaults.
- Label directly where you can (value labels on bars, end-of-line labels) instead of forcing the eye to a distant axis.
- Whitespace, alignment, and a clear visual hierarchy (title → key numbers → supporting detail) do most of the work.
4. Export to an image
From the visualization folder (or anywhere, with absolute paths):
node <this-skill>/scripts/render.mjs --in index.html --out <slug>.png
Default output is 1600×900 @2× (16:9). The aspect ratio is fully modifiable:
# A square for Instagram
node <this-skill>/scripts/render.mjs --in index.html --out sq.png --aspect 1:1 --width 1080
# A tall story / phone frame
node <this-skill>/scripts/render.mjs --in index.html --out story.png --aspect 9:16 --width 1080
# Exact pixels
node <this-skill>/scripts/render.mjs --in index.html --out big.png --width 2560 --height 1440
# Transparent background, dark theme
node <this-skill>/scripts/render.mjs --in index.html --out t.png --bg transparent --theme dark
Flags: --aspect (16:9 default, 4:3, 1:1, 9:16, 21:9, 3:2, 2:1), --width/--height (px; give either with --aspect, or both for exact), --scale (DPI multiplier, default 2), --theme (light|dark), --bg (white|transparent|#hex). Full reference: references/recipes.md.
The stage fills the viewport, so one index.html exports cleanly at any ratio. For a drastically different ratio (e.g. designing for 16:9 then exporting 9:16), glance at the result and re-tune the layout if elements crowd or strand — don't assume a 16:9 composition is automatically good as a vertical.
5. Deliver
Confirm the PNG was written, then report the saved index.html and .png paths and surface the image to the user. If the render step failed, see Troubleshooting before reporting success — never claim an image exists without confirming the file.
Troubleshooting the render
render.mjs tries, in order: Playwright with installed Chrome/Edge, then Playwright's bundled Chromium, then a system Chrome/Chromium/Edge/Brave binary directly. One of these is present on most machines. If all fail it prints the exact fix; relay it. The usual one-time install:
npm i -D playwright && npx playwright install chromium
If a chart exports half-drawn or blank, the ready signal didn't fire before capture — make sure asynchronous drawing calls vizReady() on completion, or pass --wait 8000 to give it more time.
Reference
references/recipes.md — copy-paste SVG/CSS recipes (bar, line, area, donut, scatter, KPI cards, table, diagram, timeline), the Chart.js / Three.js escalation patterns, the full design checklist, and every render.mjs flag.assets/stage.html — the 16:9 stage template you copy in step 3.
