---
name: standard-metrics-surface
type: standard
description: The quality bar an internal metrics surface must clear — figure hierarchy, a target or a comparison beside every figure, small-n and early-read honesty, missing versus zero, and one hue one meaning across the page — plus the rule that decides its delivery platform by what the surface must do rather than by taste, and the binding to the global dataviz skill for anything that draws a chart. Read before building, rebuilding or scoring any dashboard, scorecard, KPI page or metrics read, so the bar is scored rather than argued and the platform is chosen once. Sits beside standard-design-system, which holds the craft bar for the system a surface is built from; convention-analytics holds only the consent posture for web analytics and is not a measurement-reporting convention. Surfaced by the 2026-10-21 Apps operator session (APP-2524, APP-2526); grown as metrics surfaces are repeated.
license: CC BY-NC-SA 4.0
---

# Metrics-surface standard

What an internal metrics surface — a dashboard, a scorecard, a KPI page, a one-off metrics read — must contain, stated as a bar the work can pass or fail. This is a *standard*, not a convention: each requirement below is derived, and a surface can be scored against it. It exists because nothing in canon told a builder what a metrics surface must *be*, so the artefact type's own advisory look and the build ticket's own acceptance criteria were the only bars in play — and a planning-performance dashboard therefore shipped clean against its type contract and against engineering QA, was ruled CLEAN, and was then judged by the Owner to be "gross, no best practice" (APP-2483, 2026-10-21; the verdict and the audit behind it are **reported** from the Apps operator session and are not re-measured here — APP-2524).

`standard-design-system` holds the craft bar for the system a surface is built from; this is the bar for the surface itself. `convention-analytics` is not the neighbour it looks like: read live on 2026-10-22, its whole scope is the consent posture chosen by site type — cookieless for personal and portfolio sites, a consent banner for commercial ones — and it carries no measurement-reporting rule of any kind (**observed**). So measurement reporting is stated here, and a surface that invents its own local rules has a canon home to put them in rather than a second dashboard to re-derive them on.

## The bar — what a metrics surface must clear

* **Hierarchy.** The surface states what it is for in one line and ranks its figures — a small number of headline figures, then the supporting detail beneath them. A row of equal tiles is a refusal to rank: every figure reads as equally important, so none is, and the reader has to do the ranking the surface was built to do. A surface whose primary figures cannot be named in a sentence fails this bar.
* **A target or a comparison beside every figure.** A number alone is not a read. Every figure carries either a target it is measured against or an explicit comparison period, and the surface says which. Where no target exists, the surface says so rather than implying one by colouring the figure — an untargeted figure is reported neutrally.
* **Status colour only against a target.** Green and red are a verdict, and a verdict needs a bar to be measured against. A delta coloured green or red where no target is declared asserts a judgement the data does not carry.
* **Small-n honesty, and it binds the visuals too.** Where the sample or the series is too short to read, the surface says so — and then the figures *obey the caveat* rather than contradicting it. A page that prints a "too soon to read" caveat and beside it draws coloured deltas off a single period, or a trend line through one or two points, has written the caveat and then overruled it in the one place the reader actually looks. A series below the minimum length the surface declares is drawn as points, not as a trend, or is not drawn.
* **Missing is not zero.** A gap in the data renders as a gap. A missing period plotted as zero invents a fall; a missing dimension counted as zero invents a denominator. The surface distinguishes *no data*, *zero*, and *not applicable*, visibly and in any export.
* **One hue, one meaning across the whole page.** A colour means one thing everywhere on the surface: one series, one category, one status. The same hue standing for different projects in neighbouring panels is the failure this rule exists to catch, and it is invisible panel by panel — it is only legible when the page is read as one page. The number of hues is held to what the eye can hold; a page needing a dozen is a page that needed grouping.
* **Methodology once.** How a figure is derived is stated once, where the reader can reach it, not repeated in every card. Repeated methodology text crowds out the figures and still leaves the reader unsure whether two cards' wording means two methods.
* **Provenance, where the surface will be cited.** A figure somebody will quote carries where it came from and when it was last refreshed. A surface whose figures cannot be traced back is a picture, not a read.

## Chart encoding is delegated — the global `dataviz` skill is the binding

Everything about how a chart is actually drawn — form choice, palette construction, mark specs, legends, axes, tooltips, stat tiles, sparklines — is held by the global `dataviz` skill, and **this standard binds it**: read `dataviz` before writing the first line of chart code, choosing chart colours, building a stat tile or laying out a dashboard. Nothing in canon pointed at it before this artefact, which is why five encoding failures reached a shipped dashboard with every other gate green.

