Workspaces and shells

Dashboard grid

<forma-dashboard-grid>

Responsive operational dashboard composition for metrics, status, and attention-first blocks.

Authoring tag
<forma-dashboard-grid>
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

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-2 and forma-span-full utilities 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.

Canonical

Minimal dashboard grid

Rendered from the canonical pattern file.

Needs attention
7

Items requiring action.

Open work
18

Currently active records.

Completed
42

Completed this month.

HTML · Minimal dashboard grid Raw HTML for HTML · Minimal dashboard grid
<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

Scenario

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

Collected this month
$184,200

On track

HTML · Attention-first operations overview Raw HTML for HTML · Attention-first operations overview
<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.

Scenario

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.

Orders picked today
1,284

Updated 2 minutes ago.

Inventory on hand
—

Unavailable The inventory service has not responded since 09:40. Figures will return when it reconnects.

Late shipments
7

Stale Last refreshed 3 hours ago.

HTML · Unavailable and stale values Raw HTML for HTML · Unavailable and stale values
<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 example

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.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 40rem and below the grid is one 1fr column; forma-span-2 and forma-span-full children 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.
HTML · Mobile single column Raw HTML for HTML · Mobile single column
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelroot sectionstring—Names the dashboard region when it has no visible heading.
aria-labelledbyroot section, metric articleid of a visible heading or label—Names the region or an individual block by its visible text.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-dashboard-gridBlock class—Root grid: three equal columns with a 1rem gap; one column at 40rem and below.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through links in the blocks in source order. The grid adds no keyboard behavior.

Form behavior

Not a form control.

States

Dashboard grid states
StateHow it is expressedPresentation
Three columnsviewport wider than 40remEqual 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.