Chart dashboard
Turn whatever information the user gives — a table, pasted numbers, a set of
metrics, notes, or just a topic and some facts — into a single self-contained
HTML page of SVG charts rendered with charts-lib: a dashboard, a report, or a
slide deck.
Workflow
Extract the data. Pull every number, category, and time series out of the
user's input into a short plan: for each planned panel note title, chart
type, categories, series. If the user gave a topic with no numbers, say
plainly that figures are illustrative and label them as such on the page.
Never silently invent numbers that read as real measurements.
Three things count as invention, and the last two are easy to miss:
- Filling a gap. A missing week is a gap (
null), not a zero — a zero
draws a collapse that never happened. And a gap only reads as one if the
series is unsmoothed: Charts.line defaults to spline, which drops nulls
and draws an unbroken curve through the hole. Set type: 'line' on any
series with an interior gap.
- Estimating onto a real chart. If you interpolate or model a value, it
does not belong as another point on the primary trend, however carefully you
dash the line or footnote it. Readers remember the shape, not the caveat.
Put estimates in their own panel, or leave the hole visible.
- Rescaling stale numbers. When you're updating an existing page and the
user gave you new figures for only some panels, label the rest as carried
forward. Nudging last quarter's numbers so they look current is fabrication
even though every individual figure came from somewhere real.
Pick the format by what the data has to say (see references/layout.md).
The question is whether the page states a conclusion or lets the reader draw
their own:
- Dashboard — a monitoring surface. Panels stand on their own, the reader
scans for what changed, and no prose tells them what to think. Use
templates/dashboard.html. This is the right default when the user hands
you metrics without an argument attached.
- Report — an argument with evidence. Reach for it when the user is trying
to convince someone ("write up", "for the board", "retrospective",
"analysis"), or when they told you the conclusion themselves and the page
exists to support it. Use
templates/report.html.
- Deck — an argument delivered by someone, one claim per slide, read
from across a room or clicked through in a tab. Reach for it when the user
says presentation, slides, deck, "present this", "walk them through it", or
names a meeting the page has to survive. Use
templates/slides.html.
When it's genuinely ambiguous, ask yourself who reads it and whether you will
be in the room. Nobody presents a bento grid to a board, and nobody watches a
five-section narrative to see if last night's numbers moved. The deck is the
one format that assumes a presenter: if the page has to stand alone with no
one narrating, it is a report, however much the user said "slides".
Editable or static. Static is the default. Build an editable page
only when the user asked for one: charts stored as JSON, text marked
editable, and an Edit page button that opens a built-in editor, so they
can switch chart types, change text or numbers, and save the file later
without you. If they haven't asked, offer it once when you hand over the
first page (see Output). The format and its rules are in
references/editable.md. Read that file before building one; for a
dashboard, start from templates/dashboard-editable.html.
Copy the template. It lives in this skill's own directory — resolve
templates/ relative to the directory containing this SKILL.md, never from a
hard-coded home path:
<skill-dir>/templates/dashboard.html → ./index.html
<skill-dir>/templates/report.html → ./index.html
<skill-dir>/templates/slides.html → ./index.html
<skill-dir>/templates/dashboard-editable.html → ./index.html (only when asked for editable)
Do not copy assets/charts-lib/ next to the output. The template's three
charts-lib/… tags are placeholders; leave them exactly as written while you
build the page, and fold the library in as the last step (step 9). Their
order matters and the inliner preserves it — theme must load before charts.
Derive the structure from the findings, not from the template. The
dashboard template deliberately ships with a placeholder two-cell grid,
because any arrangement shipped there would end up on every page this skill
produces.
(Building a deck? A deck derives its evidence from the findings the same
way, but its spine is fixed, and references/layout.md § Compose the
sequence has the four passes — read it before writing slides. In short: write
the claims, group them into sections (one section per question the data
answers), then lay the spine before any evidence slide — l-cover first,
l-agenda second, an l-section divider before each section when there are
two or more, and an l-statement last carrying the recap and the ask. Only
then choose a layout per claim. The reason the spine goes down first is that
scaffolding added at the end is scaffolding that gets forgotten: the same
findings would otherwise produce a deck with an agenda one run and none the
next. The template's eighteen example slides are a catalogue of the available
layouts, never a running order.)
Before writing markup, answer: what is the dominant shape of this analysis
(one trend / a head-to-head comparison / a ranking / a funnel / a
distribution / parallel equal measures / geography)? Is there genuinely one
panel that is the reason the page exists? The answers pick the opening row —
worked derivations for each shape are in references/layout.md § Compose the
grid from the findings.
Two checks before you move on. A hero must be earned: w8 h2 goes to a
panel only when one finding dominates; co-equal measures get equal cells, and
promoting one is a claim the data doesn't make. And if your top row came out
as a wide line chart plus a donut plus a small panel, verify that it came from
the data — that is the shape this skill falls into by reflex, and it is
right only when a single trend really does lead and composition really is the
second thing the reader needs.
One sizing rule the grid doesn't enforce for you: tables size themselves.
table, reportTable and barInsightTable are as tall as their rows, so
they go in a content-sized <div class="bento flow"> row, never in a fixed
cell or an .h2. A fixed cell leaves a blank band under the last row. Give a
reportTable chart column a width that fits its data, and choose the
smallest span that holds the table (layout.md § Tables size themselves).
Choose a chart per panel using references/chart-selection.md, then write
the config against references/chart-api.md (the full charts-lib API: every
factory, option, and theme token). Read that file before writing chart code —
don't guess option names.
For a single fact about one engine — what it refuses, whether it self-sizes,
how many grid tracks it wants, its minimum readable size — read
assets/charts-lib/charts.manifest.json instead of the whole API file. It is
the same index the library carries as Charts.meta, kept in step with the
code by the build, and it also holds the shared plotBox and grid rules.
Check the chart's input contract first (chart-selection.md § Input
contract). Each engine accepts a particular kind of x and y, and a mismatch
is a broken panel rather than a style choice. The one that bites most often:
a line chart needs an ordered x — dates, numbers, or labels that carry
their own rising sequence ('Jan'…'Dec', 'Q1'…'Q4', 'Week 1'…'Week 12').
Named categories (regions, browsers, departments) render an error panel
instead of a chart; use Charts.column when x is a name.
Two more references come in at this step when they apply: write the panel
titles against references/narrative.md (where a finding goes, and how to
state it without editorializing), and if the page has a filter or dropdown,
read references/controls.md before wiring it.
Check any claim that does arithmetic. Titles reach for comparative
shapes — "more than the next two combined", "half of all", "double the
nearest" — because they are satisfying to write, and they are the easiest
sentences in a deck to get wrong: the shape sounds right while the numbers
say otherwise, and nobody re-adds the column before presenting. Add up the
numbers you are claiming about before you write the sentence, and if the
arithmetic does not hold, state the comparison that does. A chart that
contradicts its own title is worse than a chart with a dull title.
When a panel marks something up — an intervention, a projection, a
target, a labelled anomaly — read references/annotation.md for the cue and
its mechanics. Colour and stroke are per-series on a line, so actual-vs-
forecast is two series, not one styled midway.
If the user pointed at a brand — their site, a stylesheet, a screenshot, a
set of hex codes — recolor to match, and change nothing else. Read
references/theming.md and run the bundled extractor:
node <skill-dir>/scripts/extract-theme.js <their-css-or-html>
It harvests the design's canvas, series hue, and any color reserved for a
utility role, then runs the same OKLCH recipe described in theming.md:
paper, greyscale ink, a seven-step series ramp, and accent/annotation/
counter — taken from the design where it has a color that fits the role,
derived by hue rotation where it doesn't. Apply its Charts.applyPalette
block once, before the first chart call — hand it the palette and let
theme.js re-derive the roles; assigning roles one by one leaves tiles,
tooltips and dimmed legend keys on the old colours. Fix anything it marks FAIL rather than
shipping it. Check the series hue it picked against what you know the
brand's colour to be: the script ranks by how the CSS uses a colour, which
usually finds the brand colour and occasionally promotes a heavily-used
secondary instead. The report also names the design's typeface — reported,
not applied, unless the page can genuinely load the face (see § One design
system, only the colors change).
If all you have is one brand color — a single hex, no CSS to harvest —
run the same recipe with nothing observed:
node <skill-dir>/scripts/generate-theme.js '#2323FF'
Verify before reporting done. The page still has its charts-lib/…
placeholders at this point, so to run it you need the library beside it
temporarily. Stage it — step 8 removes it again:
node <skill-dir>/scripts/finalize.js index.html --stage
Then use the strongest check your environment supports:
If you built a deck, check it on paper too. It is made to be handed
round as a PDF, and that path has failures the screen never shows: print to
PDF (or open the print preview) and confirm one slide per sheet, nothing
crossing a page edge, and the dark slides still dark. A slide whose content
outgrew its frame is silently cropped there rather than scrolled.
If the page has any control, test it. Change each dropdown to a
non-default value and confirm — with a screenshot or by reading the rendered
text back — that the affected charts redraw and that any action title
recomputed with them. An untested filter is usually a broken filter.
Fold the library into the page, and ship one file. A dashboard outlives
the folder it was written in — it gets emailed, dropped in Slack, committed
to a wiki, opened from Downloads. A page that loads charts-lib/charts.js
from a sibling folder renders as an empty grid the moment it travels alone,
and it fails silently: the markup, the headings and the KPI numbers are all
there, so it looks like a styling bug rather than a missing dependency. So
the last build step replaces the three placeholder tags with the library's
own contents. One command does the whole ending — checks the page as built,
inlines the library, removes the staged copy, then re-checks with --final,
which this time insists the page is standalone:
node <skill-dir>/scripts/finalize.js index.html
It stops before inlining if the build checks fail, since inlining a broken
page only makes it a bigger broken page, and its exit code is the gate: a
non-zero exit means you are not done. It removes a sibling charts-lib/
only when that folder holds exactly the three files it staged, so a folder
of your own that happens to share the name survives.
The result is one ~590 KB HTML file that opens over file:// with no server,
no network, and no sibling folder. Some rules that follow from that:
- Never reintroduce a
<script src> or <link href> to anything. No CDN
for a chart library, a font, an icon set, or a CSS reset — an offline
reader, a locked-down laptop, or an air-gapped review gets a broken page.
Web fonts are the common slip: name the family in the CSS stack and let it
fall back to the system face, which is what the template already does.
- Images go in as
data: URIs or not at all.
- The library is inlined verbatim. Don't minify it, don't strip the parts
you think a page doesn't use, and don't hand-edit the inlined copy — a
bug fixed in the page instead of in
assets/charts-lib/ is lost on the
next build. Rerunning finalize.js on an already-inlined file is a
harmless no-op, so it is safe to re-run after edits.
- If the user explicitly asks for the split form — they're checking the
page into a repo beside other pages that share the library, say — skip
finalize.js and keep the staged charts-lib/ next to the output, with
the placeholder tags as the real references. Check that page with
scripts/check-page.js index.html (no --final, which would fail it for
the references it is supposed to have). That is the exception, not the
default.
Rules that keep output good
- One idea per panel. A panel whose title needs "and" is two panels.
- Lead with the finding that matters most: if one trend is the reason the page
exists, give it the wide top-left cell (
w8 h2). If nothing dominates — three
equally important measures, say — don't manufacture a hero; equal panels are
the honest layout. The rest of the grid follows the same logic: the shape of
the analysis picks the rows, and a layout reused from the last page is a layout
that describes the last page's data (references/layout.md).
- Every panel gets a
title and a subtitle that states units and scope
("USD thousands · Q4 2025"). Put units in yAxis.suffix and
tooltip.valueSuffix too.
- A projection is never drawn in the same stroke as a measurement: dash the
forecast (or
scenario:'forecast' on bars) and name the notation in the
subtitle. See references/annotation.md.
- Match the chart to what the data is, not to what looks good: a line only
where x is time or a number, a donut/waffle only where the parts are
non-negative and sum to one whole, a scatter only where both axes are
measures. See
chart-selection.md § Input contract.
- Order categorical bars by value, not alphabetically. Keep time on the x-axis
left-to-right.
- Donuts stop being readable somewhere around six wedges — below a few percent
the angles are indistinguishable and the reader is just reading the legend.
Roll the tail into "Other", or use a ranked bar list if the tail is the point.
- Don't restate a series in two panels unless the second adds a new cut.
- Annotate what matters:
callouts: [{ x, text }] on line charts for spikes,
launches, and anomalies mentioned by the user.
How many charts? One per finding — no quota, no padding
The page is not a container to fill up. Each panel should answer a question the
reader actually has, and the count falls out of the data rather than out of a
target. Ask of every panel: what would the reader do differently after seeing
this? If the answer is nothing, it isn't a panel.
That cuts both ways, and both failures are common:
- Padding. Given four numbers from an A/B test, the honest page is two or
three panels and a plain statement of the lift. Filling a twelve-cell grid
means inventing a donut of two nearly-identical sample sizes, a fabricated
daily time series, a "by segment" split nobody measured. The moment you are
reaching for something to chart, you have run past the end of the data — stop
there. A small page that answers the question is a better deliverable than a
full grid that pads it, even though the full grid looks more impressive at a
glance.
- Compression. Given twenty measures that each carry a finding, don't force
them into eight panels by stacking unrelated series onto shared axes. Let the
page be long.
When there are only a few panels, widen them (w6/w8/w12) so the grid still
reads as a designed page rather than a half-empty one — a two-panel dashboard is
two big panels, not two small panels marooned top-left.
Reports work the same way: a figure exists because a claim in the prose needs
evidence. A section that states no claim needs no chart, and a claim the reader
will accept without proof doesn't need one either.
Fit the page to how it will be read
The dashboard and report templates are tuned for someone reading at a desk.
When the user tells you otherwise — "I'm presenting this", "send it round",
"print it" — the same page fails badly in that other context. Presenting is the
case with its own template: a deck (templates/slides.html) is the right answer
to "I'm presenting this", not a dashboard with the type scaled up. For the other
two the fix is how much you put on the page and at what size, never a different
design system. All three cases are in references/layout.md § Fit the page to
how it will be read.
Make the chart show the finding, not just the data
Three defaults in charts-lib are deliberately plain, and taking them as-is is
how a page ends up technically correct and useless. Override them on purpose:
Emphasis. Read the title you just wrote. If it names specific categories,
a specific series, or a specific moment — "the top two account for 90%",
"Direct outperformed Partner", "the drop came after the March update" — the
chart leaves categorical mode and enters emphasis mode: the subject takes the
accent, everything else takes Charts.theme.muted. A finding stated in words
above eight identical bars is a finding the reader has to re-derive.
The mechanism differs by what the subject is — per-point color for
categories, series color + lineWidth for one line among many, plotBands
and callouts for a moment, a tinted centerText for a donut's focal wedge.
All of them, plus the grouped-chart series-vs-cluster split, are in
references/chart-selection.md § Emphasis. Three constraints hold across all
of them: two colors, not a rainbow (multi-hue and an accent reads as no
emphasis at all), at most 2–3 accented items (past that, go back to the
full categorical palette), and muted still has to be readable — context
bars are data too, which is why muted is derived at 3:1 against the canvas
rather than picked for how quiet it looks.
In a deck, emphasis mode is the exception and the plain ramp is the
default. Not a different rule — the same one, biting harder: a deck is where
the urge to make the point is strongest, and a grey supporting bar stops
saying anything by the third slide that has one. Write no color unless the
chart's own title names the points it means.
Three standing rules that apply whether or not the chart is in emphasis mode:
residual categories ("Other", "Don't know", a rolled-up tail) always take
muted, since they can never be the finding; several context series take one
identical mute rather than a ramp, so they read as a single band; and one
emphasis per chart — an accented bar and a callout on that same bar is two
competing signals, not double the emphasis.
Status vs. emphasis. When a chart mixes measured, planned, and projected
numbers, don't spend a palette color on the distinction — encode it in the
fill with scenario: 'plan' | 'forecast' (outlined / hatched) and keep color
for the finding. A projection drawn identically to a measurement is the same
failure as inventing the number.
Data labels. The library draws them in every chart type by default. Opt
out with dataLabels: false where they'd collide — dense lines, many bars,
grouped columns with 3+ series. See references/chart-selection.md § Data labels.
Geofacet variant. 'bar' is what you get by typing nothing, which is not
a reason to use it three times on one page. 'heat' when the spatial pattern
is the point, 'gauge' when regions are measured against a shared target.
See references/chart-api.md § Geofacet.
If you add a control, wire it
A dropdown that doesn't change the charts is worse than no dropdown: it reads as
a broken page, and the reader stops trusting the numbers that are correct. So
either add no controls at all — a static page is a perfectly good deliverable —
or wire them completely, which means the data is filtered rather than the label,
every dependent panel re-renders, and any action title recomputes from the same
filtered rows. Redraw through a helper that calls the old chart's destroy()
first: without it, old charts' resize observers keep repainting the unfiltered
chart on every window resize, and they pile up with each filter change. If the page has a control, read references/controls.md: it
has the render(state) and draw() pattern in full, the guards to apply before shipping
one, and the cases where small multiples beat a filter.
Legends go in one place
charts-lib puts the legend at the top, under the subtitle, and shows it
automatically once a chart has two or more series or wedges. Leave it there. A
reader scanning a grid of panels learns the legend's location once; a page where
it sits above one chart, beside another and below a third makes them re-hunt for
it every time, and that hunting is the entire cost of an inconsistent layout.
So: don't pass legend position options per chart, don't build legends in HTML
next to the chart, and don't hand-place colored dots in a panel's corner. If a
legend genuinely doesn't earn its space — single-series panels, or a donut whose
wedges are already labelled by callouts — turn it off with
legend: { enabled: false } for every panel in that situation, not just the
cramped one. The only sanctioned alternative is charts-lib's own
lineLabels: 'inline', and if you use it on one line chart, use it on all of
them.
Put the finding in the title
A chart titled "Weekly throughput by site" makes the reader do the work of
finding the point. A chart titled "Throughput fell 12% the week of the WMS
cutover" hands it to them and then proves it underneath — the insight lives in
the chart's own hierarchy, so it travels with the figure into a screenshot, a
slide, or an email. The finding goes in title, the units and scope stay in
subtitle.
The line that keeps this from becoming editorializing is whether the chart
proves the sentence: "Billing drives 27% of all tickets" is measurable off the
chart, "Billing is a serious problem" is a verdict the reader should reach
themselves. When no single finding dominates, a plain descriptive title is the
honest choice — don't manufacture a headline.
Read references/narrative.md before writing the titles. It has the
write-this/not-this table, the length budget per cell, and the three-way choice
between an action title, Charts.barInsightTable, and a soft surface card —
including the rule that stops the same sentence appearing in two of them.
Nothing on the page that isn't data or its labels
- No invented narrative furniture that repeats what a chart already says: no
"Key insight" banners, no "Executive summary" you wrote yourself, no
highlighted takeaway strip across the top, no emoji, no "🚀".
- The header is title, one line of scope, and the reporting window. The footer is
sources, definitions, and any honesty notes (illustrative figures, carried-
forward panels, data-quality caveats). Nothing else belongs in either.
- Conclusions the user themselves stated ("the March spike is the thing I need to
explain") belong on the relevant chart — as its title or a callout, in their
framing — not restated as your own analysis in a banner.
One design system, only the colors change
Every visible component follows charts-lib's design language: its type scale,
weights, spacing rhythm, stroke widths, hairlines, legend position and chart
geometry. Those proportions are what make ten different chart types read as one
family, and the page chrome inherits them so the cards don't look bolted on.
The colors are the exception, and the only exception. When a user supplies a
brand, recolor via Charts.applyPalette — once, before the first factory call,
never per chart — and let the page chrome pick those same values up from the sync
block in the template. Corner radius may follow the brand too, since square vs.
rounded is a brand signature the charts themselves don't express.
Do not introduce a second visual system on top: no custom card headers with
their own type scale, no gradient hero panels, no shadows or borders the template
doesn't already have.
Type is the one place where copying the brand usually backfires. Most brand faces
are licensed webfonts you cannot load into a local file, and naming one in
font-family just falls through to a system fallback you didn't choose — worse
than keeping charts-lib's stack, which was picked to work at 11px in a chart. In
a chart the cost is not only aesthetic: the engines measure label widths against
the face they think they have, so a substituted one makes axis labels the engine
had fitted collide. And a page that reaches for a webfont stops being standalone
(step 8). Match the brand's font only when the face is genuinely available — a
system font, or a file the user supplied. extract-theme.js reports the
design's face and says outright whether it is loadable; when it isn't, keep the
template stack and tell the user which face you couldn't use and why. Full
method in references/theming.md.
The page has exactly five kinds of component, all already in the template:
header, optional KPI row, chart panels, optional soft surface
card (.note), footer. The KPI row
exists because headline figures genuinely help — use the template's .kpi
markup, which is sized off the chart type scale so the tiles look like they
belong to the same page. Writing your own KPI strip with new CSS is the most
common way this page ends up looking like two designs stapled together, and it
is the thing to resist even though it feels helpful. A KPI tile is a label, a
number, and at most one line of plain context — no arrows, no red/green verdicts,
no "▲ 12% vs LY" badges.
If you find yourself writing new CSS classes, stop and ask whether a chart panel
would carry the information better. Usually it would.
Output
One HTML file, standalone — no sibling charts-lib/ folder, no CDN tags, no
network at open time (see step 8). A deck ships the same way, and a reader turns
it into a PDF with their browser's own Print → Save as PDF: the template sets
A4 landscape, one slide per sheet. Write it to the working directory (or where
the user asked). Then surface
it however your environment does that — attach or render the file if you can (in
Claude Code: SendUserFile with display: "render"); otherwise print the
absolute path and tell the user to open it in a browser. Either way, state which
figures came from the user's data and which, if any, were illustrative.
On the first page you build in a conversation, if the user didn't ask for
an editable page, end with a one-line offer of one, such as: "Want an
editable version, so you can switch chart types and change the text or
numbers yourself without rerunning this?" Only offer it once. Build it only
on a yes, following references/editable.md.
An editable page ships as two files: finalize.js writes <name>.html as
the final copy (no editor, safe to share) and <name> (working copy).html as
the editable one. Hand over both and say in one line which is which. The
working copy shows a "Working copy" banner, a DRAFT print watermark and a
"Draft ·" tab title, so it isn't mistaken for the final version.
Environment notes
Nothing in this skill requires a specific agent or vendor. It needs only the
ability to read files from this directory, write an HTML file, copy a folder,
and run Node (for finalize.js and the static checks). Without Node, inline
the three library files by hand — paste charts.css into a <style> and
theme.js then charts.js into <script> blocks, in that order, replacing the
placeholder tags. An editable page also gets assets/page-runtime.js in a
<script> block after them. Browser preview, screenshots, and file attachment are used
when available and degrade gracefully when not.
1---2name: chart-dashboard-23description: Build a self-contained HTML dashboard, data-story report, or slide deck from supplied information (metrics, tables, notes, pasted data, a topic), rendered with the bundled zero-dependency charts-lib SVG chart library. Use whenever the user asks for a dashboard, analytics page, KPI/bento view, illustrated report, or a presentation, slides or a deck built from data they provide or describe.4metadata:5 source: https://skillmd.com/skills/raghuramsirigiri/chart-dashboard-26---78# Chart dashboard910Turn whatever information the user gives — a table, pasted numbers, a set of11metrics, notes, or just a topic and some facts — into a single self-contained12HTML page of SVG charts rendered with `charts-lib`: a dashboard, a report, or a13slide deck.1415## Workflow16171. **Extract the data.** Pull every number, category, and time series out of the18 user's input into a short plan: for each planned panel note *title, chart19 type, categories, series*. If the user gave a topic with no numbers, say20 plainly that figures are illustrative and label them as such on the page.21 Never silently invent numbers that read as real measurements.2223 Three things count as invention, and the last two are easy to miss:24 - **Filling a gap.** A missing week is a gap (`null`), not a zero — a zero25 draws a collapse that never happened. And a gap only reads as one if the26 series is unsmoothed: `Charts.line` defaults to `spline`, which drops nulls27 and draws an unbroken curve through the hole. Set `type: 'line'` on any28 series with an interior gap.29 - **Estimating onto a real chart.** If you interpolate or model a value, it30 does not belong as another point on the primary trend, however carefully you31 dash the line or footnote it. Readers remember the shape, not the caveat.32 Put estimates in their own panel, or leave the hole visible.33 - **Rescaling stale numbers.** When you're updating an existing page and the34 user gave you new figures for only some panels, label the rest as carried35 forward. Nudging last quarter's numbers so they look current is fabrication36 even though every individual figure came from somewhere real.372. **Pick the format by what the data has to say** (see `references/layout.md`).38 The question is whether the page states a conclusion or lets the reader draw39 their own:40 - **Dashboard** — a monitoring surface. Panels stand on their own, the reader41 scans for what changed, and no prose tells them what to think. Use42 `templates/dashboard.html`. This is the right default when the user hands43 you metrics without an argument attached.44 - **Report** — an argument with evidence. Reach for it when the user is trying45 to convince someone ("write up", "for the board", "retrospective",46 "analysis"), or when they told you the conclusion themselves and the page47 exists to support it. Use `templates/report.html`.48 - **Deck** — an argument delivered *by someone*, one claim per slide, read49 from across a room or clicked through in a tab. Reach for it when the user50 says presentation, slides, deck, "present this", "walk them through it", or51 names a meeting the page has to survive. Use `templates/slides.html`.5253 When it's genuinely ambiguous, ask yourself who reads it and whether you will54 be in the room. Nobody presents a bento grid to a board, and nobody watches a55 five-section narrative to see if last night's numbers moved. The deck is the56 one format that assumes a presenter: if the page has to stand alone with no57 one narrating, it is a report, however much the user said "slides".5859 **Editable or static.** Static is the default. Build an *editable* page60 only when the user asked for one: charts stored as JSON, text marked61 editable, and an **Edit page** button that opens a built-in editor, so they62 can switch chart types, change text or numbers, and save the file later63 without you. If they haven't asked, offer it once when you hand over the64 first page (see Output). The format and its rules are in65 `references/editable.md`. Read that file before building one; for a66 dashboard, start from `templates/dashboard-editable.html`.673. **Copy the template.** It lives in this skill's own directory — resolve68 `templates/` relative to the directory containing this SKILL.md, never from a69 hard-coded home path:70 ```71 <skill-dir>/templates/dashboard.html → ./index.html72 <skill-dir>/templates/report.html → ./index.html73 <skill-dir>/templates/slides.html → ./index.html74 <skill-dir>/templates/dashboard-editable.html → ./index.html (only when asked for editable)75 ```76 Do **not** copy `assets/charts-lib/` next to the output. The template's three77 `charts-lib/…` tags are placeholders; leave them exactly as written while you78 build the page, and fold the library in as the last step (step 9). Their79 order matters and the inliner preserves it — theme must load before charts.804. **Derive the structure from the findings, not from the template.** The81 dashboard template deliberately ships with a placeholder two-cell grid,82 because any arrangement shipped there would end up on every page this skill83 produces.8485 *(Building a deck? A deck derives its **evidence** from the findings the same86 way, but its **spine** is fixed, and `references/layout.md` § Compose the87 sequence has the four passes — read it before writing slides. In short: write88 the claims, group them into sections (one section per question the data89 answers), then lay the spine before any evidence slide — `l-cover` first,90 `l-agenda` second, an `l-section` divider before each section when there are91 two or more, and an `l-statement` last carrying the recap and the ask. Only92 then choose a layout per claim. The reason the spine goes down first is that93 scaffolding added at the end is scaffolding that gets forgotten: the same94 findings would otherwise produce a deck with an agenda one run and none the95 next. The template's eighteen example slides are a catalogue of the available96 layouts, never a running order.)*97 Before writing markup, answer: what is the dominant shape of this analysis98 (one trend / a head-to-head comparison / a ranking / a funnel / a99 distribution / parallel equal measures / geography)? Is there genuinely one100 panel that is the reason the page exists? The answers pick the opening row —101 worked derivations for each shape are in `references/layout.md` § Compose the102 grid from the findings.103104 Two checks before you move on. **A hero must be earned**: `w8 h2` goes to a105 panel only when one finding dominates; co-equal measures get equal cells, and106 promoting one is a claim the data doesn't make. And **if your top row came out107 as a wide line chart plus a donut plus a small panel, verify that it came from108 the data** — that is the shape this skill falls into by reflex, and it is109 right only when a single trend really does lead and composition really is the110 second thing the reader needs.111112 One sizing rule the grid doesn't enforce for you: **tables size themselves.**113 `table`, `reportTable` and `barInsightTable` are as tall as their rows, so114 they go in a content-sized `<div class="bento flow">` row, never in a fixed115 cell or an `.h2`. A fixed cell leaves a blank band under the last row. Give a116 `reportTable` chart column a `width` that fits its data, and choose the117 smallest span that holds the table (`layout.md` § Tables size themselves).1181195. **Choose a chart per panel** using `references/chart-selection.md`, then write120 the config against `references/chart-api.md` (the full charts-lib API: every121 factory, option, and theme token). Read that file before writing chart code —122 don't guess option names.123124 For a single fact about one engine — what it refuses, whether it self-sizes,125 how many grid tracks it wants, its minimum readable size — read126 `assets/charts-lib/charts.manifest.json` instead of the whole API file. It is127 the same index the library carries as `Charts.meta`, kept in step with the128 code by the build, and it also holds the shared `plotBox` and `grid` rules.129130 **Check the chart's input contract first** (`chart-selection.md` § Input131 contract). Each engine accepts a particular kind of x and y, and a mismatch132 is a broken panel rather than a style choice. The one that bites most often:133 a line chart needs an *ordered* x — dates, numbers, or labels that carry134 their own rising sequence (`'Jan'…'Dec'`, `'Q1'…'Q4'`, `'Week 1'…'Week 12'`).135 Named categories (regions, browsers, departments) render an error panel136 instead of a chart; use `Charts.column` when x is a name.137138 Two more references come in at this step when they apply: write the panel139 titles against `references/narrative.md` (where a finding goes, and how to140 state it without editorializing), and if the page has a filter or dropdown,141 read `references/controls.md` before wiring it.142143 **Check any claim that does arithmetic.** Titles reach for comparative144 shapes — "more than the next two combined", "half of all", "double the145 nearest" — because they are satisfying to write, and they are the easiest146 sentences in a deck to get wrong: the shape sounds right while the numbers147 say otherwise, and nobody re-adds the column before presenting. Add up the148 numbers you are claiming about before you write the sentence, and if the149 arithmetic does not hold, state the comparison that does. A chart that150 contradicts its own title is worse than a chart with a dull title.151152 **When a panel marks something up** — an intervention, a projection, a153 target, a labelled anomaly — read `references/annotation.md` for the cue and154 its mechanics. Colour and stroke are per-series on a line, so actual-vs-155 forecast is two series, not one styled midway.1566. **If the user pointed at a brand** — their site, a stylesheet, a screenshot, a157 set of hex codes — recolor to match, and change nothing else. Read158 `references/theming.md` and run the bundled extractor:159 ```bash160 node <skill-dir>/scripts/extract-theme.js <their-css-or-html>161 ```162 It harvests the design's canvas, series hue, and any color reserved for a163 utility role, then runs the same OKLCH recipe described in `theming.md`:164 paper, greyscale ink, a seven-step series ramp, and `accent`/`annotation`/165 `counter` — taken from the design where it has a color that fits the role,166 derived by hue rotation where it doesn't. Apply its `Charts.applyPalette`167 block once, before the first chart call — hand it the palette and let168 `theme.js` re-derive the roles; assigning roles one by one leaves tiles,169 tooltips and dimmed legend keys on the old colours. Fix anything it marks FAIL rather than170 shipping it. **Check the series hue it picked** against what you know the171 brand's colour to be: the script ranks by how the CSS uses a colour, which172 usually finds the brand colour and occasionally promotes a heavily-used173 secondary instead. The report also names the design's typeface — reported,174 not applied, unless the page can genuinely load the face (see § One design175 system, only the colors change).176177 **If all you have is one brand color** — a single hex, no CSS to harvest —178 run the same recipe with nothing observed:179 ```bash180 node <skill-dir>/scripts/generate-theme.js '#2323FF'181 ```1827. **Verify before reporting done.** The page still has its `charts-lib/…`183 placeholders at this point, so to *run* it you need the library beside it184 temporarily. Stage it — step 8 removes it again:185 ```bash186 node <skill-dir>/scripts/finalize.js index.html --stage187 ```188 Then use the strongest check your environment supports:189 - *Browser tooling available* — open the file, read the console for errors,190 and screenshot it to confirm layout. (In Claude Code: `preview_start`, then191 `read_console_messages` and a screenshot. Serve over a local HTTP server192 rather than `file://` so the scripts execute.)193 - *No browser tooling* — run the bundled checker and fix what it reports:194 ```bash195 node <skill-dir>/scripts/check-page.js index.html196 ```197 It catches the four failures that do not throw and so survive a198 confident-looking build: a panel whose chart was never wired (an empty199 box), a line over unordered categories (an error panel *inside* the200 chart), a page still pointing at `charts-lib/`, and anything else that201 reaches the network. Each one reads as a styling bug rather than the202 missing wiring it is. Exit code is non-zero when something fails, so it203 also works as a gate. Run it here without `--final` — the page is not204 inlined yet, and mid-build that is simply where you are. (Step 8 runs it205 for you either way; running it now just shortens the loop.)206 Either way, fix any panel that renders empty or overflows its cell first. A207 panel reading *"Line charts need a continuous or temporal x-axis"* is the208 input-contract failure above — change the chart type or the x values, don't209 restyle it.210211 **If you built a deck, check it on paper too.** It is made to be handed212 round as a PDF, and that path has failures the screen never shows: print to213 PDF (or open the print preview) and confirm one slide per sheet, nothing214 crossing a page edge, and the dark slides still dark. A slide whose content215 outgrew its frame is silently cropped there rather than scrolled.216217 **If the page has any control, test it.** Change each dropdown to a218 non-default value and confirm — with a screenshot or by reading the rendered219 text back — that the affected charts redraw *and* that any action title220 recomputed with them. An untested filter is usually a broken filter.2218. **Fold the library into the page, and ship one file.** A dashboard outlives222 the folder it was written in — it gets emailed, dropped in Slack, committed223 to a wiki, opened from Downloads. A page that loads `charts-lib/charts.js`224 from a sibling folder renders as an empty grid the moment it travels alone,225 and it fails *silently*: the markup, the headings and the KPI numbers are all226 there, so it looks like a styling bug rather than a missing dependency. So227 the last build step replaces the three placeholder tags with the library's228 own contents. One command does the whole ending — checks the page as built,229 inlines the library, removes the staged copy, then re-checks with `--final`,230 which this time *insists* the page is standalone:231 ```bash232 node <skill-dir>/scripts/finalize.js index.html233 ```234 It stops before inlining if the build checks fail, since inlining a broken235 page only makes it a bigger broken page, and its exit code is the gate: a236 non-zero exit means you are not done. It removes a sibling `charts-lib/`237 only when that folder holds exactly the three files it staged, so a folder238 of your own that happens to share the name survives.239 The result is one ~590 KB HTML file that opens over `file://` with no server,240 no network, and no sibling folder. Some rules that follow from that:241 - **Never reintroduce a `<script src>` or `<link href>` to anything.** No CDN242 for a chart library, a font, an icon set, or a CSS reset — an offline243 reader, a locked-down laptop, or an air-gapped review gets a broken page.244 Web fonts are the common slip: name the family in the CSS stack and let it245 fall back to the system face, which is what the template already does.246 - **Images go in as `data:` URIs** or not at all.247 - **The library is inlined verbatim.** Don't minify it, don't strip the parts248 you think a page doesn't use, and don't hand-edit the inlined copy — a249 bug fixed in the page instead of in `assets/charts-lib/` is lost on the250 next build. Rerunning `finalize.js` on an already-inlined file is a251 harmless no-op, so it is safe to re-run after edits.252 - **If the user explicitly asks for the split form** — they're checking the253 page into a repo beside other pages that share the library, say — skip254 `finalize.js` and keep the staged `charts-lib/` next to the output, with255 the placeholder tags as the real references. Check that page with256 `scripts/check-page.js index.html` (no `--final`, which would fail it for257 the references it is supposed to have). That is the exception, not the258 default.259260## Rules that keep output good261262- One idea per panel. A panel whose title needs "and" is two panels.263- Lead with the finding that matters most: if one trend is the reason the page264 exists, give it the wide top-left cell (`w8 h2`). If nothing dominates — three265 equally important measures, say — don't manufacture a hero; equal panels are266 the honest layout. The rest of the grid follows the same logic: the shape of267 the analysis picks the rows, and a layout reused from the last page is a layout268 that describes the last page's data (`references/layout.md`).269- Every panel gets a `title` and a `subtitle` that states units and scope270 ("USD thousands · Q4 2025"). Put units in `yAxis.suffix` and271 `tooltip.valueSuffix` too.272- A projection is never drawn in the same stroke as a measurement: dash the273 forecast (or `scenario:'forecast'` on bars) and name the notation in the274 subtitle. See `references/annotation.md`.275- Match the chart to what the data *is*, not to what looks good: a line only276 where x is time or a number, a donut/waffle only where the parts are277 non-negative and sum to one whole, a scatter only where both axes are278 measures. See `chart-selection.md` § Input contract.279- Order categorical bars by value, not alphabetically. Keep time on the x-axis280 left-to-right.281- Donuts stop being readable somewhere around six wedges — below a few percent282 the angles are indistinguishable and the reader is just reading the legend.283 Roll the tail into "Other", or use a ranked bar list if the tail is the point.284- Don't restate a series in two panels unless the second adds a new cut.285- Annotate what matters: `callouts: [{ x, text }]` on line charts for spikes,286 launches, and anomalies mentioned by the user.287288### How many charts? One per finding — no quota, no padding289290The page is not a container to fill up. Each panel should answer a question the291reader actually has, and the count falls out of the data rather than out of a292target. Ask of every panel: *what would the reader do differently after seeing293this?* If the answer is nothing, it isn't a panel.294295That cuts both ways, and both failures are common:296297- **Padding.** Given four numbers from an A/B test, the honest page is two or298 three panels and a plain statement of the lift. Filling a twelve-cell grid299 means inventing a donut of two nearly-identical sample sizes, a fabricated300 daily time series, a "by segment" split nobody measured. The moment you are301 reaching for something to chart, you have run past the end of the data — stop302 there. A small page that answers the question is a better deliverable than a303 full grid that pads it, even though the full grid looks more impressive at a304 glance.305- **Compression.** Given twenty measures that each carry a finding, don't force306 them into eight panels by stacking unrelated series onto shared axes. Let the307 page be long.308309When there are only a few panels, widen them (`w6`/`w8`/`w12`) so the grid still310reads as a designed page rather than a half-empty one — a two-panel dashboard is311two big panels, not two small panels marooned top-left.312313Reports work the same way: a figure exists because a claim in the prose needs314evidence. A section that states no claim needs no chart, and a claim the reader315will accept without proof doesn't need one either.316317### Fit the page to how it will be read318319The dashboard and report templates are tuned for someone reading at a desk.320When the user tells you otherwise — "I'm presenting this", "send it round",321"print it" — the same page fails badly in that other context. Presenting is the322case with its own template: a deck (`templates/slides.html`) is the right answer323to "I'm presenting this", not a dashboard with the type scaled up. For the other324two the fix is how much you put on the page and at what size, never a different325design system. All three cases are in `references/layout.md` § Fit the page to326how it will be read.327328### Make the chart show the finding, not just the data329330Three defaults in charts-lib are deliberately plain, and taking them as-is is331how a page ends up technically correct and useless. Override them on purpose:332333- **Emphasis.** Read the title you just wrote. If it names specific categories,334 a specific series, or a specific moment — "the top two account for 90%",335 "Direct outperformed Partner", "the drop came after the March update" — the336 chart leaves categorical mode and enters emphasis mode: the subject takes the337 accent, everything else takes `Charts.theme.muted`. A finding stated in words338 above eight identical bars is a finding the reader has to re-derive.339340 The mechanism differs by what the subject is — per-point `color` for341 categories, series `color` + `lineWidth` for one line among many, `plotBands`342 and `callouts` for a moment, a tinted `centerText` for a donut's focal wedge.343 All of them, plus the grouped-chart series-vs-cluster split, are in344 `references/chart-selection.md` § Emphasis. Three constraints hold across all345 of them: **two colors, not a rainbow** (multi-hue *and* an accent reads as no346 emphasis at all), **at most 2–3 accented items** (past that, go back to the347 full categorical palette), and **muted still has to be readable** — context348 bars are data too, which is why `muted` is derived at 3:1 against the canvas349 rather than picked for how quiet it looks.350351 **In a deck, emphasis mode is the exception and the plain ramp is the352 default.** Not a different rule — the same one, biting harder: a deck is where353 the urge to make the point is strongest, and a grey supporting bar stops354 saying anything by the third slide that has one. Write no `color` unless the355 chart's own title names the points it means.356357 Three standing rules that apply whether or not the chart is in emphasis mode:358 residual categories ("Other", "Don't know", a rolled-up tail) always take359 `muted`, since they can never be the finding; several context series take one360 identical mute rather than a ramp, so they read as a single band; and one361 emphasis per chart — an accented bar *and* a callout on that same bar is two362 competing signals, not double the emphasis.363- **Status vs. emphasis.** When a chart mixes measured, planned, and projected364 numbers, don't spend a palette color on the distinction — encode it in the365 fill with `scenario: 'plan' | 'forecast'` (outlined / hatched) and keep color366 for the finding. A projection drawn identically to a measurement is the same367 failure as inventing the number.368- **Data labels.** The library draws them in every chart type by default. Opt369 out with `dataLabels: false` where they'd collide — dense lines, many bars,370 grouped columns with 3+ series. See `references/chart-selection.md` § Data labels.371- **Geofacet variant.** `'bar'` is what you get by typing nothing, which is not372 a reason to use it three times on one page. `'heat'` when the spatial pattern373 is the point, `'gauge'` when regions are measured against a shared target.374 See `references/chart-api.md` § Geofacet.375376### If you add a control, wire it377378A dropdown that doesn't change the charts is worse than no dropdown: it reads as379a broken page, and the reader stops trusting the numbers that *are* correct. So380either add no controls at all — a static page is a perfectly good deliverable —381or wire them completely, which means the data is filtered rather than the label,382every dependent panel re-renders, and any action title recomputes from the same383filtered rows. Redraw through a helper that calls the old chart's `destroy()`384first: without it, old charts' resize observers keep repainting the unfiltered385chart on every window resize, and they pile up with each filter change. **If the page has a control, read `references/controls.md`**: it386has the `render(state)` and `draw()` pattern in full, the guards to apply before shipping387one, and the cases where small multiples beat a filter.388389### Legends go in one place390391charts-lib puts the legend at the top, under the subtitle, and shows it392automatically once a chart has two or more series or wedges. Leave it there. A393reader scanning a grid of panels learns the legend's location once; a page where394it sits above one chart, beside another and below a third makes them re-hunt for395it every time, and that hunting is the entire cost of an inconsistent layout.396397So: don't pass `legend` position options per chart, don't build legends in HTML398next to the chart, and don't hand-place colored dots in a panel's corner. If a399legend genuinely doesn't earn its space — single-series panels, or a donut whose400wedges are already labelled by callouts — turn it off with401`legend: { enabled: false }` **for every panel in that situation**, not just the402cramped one. The only sanctioned alternative is charts-lib's own403`lineLabels: 'inline'`, and if you use it on one line chart, use it on all of404them.405406### Put the finding in the title407408A chart titled "Weekly throughput by site" makes the reader do the work of409finding the point. A chart titled "Throughput fell 12% the week of the WMS410cutover" hands it to them and then proves it underneath — the insight lives in411the chart's own hierarchy, so it travels with the figure into a screenshot, a412slide, or an email. The finding goes in `title`, the units and scope stay in413`subtitle`.414415The line that keeps this from becoming editorializing is whether the chart416proves the sentence: "Billing drives 27% of all tickets" is measurable off the417chart, "Billing is a serious problem" is a verdict the reader should reach418themselves. When no single finding dominates, a plain descriptive title is the419honest choice — don't manufacture a headline.420421**Read `references/narrative.md` before writing the titles.** It has the422write-this/not-this table, the length budget per cell, and the three-way choice423between an action title, `Charts.barInsightTable`, and a soft surface card —424including the rule that stops the same sentence appearing in two of them.425426### Nothing on the page that isn't data or its labels427428- No invented narrative furniture that repeats what a chart already says: no429 "Key insight" banners, no "Executive summary" you wrote yourself, no430 highlighted takeaway strip across the top, no emoji, no "🚀".431- The header is title, one line of scope, and the reporting window. The footer is432 sources, definitions, and any honesty notes (illustrative figures, carried-433 forward panels, data-quality caveats). Nothing else belongs in either.434- Conclusions the user themselves stated ("the March spike is the thing I need to435 explain") belong on the relevant chart — as its title or a callout, in their436 framing — not restated as your own analysis in a banner.437438### One design system, only the colors change439440Every visible component follows charts-lib's design language: its type scale,441weights, spacing rhythm, stroke widths, hairlines, legend position and chart442geometry. Those proportions are what make ten different chart types read as one443family, and the page chrome inherits them so the cards don't look bolted on.444445The colors are the exception, and the only exception. When a user supplies a446brand, recolor via `Charts.applyPalette` — once, before the first factory call,447never per chart — and let the page chrome pick those same values up from the sync448block in the template. Corner radius may follow the brand too, since square vs.449rounded is a brand signature the charts themselves don't express.450451Do not introduce a second visual system on top: no custom card headers with452their own type scale, no gradient hero panels, no shadows or borders the template453doesn't already have.454455Type is the one place where copying the brand usually backfires. Most brand faces456are licensed webfonts you cannot load into a local file, and naming one in457`font-family` just falls through to a system fallback you didn't choose — worse458than keeping charts-lib's stack, which was picked to work at 11px in a chart. In459a chart the cost is not only aesthetic: the engines measure label widths against460the face they think they have, so a substituted one makes axis labels the engine461had fitted collide. And a page that reaches for a webfont stops being standalone462(step 8). Match the brand's font only when the face is genuinely available — a463system font, or a file the user supplied. `extract-theme.js` reports the464design's face and says outright whether it is loadable; when it isn't, keep the465template stack and tell the user which face you couldn't use and why. Full466method in `references/theming.md`.467468The page has exactly five kinds of component, all already in the template:469**header**, optional **KPI row**, **chart panels**, optional **soft surface470card** (`.note`), **footer**. The KPI row471exists because headline figures genuinely help — use the template's `.kpi`472markup, which is sized off the chart type scale so the tiles look like they473belong to the same page. Writing your own KPI strip with new CSS is the most474common way this page ends up looking like two designs stapled together, and it475is the thing to resist even though it feels helpful. A KPI tile is a label, a476number, and at most one line of plain context — no arrows, no red/green verdicts,477no "▲ 12% vs LY" badges.478479If you find yourself writing new CSS classes, stop and ask whether a chart panel480would carry the information better. Usually it would.481482## Output483484One HTML file, standalone — no sibling `charts-lib/` folder, no CDN tags, no485network at open time (see step 8). A deck ships the same way, and a reader turns486it into a PDF with their browser's own Print → Save as PDF: the template sets487A4 landscape, one slide per sheet. Write it to the working directory (or where488the user asked). Then surface489it however your environment does that — attach or render the file if you can (in490Claude Code: `SendUserFile` with `display: "render"`); otherwise print the491absolute path and tell the user to open it in a browser. Either way, state which492figures came from the user's data and which, if any, were illustrative.493494On the **first** page you build in a conversation, if the user didn't ask for495an editable page, end with a one-line offer of one, such as: *"Want an496editable version, so you can switch chart types and change the text or497numbers yourself without rerunning this?"* Only offer it once. Build it only498on a yes, following `references/editable.md`.499500An editable page ships as **two files**: `finalize.js` writes `<name>.html` as501the final copy (no editor, safe to share) and `<name> (working copy).html` as502the editable one. Hand over both and say in one line which is which. The503working copy shows a "Working copy" banner, a DRAFT print watermark and a504"Draft ·" tab title, so it isn't mistaken for the final version.505506## Environment notes507508Nothing in this skill requires a specific agent or vendor. It needs only the509ability to read files from this directory, write an HTML file, copy a folder,510and run Node (for `finalize.js` and the static checks). Without Node, inline511the three library files by hand — paste `charts.css` into a `<style>` and512`theme.js` then `charts.js` into `<script>` blocks, in that order, replacing the513placeholder tags. An editable page also gets `assets/page-runtime.js` in a514`<script>` block after them. Browser preview, screenshots, and file attachment are used515when available and degrade gracefully when not.