ADR-012: Maximum 12 panels per dashboard

Status: Accepted Date: 2026-04-21

Context

ADR-011 establishes that every dashboard answers one question. That rule is about purpose. Purpose alone does not prevent a dashboard from stacking twenty panels that all legitimately relate to the same question — category mix, top messages, rate over time, rate by route, rate by user class, rate by region, rate by… The on-call engineer still has to scan all of them.

There is a cognitive cap on what a human can glance at in twenty seconds. The research on dashboard design (Few, "Information Dashboard Design") puts the working-memory ceiling somewhere near 7±2 chunks; production dashboards in practice feel usable up to about a dozen. Past twelve, the eye starts missing panels. At 3am, it misses more.

We also pay a concrete cost per panel: each one is a Loki or Prometheus query on every refresh, and a dashboard with thirty panels refreshing every 30 seconds is a measurable load on the observability stack. That cost scales per dashboard × per viewer × per refresh, which adds up quickly with auto-refresh on.

Decision

A dashboard contains at most 12 panels. Grafana row containers (type: "row") do not count — they are visual grouping, not content. Stat-panel strips with four sub-cells count as one panel, not four.

The cap applies at PR review. The scaffold CLI's --validate mode and a CI check on infrastructure/grafana-templates/ both enforce it for templates. For service-specific (post-scaffold) dashboards, the service author is responsible; a platform review can cite this ADR in a PR.

A template that needs more than twelve panels has the question the dashboard answers wrong — either it's two questions, or several panels are not pulling their weight. Either is fixable without exceeding the cap.

Consequences

Panel budget forces panel quality. If every new panel costs one of twelve slots, authors pick the right signal instead of "also, here's the raw number". Dashboards that use percentile summaries (one stat panel) beat dashboards that show the raw histogram (one panel per quantile).
Splitting is the relief valve. When a dashboard wants a thirteenth panel, the path is "create a new dashboard answering a different question", not "raise the cap". This dovetails with ADR-011.
Mechanical CI check exists. jq '[.panels[] | select(.type != "row")] | length' on every dashboard file; hard fail if > 12. No taste required.
Per-service panel count goes up, not down. A service with five Tier-0 dashboards at 7–10 panels each is 40+ panels across five clean dashboards, and the engineer only looks at one dashboard at a time. That is a feature.
Incident dashboards have the tightest cap by design. platform-incident uses four panels, one per quadrant. The cap is not aspirational — the cognitive-load argument is strongest when everything else is on fire and the engineer has the least capacity.
Exceptions require amendment. A dashboard that genuinely needs 14 panels files an amendment to this ADR with the reason and the panels. To date we have no such exception; this paragraph is the escape hatch, not a policy invitation.

Alternatives considered

No hard cap, reviewer discretion. Relies on reviewers internalising the cognitive-load case and saying no consistently. Rejected: "one more panel won't hurt" beats taste over time. A number in an ADR is harder to erode than a feeling in a review comment.
Hard cap at 6 panels. Closer to Few's working-memory number. Rejected as too tight: splitting a coherent "service overview" into three sub-dashboards hurts the one-question rule more than a 12-panel overview does. 12 is the largest cap that still survives the 3am scan.
Cap by pixel area, not panel count. Large-but-few panels are fine; small-but-many panels overwhelm. Measured in grid cells this would be sensible. Rejected on implementation cost: jq on panel count is a one-line CI check; computing total grid area is more work than the marginal precision is worth.
Per-panel-type caps (e.g., max 3 time-series panels). More nuanced. Rejected: rules that care about panel type stop applying as new panel types land. A type-agnostic cap is durable.

Supersedes: none Superseded by: