Metric targets

This is the dashboard knowing what good is. A target turns a number into a judgement, which means the target needs an owner and a date on it or nobody can say whether missing it matters.

npx shadcn@latest add card progress

Tokens this needs: --background, --card, --card-foreground, --muted, --muted-foreground, --border, --status-warn, --status-critical, --chart-1
The status, chart, scale, state and direction names are an extension,
not a rename. shadcn has --destructive and five --chart-* and nothing
else in this territory.

────────────────────────────────────────────────────────────────────────
// MetricTarget.tsx
────────────────────────────────────────────────────────────────────────

import { Card } from "@/components/ui/card";
import { Progress } from "@/components/ui/progress";

/**
 * A target is a commitment with provenance, and the provenance is the type.
 * Owner and review date are required because a target with no name cannot
 * be revised, only ignored, and an unreviewed one is wrong within a year and
 * still colouring panels. Panels take a Target; they never retype the number.
 */
export type Target = {
  name: string;
  /** The objective, as a fraction: 0.999 for 99.9%. */
  objective: number;
  /** What the objective is a fraction of: "requests", "checkouts". */
  of: string;
  /** How the indicator is computed, so the reasoning is reachable from the panel. */
  measuredAs: string;
  owner: string;
  reviewDue: Date;
  /** What draws or fires on this target. Stored once, referenced from here. */
  referencedBy: string[];
};

const DAY = 86_400_000;
const pct = (f: number) => `${+(f * 100).toFixed(2)}%`;

function review(due: Date, now: Date) {
  const days = Math.ceil((due.getTime() - now.getTime()) / DAY);
  if (days < 0) return { text: `overdue by ${-days} days`, cls: "text-status-critical" };
  const text = days >= 14 ? `due in ${Math.round(days / 7)} weeks` : `due in ${days} days`;
  return { text, cls: days <= 30 ? "text-status-warn" : "text-card-foreground" };
}

export function TargetCard({ target, now, onOpen }: { target: Target; now: Date; onOpen?: (t: Target) => void }) {
  const r = review(target.reviewDue, now);
  return (
    <Card className="p-4">
      <p className="border-b pb-2 text-[11px] uppercase tracking-wide text-muted-foreground">{target.name}</p>
      <dl className="mt-3 grid grid-cols-[84px_1fr] gap-x-3 gap-y-2.5 text-xs">
        <dt className="text-muted-foreground">objective</dt><dd className="m-0 tabular-nums text-card-foreground">{pct(target.objective)} of {target.of}</dd>
        <dt className="text-muted-foreground">measured as</dt><dd className="m-0 text-card-foreground">{target.measuredAs}</dd>
        <dt className="text-muted-foreground">owner</dt><dd className="m-0 text-card-foreground">{target.owner}</dd>
        <dt className="text-muted-foreground">reviewed</dt><dd className={`m-0 ${r.cls}`}>{r.text}</dd>
      </dl>
      <p className="mt-3 border-t pt-2 text-[11px] text-muted-foreground">used by</p>
      <ul className="mt-1 flex flex-wrap gap-1.5 text-[11px]">
        {target.referencedBy.map((ref) => (
          <li key={ref}>
            <button type="button" onClick={onOpen && (() => onOpen(target))} className="rounded-[2px] border px-2 py-0.5 text-card-foreground">{ref}</button>
          </li>
        ))}
      </ul>
    </Card>
  );
}

/**
 * The budget is what makes the target usable on a Tuesday. It converts the
 * pass/fail into a rate: how much of the permitted failure is spent, against
 * how much of the period has elapsed.
 */
export function budget(target: Target, period: { start: Date; end: Date }, errors: number, total: number, now: Date) {
  const allowed = (1 - target.objective) * total;
  const left = Math.max(0, 1 - errors / allowed);
  const elapsed = (now.getTime() - period.start.getTime()) / (period.end.getTime() - period.start.getTime());
  const daysToGo = Math.ceil((period.end.getTime() - now.getTime()) / DAY);
  return { left, expectedLeft: 1 - elapsed, daysToGo, fast: left < 1 - elapsed };
}

export function ErrorBudget({ target, period, errors, total, now }: {
  target: Target;
  /** The period the budget is spread over, usually the quarter. */
  period: { start: Date; end: Date };
  errors: number;
  total: number;
  now: Date;
}) {
  const b = budget(target, period, errors, total, now);
  return (
    <Card className="bg-muted p-4">
      <p className="border-b pb-2 text-[11px] uppercase tracking-wide text-muted-foreground">Error budget</p>
      <p className="mt-3 text-3xl font-medium tabular-nums text-card-foreground">{Math.round(b.left * 100)}%</p>
      <p className="text-[11px] tabular-nums text-muted-foreground">left, {b.daysToGo} days to go</p>
      <div className="relative mt-3">
        <Progress value={b.left * 100} aria-label="error budget left" className="h-3 rounded-[2px] bg-background [&>div]:bg-chart-1" />
        {/* Where the budget would be if it were spent evenly over the period. */}
        <span aria-hidden="true" className="absolute -top-1 h-5 w-px bg-status-warn" style={{ left: `${b.expectedLeft * 100}%` }} />
      </div>
      <p className={`mt-2 text-[11px] ${b.fast ? "text-status-warn" : "text-muted-foreground"}`}>
        {b.fast ? "burning faster than the quarter allows" : "on pace for the quarter"}
      </p>
    </Card>
  );
}

────────────────────────────────────────────────────────────────────────
// demo.tsx
────────────────────────────────────────────────────────────────────────

import { ErrorBudget, TargetCard, type Target } from "./MetricTarget";

/**
 * One target, stored once, drawn twice: the card that names it and the
 * budget derived from it. Fifty days into the quarter, 62% of the permitted
 * failures are spent, so the budget is burning faster than the period allows.
 */
const NOW = new Date("2026-08-20T09:00:00Z");
const Q3 = { start: new Date("2026-07-01T00:00:00Z"), end: new Date("2026-09-30T00:00:00Z") };

const AVAILABILITY: Target = {
  name: "Checkout availability",
  objective: 0.999,
  of: "requests",
  measuredAs: "non-5xx / total, 28d",
  owner: "payments",
  reviewDue: new Date("2026-09-10T00:00:00Z"),
  referencedBy: ["availability panel", "the wallboard tile", "the paging rule"],
};

export default function Demo() {
  return (
    <div className="grid grid-cols-[1.4fr_1fr] gap-5">
      <TargetCard target={AVAILABILITY} now={NOW} onOpen={(t) => console.log("open", t.name)} />
      <ErrorBudget target={AVAILABILITY} period={Q3} errors={25_544} total={41_200_000} now={NOW} />
    </div>
  );
}