building-stats-pages

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

1. Inspect the user-specified data source and the existing project's manifests, routes, and frontend stack before designing.
2. Normalize scalars, dated series, and categories separately. Retain raw values, sources, retrieval times, units, and cache state.
3. 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.
4. When authoritative fields disagree, show both with a visible source-quality warning; never rewrite one silently.
5. Derive aggregates only from compatible windows. Never present a limited period as lifetime, combine unlike downloads, or attach an unscoped scalar to a release.
6. 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