| name | building-stats-pages |
| description | Use when creating or redesigning a visual statistics page, dashboard, scorecard, or usage report from numbers in a user-specified data source. |
Build Stats Pages
Overview
Build a truthful Dither Kit dashboard whose data shape chooses the presentation.
Required Output
Ship a working responsive page, not a mockup or plan. Preserve existing routing, technology choices, and project conventions. If no application exists, scaffold an appropriate frontend.
Use the numbers from the user's specified data source as authoritative. Access that source directly and use its official API when applicable. Keep tokens server-side. Label each metric's source, window, timezone when relevant, and update time.
Use Dither Kit
Read https://www.tripwire.sh/dither-kit.md. Run npx @dither-kit/cli list, install only the needed items, then inspect the vendored files and use their actual exports. Build with the real Sparkline, AreaChart/LineChart, BarChart, PieChart, and RadarChart primitives. Never imitate Dither Kit with CSS or another chart library.
Use a near-black canvas, charcoal surfaces, hairline borders, oversized tabular totals, restrained labels, and generous spacing. Use cyan or blue for the primary series, green for cyclic data, and controlled colors for categories. Prefer gradient or dotted fills with bloom along the contour. Keep text, axes, controls, and tooltips undithered.
Choose the Composition
| Available shape | Composition |
|---|
| Several KPIs, a time series, and credible breakdowns | Report: title; two sparkline KPIs; full-width trend; radar then donut below |
| One dominant time series with few breakdowns | Explorer: one full-width chart; supported controls; KPI strip below |
| Scalars or categories without a time axis | Snapshot: KPI strip; at most one comparable bar or donut; chartless when values lack shared meaning |
| Cyclic dimensions such as weekday or hour | Use radar only when the cycle is meaningful; otherwise use bars |
Ship only controls the data can honor. Rank nominal categories, but preserve meaningful ordinal source order. Put additional breakdowns in exact tables unless another chart answers a distinct question. Omit unsupported ranges, granularities, fake tabs, and decorative filters.
Handle Data Honestly
- Inspect the user-specified data source and the existing project's manifests, routes, and frontend stack before designing.
- Normalize scalars, dated series, and categories separately. Retain raw values, sources, retrieval times, units, and cache state.
- Pass only real numbers: Dither Kit can coerce nonnumeric values toward zero. Exclude unknown observations from charts and aggregates, but preserve them as missing in notices and tables. If a gap cannot render safely, label the chart “available observations” and disclose the date.
- When authoritative fields disagree, show both with a visible source-quality warning; never rewrite one silently.
- Derive aggregates only from compatible windows. Never present a limited period as lifetime, combine unlike downloads, or attach an unscoped scalar to a release.
- Reconcile totals, date boundaries, and at least three plotted values with the source.
Cover the Real Data Boundary
For local files, handle malformed, empty, partial, missing, and inconsistent data. For network sources, also handle loading, stale, rate-limited, and error states. Failed requests render as missing, never zero.
Render Gate
A green build is insufficient. Open desktop and mobile renders, confirm a clean console, and capture both screenshots. Verify keyboard operation, reduced motion, exact-value tables, and formatting for tiny, zero, negative, decimal, and huge values. Finish only when both renders work and numbers reconcile.
Common Mistakes
| Mistake | Correction |
|---|
| Recreating the dither treatment manually | Install real Dither Kit components |
| Plotting unknown or rate-limited points as zero | Exclude them; show as missing |
| Rewriting a total to match its rows | Show both with a source-quality warning |
| Trusting a green build | Render at desktop and mobile, then screenshot |
