Dashboards / Organization and navigation / Semantic grouping

Semantic grouping

People need related panels grouped together so they can find and compare them.

Updated September 10, 2026

Problem

Panels added over time can end up beside unrelated information, forcing people to search for measures that belong together.

Solution

Group panels by a clear organizing principle, such as subsystem, signal type, or audience. Choose the principle that fits the page’s main task and apply it consistently.

Give groups specific names that describe their contents. Keep related panels close enough to compare, and use spacing or headings to separate groups.

Review the grouping as content changes. A new panel should fit the task, not simply go into the nearest available section.

Use when

A page contains enough panels that people need meaningful sections to scan it.

Don’t use when

There are six panels. Grouping six things into three groups adds ceremony and reduces the information density of every label.

Trade-offs

Every grouping favors some questions over others. Existing sections can discourage rethinking an outdated layout. Inconsistent organization across similar dashboards adds learning work.

Checklist

What is the grouping axis, and is it applied consistently down the whole page?
Would a different axis serve the primary reader better?
Does every group have a label that says something specific?
Is there a group called Misc, Other or Metrics?
Does proximity anywhere imply a relationship that does not exist?
Are groups ordered by importance, or by when they were added?
Do the same groups appear in the same order across related dashboards?
Does a new panel have an obvious home, or does it default to the last group?
Are group boundaries visible without relying on colour?
Does the grouping still make sense after the last reorganisation?

Compare

Grafana provides rows as the grouping mechanism, so a group is a labelled collapsible band, and the label is the only thing carrying the semantics. Datadog offers group widgets that nest within a page and can carry their own status, so a group is an object with state rather than only a divider. Netdata derives grouping from the collectors themselves—CPU, memory, disks, network, per application—which means the structure is generated rather than curated and is consistent across every node by construction. Honeycomb has little of this, because a board is a set of queries rather than a spatial arrangement, and the grouping question moves to which queries belong on which board.

Panel grid expresses relationships through placement. Collapsible row lets groups close. Tabs as genres separates groups at page level.

Multi-page dashboard gives larger topics their own space. Dense small-multiple layout depends on clear grouping for scanning.

Wireframe — the pattern's anatomy, not any one product's version of it

Implementation

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.

shadcn: npx shadcn@latest add separator card
Tokens: --card--muted-foreground--border--status-warn--status-critical

LightDarkCode

Traffic

Requests / s

1,240

Active sessions

8,912

Egress

210 MB/s

Errors

5xx rate

0.21%

4xx rate

2.4%

Failed jobs

Saturation

CPU

61%

Memory

78%

Queue depth

PanelGroups.tsxOne grouping axis per page, a labelled section per group, and a label that says nothing gets flagged.

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.tsxHow it is called: nine panels by signal type, traffic then errors then saturation.

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>
  );
}

What it renders. Identical markup in both panes, with only the token values changing.

Copy-paste: this implementation as plain text

Examples

Screenshots are grouped by product and include the capture date. Dashed boxes highlight this pattern. Notes appear below each screenshot and when you hover over a box.