Semantic grouping

Panels that belong together by meaning, laid out so the grouping is visible without a box around everything. A heading and a gap do more work than a border, and cost less ink.

npx shadcn@latest add separator card

Tokens this needs: --card, --muted-foreground, --border, --status-warn, --status-critical
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.

────────────────────────────────────────────────────────────────────────
// PanelGroups.tsx
────────────────────────────────────────────────────────────────────────

import type { ReactNode } from "react";
import { Separator } from "@/components/ui/separator";
import { cn } from "@/lib/utils";

/** One axis per page. Subsystem, signal type or audience, chosen once, so a
 *  page cannot group by service at the top and by signal further down. */
export type Axis = "subsystem" | "signal" | "audience";

export type Group = {
  /** Specific. "Misc", "Other" and "Metrics" are confessions, and they are
   *  flagged rather than silently accepted. */
  label: string;
  /** Ordered by importance, never by when they were added. */
  panels: ReactNode[];
};

type Props = {
  axis: Axis;
  groups: Group[];
  columns?: 2 | 3 | 4;
};

const SAYS_NOTHING = /^(misc|miscellaneous|other|metrics|general|stuff)$/i;
const COLS = { 2: "grid-cols-2", 3: "grid-cols-3", 4: "grid-cols-4" };

export function PanelGroups({ axis, groups, columns = 3 }: Props) {
  return (
    <div className="flex flex-col gap-5" data-axis={axis}>
      {groups.map((g) => {
        const empty = SAYS_NOTHING.test(g.label.trim());
        return (
          // A heading and a gap do the work. No box around everything, and
          // the boundary is visible without colour.
          <section key={g.label} aria-label={g.label}>
            <h3
              className={cn("text-[11px] uppercase tracking-[0.1em]", empty ? "text-status-warn" : "text-muted-foreground")}
              title={empty ? `"${g.label}" says nothing about what is inside. Name the ${axis}.` : undefined}
            >
              {g.label}
            </h3>
            <Separator className="mb-2 mt-1.5" />
            {g.panels.length > 0 ? (
              <div className={cn("grid gap-2", COLS[columns])}>{g.panels}</div>
            ) : (
              <p className="text-[11px] text-muted-foreground">Nothing here yet.</p>
            )}
          </section>
        );
      })}
    </div>
  );
}

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

import { Card } from "@/components/ui/card";
import { cn } from "@/lib/utils";
import { PanelGroups } from "./PanelGroups";

/**
 * Nine panels grouped by signal type. Traffic, errors, saturation, in that
 * order, because that is the order a person diagnosing reads them. One error
 * panel is firing and sits where a reader would look for it.
 */
const Stat = ({ label, value, critical }: { label: string; value: string; critical?: boolean }) => (
  <Card className={cn("p-3 shadow-none", critical && "border-status-critical")}>
    <p className="text-xs text-muted-foreground">{label}</p>
    <p className={cn("mt-1 text-lg font-semibold tabular-nums", critical && "text-status-critical")}>{value}</p>
  </Card>
);

export default function Demo() {
  return (
    <div className="rounded-lg border bg-card p-4">
      <PanelGroups
        axis="signal"
        groups={[
          {
            label: "Traffic",
            panels: [
              <Stat key="rps" label="Requests / s" value="1,240" />,
              <Stat key="sessions" label="Active sessions" value="8,912" />,
              <Stat key="bw" label="Egress" value="210 MB/s" />,
            ],
          },
          {
            label: "Errors",
            panels: [
              <Stat key="5xx" label="5xx rate" value="0.21%" />,
              <Stat key="4xx" label="4xx rate" value="2.4%" />,
              <Stat key="jobs" label="Failed jobs" value="3" critical />,
            ],
          },
          {
            label: "Saturation",
            panels: [
              <Stat key="cpu" label="CPU" value="61%" />,
              <Stat key="mem" label="Memory" value="78%" />,
              <Stat key="queue" label="Queue depth" value="42" />,
            ],
          },
        ]}
      />
    </div>
  );
}