Semantic status color

status.tsThe closed set. A fifth status cannot be invented at a call site.Copy

import type { LucideIcon } from "lucide-react";
import { AlertTriangle, CheckCircle2, CircleHelp, OctagonAlert } from "lucide-react";

/**
 * The closed set.
 *
 * Adding a state means changing this union, which is the whole point: the
 * compiler refuses anything that is not one of these four, so a fifth status
 * cannot quietly appear at a call site six months from now. "How many states,
 * and is the set closed and written down?" stops being a review question.
 */
export const STATUSES = ["nominal", "warn", "critical", "unknown"] as const;
export type Status = (typeof STATUSES)[number];

/**
 * Every state carries a non-colour signal.
 *
 * This makes "is there a non-colour signal for every state" structural rather
 * than advisory—there is no way to render a status without also rendering its
 * icon and its label, because the component reads both from here.
 *
 * `unknown` is deliberately not a quiet success. No data and healthy are
 * different answers and they must not look alike.
 */
export const STATUS_META: Record<Status, { label: string; Icon: LucideIcon }> = {
  nominal: { label: "Nominal", Icon: CheckCircle2 },
  warn: { label: "Warning", Icon: AlertTriangle },
  critical: { label: "Critical", Icon: OctagonAlert },
  unknown: { label: "No data", Icon: CircleHelp },
};

StatusBadge.tsxWraps shadcn's Badge. The icon is structural, not decoration.Copy

import { cva } from "class-variance-authority";
import { cn } from "@/lib/utils";
import { STATUS_META, type Status } from "./status";

/**
 * Severity is carried by three things at once: hue, lightness, and an icon.
 * Hue alone fails in greyscale and fails for the common colour vision
 * deficiencies, both of which are checklist items on this pattern.
 *
 * The tokens are --status-*, never --destructive. shadcn's --destructive means
 * "this button deletes things"; a critical alarm is a state of the world. They
 * often land on similar reds and they are not the same semantic.
 */
const statusBadge = cva(
  "inline-flex items-center gap-1.5 rounded-md border px-2 py-0.5 text-xs font-medium",
  {
    variants: {
      status: {
        nominal: "border-status-nominal/30 bg-status-nominal/10 text-status-nominal",
        warn: "border-status-warn/30 bg-status-warn/10 text-status-warn",
        critical: "border-status-critical/40 bg-status-critical/10 text-status-critical",
        unknown: "border-status-unknown/30 bg-status-unknown/10 text-status-unknown",
      },
    },
    defaultVariants: { status: "unknown" },
  },
);

export function StatusBadge({ status, className }: { status: Status; className?: string }) {
  const { label, Icon } = STATUS_META[status];
  return (
    <span className={cn(statusBadge({ status }), className)}>
      <Icon aria-hidden="true" className="size-3.5 shrink-0" />
      {label}
    </span>
  );
}

demo.tsxHow it is called: the four values from STATUSES, each beside the rule that fires it.Copy

import { STATUSES } from "./status";
import { StatusBadge } from "./StatusBadge";

/** The closed set, each value beside the rule that fires it. */
const FIRES_WHEN = {
  nominal: "p95 under 300ms",
  warn: "300ms to 800ms",
  critical: "over 800ms",
  unknown: "no sample for 5m",
} as const;

export default function Demo() {
  return (
    <div className="w-[360px] rounded-lg border bg-card p-4">
      <div className="flex items-baseline justify-between border-b pb-2 text-[11px] uppercase tracking-wide text-muted-foreground">
        <span>State</span><span>Fires when</span>
      </div>
      <ul className="mt-1">
        {STATUSES.map((s) => (
          <li key={s} className="flex items-center justify-between gap-3 py-2 text-xs">
            <StatusBadge status={s} />
            <span className="tabular-nums text-muted-foreground">{FIRES_WHEN[s]}</span>
          </li>
        ))}
      </ul>
    </div>
  );
}