numbers-style
Use when writing any number in prose, a table, a chart label or a KPI tile: rounding and significant figures, percent vs percentage points, relative vs absolute change, growth wording, small bases, un
SKILL.mdskills/numbers-style/SKILL.md
GitHubNumbers style
A number is read once, quickly. It must be unambiguous, no more precise than the evidence, and formatted the same way everywhere in a report.
Precision
- Two or three significant figures in prose. "€182,400" in a table; "€182,000" or "€0.18 million" in a sentence. Never more precise than the uncertainty: if the interval is ±3 pp, "24%" not "24.37%".
- Round at the end. Keep full precision through calculations; round only for display. Shares that are rounded need not sum to 100%; say so in a note rather than fudging a component.
- Consistent decimals within a column, axis or comparison.
Change
- Percentage points for differences between rates; percent for relative change. "Conversion rose 3 percentage points, from 21% to 24% (a 14% relative increase)." Never "conversion rose 3%" for that change.
- Give both levels. "from 188 to 212 orders (+13%)", not only "+13%".
- Growth from zero or a negative base is undefined. Write the levels.
- Decreases cannot exceed 100%. Use "fell to a third", not "fell 300%". Avoid "three times less".
- Small bases: counts first. "2 of 10 East-region orders were cancelled", not
"20% cancellation". When a rate on a small base must be shown, give n and
an interval (
uncertainty-display).
Units and money
- Every number has a unit, on first use in prose and in every axis label and column header.
- Currency. State whether prices include VAT (Finland's standard rate is 25.5% since 1 September 2024); state nominal vs inflation-adjusted for comparisons across years, and name the index and base year.
- Normalise to the decision. Per order, per 100 deliveries, per staff-hour, per € of ad spend; say which denominator.
- Name the average. Mean, median, or weighted mean; for skewed values (order value, lead time) prefer the median and say so.
- Percent storage. Decide whether rates are stored as fractions (0.24) or percent (24) and declare it in the unit; ieeVisualizer will not convert.
Locale
Pick one locale per report and apply it everywhere, including chart ticks.
| English report | Finnish report (fi-FI) | |
|---|---|---|
| Thousands / decimal | 12,345.6 | 12 345,6 (no-break space) |
| Currency | €12,345.60 | 12 345,60 € |
| Percent | 12.3% | 12,3 % |
| Range | 20–28% | 20–28 % |
| Date | 4 October 2026; 4 Oct | 4.10.2026 |
- Ranges with an en dash and the unit once: "20–28%"; in prose "from 20% to 28%".
- Negative numbers with a true minus sign (−4), not a hyphen.
- Large numbers: "€1.2 million" (or "€1.2m" in labels), consistent.
Time
- Name the period exactly. "ISO week 40 (28 Sep–4 Oct 2026)" or "the week to 4 October". Not "last week" in a document that will be read later.
- State the timezone for daily or weekly buckets (the business's own timezone, named, e.g. Europe/Berlin) and the data cut-off ("retrieved 5 Oct 06:00 CEST").
- Partial periods are labelled ("October to date, 1–14 Oct").
ieeVisualizer enforcement
- Units are stored as given and never converted: the
timeseriestemplate takes the y unit from the columns, reportsmixed_unitswhen drawn columns disagree andunit_override_conflictwheny_unitcontradicts a declared unit;validate()reportsaxis_unit_conflictwhen layers on one axis disagree. A missing unit is amissing_unitwarning. - Axis labels are rendered "Label (unit)".
- Datetime values are stored canonically and keep their UTC offset; the
renderer labels them in
provenance.timezone(or UTC with adatetime_displayed_in_utcwarning). - Not enforced: tick and label locale formatting, rounding in titles and captions, pp vs % wording. The skill is the guard.
Good / bad
| Bad | Good |
|---|---|
| Conversion up 3% (21% → 24%) | Conversion up 3 percentage points, to 24% |
| Revenue €182,437.18 (in a headline) | Revenue €182,000 |
| Cancellations doubled to 20% (East region) | 2 of 10 East-region orders cancelled, up from 1 of 10 |
| Avg order value €870 | Revenue per order €691 (weighted; North and South regions) |
| CPA €45 | Ad spend per paid order €45 (28-day click attribution, ex VAT) |
| Accuracy 0.71 vs 71% in the same table | 71.0% throughout |
Checklist
- Precision no finer than the uncertainty; 2–3 significant figures in prose.
- pp for rate differences, % for relative change; both levels given.
- Counts shown for small bases.
- Every number has a unit; VAT and nominal/real stated for money.
- Average named; denominator named.
- One locale applied to prose, tables and ticks.
- Periods exact, timezone stated, partial periods labelled.
Adapted in part from jamditis data-journalism (MIT) and UK Analysis Function
guidance (OGL v3.0); changed: rewritten, Finnish locale and examples added.
Sources and licences: SOURCES.md.