That absence was measured rather than assumed. **Observed 2026-10-22 against the synced skills store, 174 artefacts and `manifest.json`: `grep -rFl 'dataviz'` returns 0 files.** Three fallbacks were run before calling it an absence — a case-insensitive re-run (`grep -rFil`, 0), the distinctive substrings `sparkline`, `KPI tile` and `chart colour` (0, 0, 0), and the surfacing note identifiers `APP-2524` and `APP-2526` (0 each). So the binding above is the first reference canon holds, and it is deliberately a pointer rather than a copy: a palette or a mark spec restated here would drift from the skill that owns it within a release.

What stays here rather than going to `dataviz` is only what `dataviz` cannot know — which figures matter on this estate's surfaces, what they are measured against, and where the targets live.

## Measurement reporting — the rules that are not visual

These are the honesty rules a surface is scored on independently of how it looks, and they are stated here because no other artefact holds them.

* **Declare the comparison period on the surface**, not in the build ticket. "Versus prior week", "versus the same week last quarter", "versus target" — the reader must be able to see which, because every delta on the page depends on it.
* **Declare the minimum series length** below which the surface will not draw a trend or colour a delta, and apply it uniformly. An early-read flag that is set per card is a flag that will be forgotten on the next card.
* **Say where the targets live.** A target is owned somewhere — a goal document, a mandate, a cycle commit — and the surface names that source rather than hardcoding a number nobody can trace or update.
* **Distinguish an early read from a result in the wording as well as the chrome.** "First week, directional only" is a read; a green arrow is a result.

## The platform rule — decided by what the surface must do

The delivery platform for a metrics surface had been re-argued per build — the planning view changed platform twice in two days and was re-litigated on the third (APP-2425 → APP-2483, then re-opened 2026-10-21; **reported** — APP-2526). The rule is decided here once, and it is decided by **what the surface must do**, not by which platform looks better in the moment. Three questions, in order:

1. **Must it read live data, be typed into, or hold state another reader sees?** Then it is a **deployed app**, not an artefact. An artefact that must poll, authenticate or accept input is the wrong shape for the job, and no amount of visual work fixes that.
2. **Otherwise — must each figure be traceable, re-runnable from attached data, and downloadable?** Then it is the **Dashboard artifact type**. Per-figure provenance, a sources panel, refresh from attached files and a CSV download are what that type exists to give, and they are the properties an internal metrics read is quoted on.
3. **Otherwise — is full visual control itself the deliverable, with no provenance requirement?** Then it is a **plain HTML artifact**, and the surface accepts that its figures are not individually traceable. A client-facing report or a narrative one-pager is the case that earns this; an internal read almost never is.

**The figures that were cited in the argument are reported inputs to this reasoning, not the rule.** Each is a runtime or harness premise and **none of them is verifiable from the authoring surface, where no repo and no build output is readable** — the flags below name only their own premises, and a wrong figure in one implies nothing about the others:

* That the Dashboard artifact type permits no React and no network and keeps the host toolbar chrome — **premise unverified**.
* That a plain HTML artifact needs roughly 490KB of React 18 plus Recharts UMD — **premise unverified**.
* That React 19 ships no UMD build — **premise unverified**.

The rule survives any of the three being wrong, because none of them is what it turns on: it turns on whether the surface must be live, must be traceable, or must be controlled. If a figure changes, the weight of the trade-off changes and the ordering above does not. What a build ticket must never do again is re-run the argument — it names the question this rule answers, states the answer, and spends its effort on the bar above instead.

## Scoring a surface

Score each bullet of *The bar* pass or fail, then the four measurement-reporting rules, then whether the platform matches the rule's answer for that surface's job. Report the failures with the figure or panel that fails, not as a general impression — the Owner's verdict on APP-2483 was correct and unactionable at the same time, and it became actionable only once an audit named the five specific failures.

## Guardrails

* **Never colour a delta that has no declared target**, and never draw a trend shorter than the declared minimum series length. These two produce most of what reads as "no best practice".
* **Never restate a `dataviz` rule here.** Point at the skill. A copied palette or mark spec is a second source of truth by construction.
* **Never re-argue the platform inside a build ticket.** Where the rule gives the wrong answer for a real case, change the rule here and say why; do not settle it locally and leave the next build to settle it again.
* **Never assert a platform runtime figure from this artefact.** The three above are reported and flagged, and a build that depends on one confirms it against the platform itself first.
