Items requiring action.
Dashboard grid
<forma-dashboard-grid>
Responsive operational dashboard composition for metrics, status, and attention-first blocks.
- Authoring tag
<forma-dashboard-grid>- Category
- Workspaces and shells
- Behavior owner
- Application content
- Canonical source
patterns/dashboard-grid.html
Purpose
A dashboard grid lays out operational summary blocks, usually Metric card articles, in three equal columns that collapse to one column on phones. It is deliberately simple: the grid assigns no analytical meaning to position or size, and the order of blocks is exactly the order the application writes. Put the blocks that need attention first in the source, because that is also the order on a phone and for assistive technology.
Use when
- An overview screen summarizes several independent operational numbers or states, such as open work, overdue items and throughput.
- Each block is a self-contained summary with a label, value and a link to the detail.
- The same blocks must remain readable as a single column on a phone.
Avoid when
- Blocks have different importance that should show in size: use Mosaic with spans, or Priority stack.
- The number of columns should follow available width instead of a fixed three: use Responsive grid or Card grid.
- The content is a list of items to act on: use Work queue.
- Values need to be compared across rows and columns: use Data grid or Dense ledger.
Behavior to know
- Three equal
minmax(0, 1fr)columns with a 1rem gap; blocks never force the page wider. - One column at 40rem and below, in source order.
- Children can use the
forma-span-2andforma-span-fullutilities to span columns; they return to full width on narrow screens.
Basic example
The smallest correct markup: the canonical pattern from patterns/dashboard-grid.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal dashboard grid
Rendered from the canonical pattern file.
Currently active records.
Completed this month.
<forma-dashboard-grid class="forma-component-tag">
<section class="forma-dashboard-grid" aria-label="Operational dashboard">
<article class="forma-metric-card"><div class="forma-metric-card__label">Needs attention</div><div class="forma-metric-card__value">7</div><p>Items requiring action.</p></article>
<article class="forma-metric-card"><div class="forma-metric-card__label">Open work</div><div class="forma-metric-card__value">18</div><p>Currently active records.</p></article>
<article class="forma-metric-card"><div class="forma-metric-card__label">Completed</div><div class="forma-metric-card__value">42</div><p>Completed this month.</p></article>
</section>
</forma-dashboard-grid>
Click or tap the code once to select all of it, then copy.
Examples
Attention-first operations overview
The blocks that need action come first in source order and carry text status with a symbol, not only color. A full-width summary spans the grid with forma-span-full.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
Accounts receivable · October
Needs action
Review overdue invoicesAwaiting customer
Open disputesOn track
<forma-dashboard-grid class="forma-component-tag">
<section class="forma-dashboard-grid" aria-labelledby="dashboard-grid-attention-first-title">
<h2 class="forma-span-full" id="dashboard-grid-attention-first-title">Accounts receivable · October</h2>
<article class="forma-metric-card" aria-labelledby="dashboard-grid-attention-first-overdue">
<div class="forma-metric-card__label" id="dashboard-grid-attention-first-overdue">Overdue invoices</div>
<div class="forma-metric-card__value">12</div>
<p><span class="forma-status-lozenge" data-state="attention">Needs action</span></p>
<a href="#dashboard-grid-attention-first-overdue-list">Review overdue invoices</a>
</article>
<article class="forma-metric-card" aria-labelledby="dashboard-grid-attention-first-disputed">
<div class="forma-metric-card__label" id="dashboard-grid-attention-first-disputed">Disputed</div>
<div class="forma-metric-card__value">3</div>
<p><span class="forma-status-lozenge" data-state="blocked">Awaiting customer</span></p>
<a href="#dashboard-grid-attention-first-disputed-list">Open disputes</a>
</article>
<article class="forma-metric-card" aria-labelledby="dashboard-grid-attention-first-collected">
<div class="forma-metric-card__label" id="dashboard-grid-attention-first-collected">Collected this month</div>
<div class="forma-metric-card__value">$184,200</div>
<p><span class="forma-status-lozenge" data-state="ok">On track</span></p>
</article>
</section>
</forma-dashboard-grid>
Click or tap the code once to select all of it, then copy.
Unavailable and stale values
When a source is unavailable the block keeps its place and says so, instead of showing zero. A wider block uses forma-span-2 for a short explanation of the stale data.
Updated 2 minutes ago.
Unavailable The inventory service has not responded since 09:40. Figures will return when it reconnects.
Stale Last refreshed 3 hours ago.
<forma-dashboard-grid class="forma-component-tag">
<section class="forma-dashboard-grid" aria-label="Warehouse status">
<article class="forma-metric-card">
<div class="forma-metric-card__label">Orders picked today</div>
<div class="forma-metric-card__value">1,284</div>
<p>Updated 2 minutes ago.</p>
</article>
<article class="forma-metric-card forma-span-2">
<div class="forma-metric-card__label">Inventory on hand</div>
<div class="forma-metric-card__value">—</div>
<p><span class="forma-status-lozenge" data-state="unknown">Unavailable</span> The inventory service has not responded since 09:40. Figures will return when it reconnects.</p>
</article>
<article class="forma-metric-card">
<div class="forma-metric-card__label">Late shipments</div>
<div class="forma-metric-card__value">7</div>
<p><span class="forma-status-lozenge" data-state="unknown">Stale</span> Last refreshed 3 hours ago.</p>
</article>
</section>
</forma-dashboard-grid>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile single column
At phone width every block takes the full width in source order, so the attention block written first is also seen first.
What changes at narrow widths
- At 40rem and below the grid is one
1frcolumn;forma-span-2andforma-span-fullchildren simply fill that column. - Order is the source order. Nothing is reordered by importance, so write attention blocks first.
- Large values such as currency amounts wrap rather than overflow because every block can shrink to the viewport.
- Links inside metric cards are ordinary inline links; give them a comfortable touch height in application CSS or make the whole label a single, clearly named link.
<forma-dashboard-grid class="forma-component-tag">
<section class="forma-dashboard-grid" aria-label="On-call summary">
<article class="forma-metric-card">
<div class="forma-metric-card__label">Open incidents</div>
<div class="forma-metric-card__value">2</div>
<p><span class="forma-status-lozenge" data-state="attention">1 unacknowledged</span></p>
</article>
<article class="forma-metric-card">
<div class="forma-metric-card__label">Pages this week</div>
<div class="forma-metric-card__value">9</div>
</article>
<article class="forma-metric-card">
<div class="forma-metric-card__label">Mean time to acknowledge</div>
<div class="forma-metric-card__value">4 min</div>
</article>
</section>
</forma-dashboard-grid>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
aria-label | root section | string | — | Names the dashboard region when it has no visible heading. |
aria-labelledby | root section, metric article | id of a visible heading or label | — | Names the region or an individual block by its visible text. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-dashboard-grid | Block class | — | Root grid: three equal columns with a 1rem gap; one column at 40rem and below. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through links in the blocks in source order. The grid adds no keyboard behavior. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Three columns | viewport wider than 40rem | Equal columns; blocks flow row by row in source order. |
| One column | @media (max-width: 40rem) | Full-width blocks stacked in source order. |
Accessibility
Forma provides
- Keeps visual order identical to source order at every width.
- Lets blocks shrink so values and descriptions reflow at 320px and 400% zoom.
Your application supplies
- Order blocks by what users need first, and do not rely on position to express priority or severity.
- Give each block a label and express status as text (for example with Status lozenge), not only color.
- Show unknown, unavailable or stale values explicitly instead of zero or blank.
- Name the dashboard region with a heading.
Responsive behavior
- Above 40rem:
repeat(3, minmax(0, 1fr)). Between about 40rem and 60rem each column is narrow, so keep labels and values short or use Responsive grid instead. - At 40rem and below: a single column.
- The column count is fixed and viewport-based; a dashboard inside a narrow container still gets three columns above 40rem viewport width.
Motion
- No animation: blocks reflow instantly at the breakpoint. Value changes inside blocks are the concern of components such as Metric value change.
Usage guidance
Do
- Link each block to the detail it summarizes.
- Keep a stable block order between visits so people can find numbers by habit.
Avoid
- Encoding meaning in position, such as putting the worst metric top-left and expecting users to infer severity.
- Filling the grid with more than about six blocks; group the rest into sections.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.