html-report

A house style for reports that hold numbers: one reading column, wide figures, both themes, tables whose digits
line up. The files next to this one are the whole kit; nothing else needs to be installed.

Install: copy this folder to ~/.claude/skills/html-report (or your agent's skills folder). Refresh the copy after
the folder changes here.

A generator script reads report.css and replaces /*__BASE_CSS__*/ in its template with it, so the published
page stays one file.

Order of a report

The reader wants the answer first and the proof after it.

1. Header: a one-line context (what was measured · data pulled <date>), the title naming the subject, one
   paragraph on what the page covers and where the data came from. A short list of links to the sections when the
   page is long.
2. Key numbers: 4 or 8 tiles (.kpis), never a count that leaves one tile alone in a row. Each label says what
   the number counts and over which period.
3. Findings: sentences, each led by its number in bold. They are generated from the data where possible, so they
   stay true when the report is rerun.
4. Reading and advice, when asked for: what we think it means, what works, what to change, what to try. Keep it
   apart from the measured findings, and say "we think" where it is a guess.
5. Evidence: one section per question the reader has ("Does posting more often cost views?"), each with its
   charts and tables.
6. Method: the source, the period, what was left out, the definitions of every derived measure, what the data
   cannot show.

Rules

Headings. Each section opens with an h2 that says what the section answers. No small label above a heading,
no section numbers: the heading does that work. Figure titles are h3.

Numbers. Tabular figures everywhere (the base sets it). Right-align number columns (th.n, td.n). Round to
what the data supports. Write a unit or % on the number, not only in the header. Define each derived measure the
first time it appears, in the caption under the figure.

Charts. Chart.js from cdnjs, pinned (4.4.1). Take every colour from the CSS tokens and redraw when the theme
changes (the skeleton shows how), or ticks stay black on a dark page. Show shares, not counts, when the groups differ
in size. Mark an unfinished period ("2026 (to 10-10)") so a drop is not read as a decline. Hide groups too small to
trust and say so in the caption. Two y-axes only when both series share the x-axis and the caption says which is
which.

Tables. Wrap each in .tbl so it scrolls inside its box on a phone, not the page. Headers in sentence case.

Boxes. A figure sits on the page without a frame; only a block that stands apart from the flow (an interpretation
panel, the subject's profile) gets .panel. Never a box inside a box.

Colour. Accent for the main series and links; --good and --bad only for meaning (better, worse); --warm for
the second series. Change the tokens in :root and both dark blocks together to give a report its own palette.

Type. A display face for h1 and h2 only, a sans for the text, a mono for numbers in tables and tiles. Running
text stays under about 70 characters a line.

Copy. Plain sentences. Name things the way the reader does. A finding says what was measured and how much; the
advice says what to do.

Privacy. A report about people's activity counts them and never names them. The page source holds all of the
data the script embeds, not only what is shown, so leave names out of the embedded data too.

Before you publish

1. Run check page.html and look at the four screenshots once: overflow on the phone, unreadable chart text in
   dark, a tile alone in a row, a caption missing.
2. Fix everything you saw in one pass. Do not loop.
3. As a Claude artifact: publish the HTML file. It must stay one file, with fonts from Google Fonts and scripts from
   cdnjs only.