Template — Dashboard page

Status: v0.1.0 — Draft. Promoted from the KDS × gov.br Design System gap analysis (tools/design-gen/docs/govbr-ds-gap-analysis.md, GVB-18). Source: gov.br Padrão Digital transactional dashboard template.

R1 — When to use (vs report / data-table)

• Dashboard (this): an at-a-glance overview — KPIs + charts, read first, mixed widget types, drill-down to detail. Refreshes to show "current state".
• Report page (specs/patterns/report-page.kmd): a parameterized, exportable output — pick filters, run, get a tabular/graphical result to read or export. More document than console.
• Admin data table (specs/patterns/admin-data-table.kmd): the working list for a single entity (sort/filter/bulk-act) — a dashboard links to it, it is not the dashboard.

R2 — Layout order

Top to bottom:

1. Page header — title + the scope filters (R4).
2. Metric cards (R3) — a row of KPIs, most important first.
3. Chart/table grid (R5) — the supporting detail, in a responsive grid.

Keep the highest-value signal above the fold; secondary widgets below.

R3 — Metric cards (KPIs)

• Each card shows one metric: a large value, a label, and — where it helps — a delta vs the prior period (with direction, not color alone) and a sparkline. Cap the row to a scannable few.
• A card is optionally a drill-down: clicking it opens the detail (a filtered data table or report). If clickable, it is a real link/button.
• The value has units and formatting appropriate to locale (R7); long values truncate per specs/patterns/content-overflow.kmd.

R4 — Filters scope the whole page

• A shared filter/date-range bar scopes every widget on the page consistently — changing the range updates cards and charts together.
• The active scope is always visible (chips/summary) and resettable. The scope may persist in the URL so a view is shareable/bookmarkable.
• Default to a sensible range (e.g. last 30 days), never an unbounded "all time" that is slow and meaningless.

R5 — Widget states (per widget, not per page)

• Each widget owns its loading / empty / error state independently — one slow or failed widget must not blank the whole page. Use skeletons while loading.
• Empty widgets use an specs/patterns/empty-state.kmd message ("No data for this range"), not a blank box or a zero that looks like real data.
• A widget error shows a scoped, retryable message; the rest of the dashboard stays usable.

R6 — Charts

• Charts are labeled (title, axes, units, legend) and never rely on color alone to distinguish series (pattern/label/shape too). Provide the underlying values to assistive tech (an accessible table or summary behind the chart).
• Respect reduced-motion for animated transitions.

R7 — Accessibility & i18n

• The page is a landmarked structure with a real <h1>; cards and widgets have headings and a logical tab order.
• Numbers, dates, and currencies format per locale; deltas convey direction with icon + text, not color alone.
• All chrome (titles, card labels, filter labels, empty/error copy) is translatable per specs/i18n/contract.kmd.

Não-escopo

• The editing/CRUD surfaces a card drills into (specs/patterns/crud-page.kmd).
• Parameterized exportable reports (specs/patterns/report-page.kmd).
• The chart component library internals.
• Real-time streaming/push semantics (an app-behavior concern).