Layout primitives

Responsive grid

<forma-responsive-grid>

Auto-fitting composition grid with optional visual spans that collapse without changing source order.

Authoring tag
<forma-responsive-grid>
Behavior owner
Application content
Canonical source
patterns/responsive-grid.html

Purpose

The responsive grid is an auto-fit grid for composing a view from regions of unequal importance. Items fill equal columns sized by a minimum track, and forma-span-2 or forma-span-full let a region take more width when there is room. Emphasis is expressed by space, never by moving the region: the DOM order stays the reading order, and the spans collapse to full width on narrow screens. The application decides which regions exist and which one is emphasized; Forma only places them.

Use when

  • A summary view mixes one primary region with several supporting regions of equal weight.
  • A region needs more width on large screens, such as a chart or a long table, while the rest stay in columns.
  • The layout must work unchanged in a full page and in a narrower workspace pane.

Avoid when

  • All items are equal peers: the simpler Grid is enough.
  • The layout is an editorial composition with a fixed rhythm: use Mosaic.
  • One task should dominate and supporting context should sit beside it: use Priority stack or Focus stage.
  • The emphasis means something in the domain (for example the most severe incident): state it in text and order, not only in span.

Behavior to know

  • Columns come from repeat(auto-fit, minmax(min(100%, var(--forma-responsive-grid-min)), 1fr)).
  • Direct children get min-inline-size: 0, so long content wraps inside its track.
  • forma-span-2 and forma-span-full are general grid helpers: they also work in Grid and other grid containers.

Basic example

The smallest correct markup: the canonical pattern from patterns/responsive-grid.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal responsive grid

Rendered from the canonical pattern file.

Priority summary

A priority region may span columns without changing source order.

Evidence

Supporting information.

Actions

Related actions remain reachable.

HTML · Minimal responsive grid Raw HTML for HTML · Minimal responsive grid
<forma-responsive-grid class="forma-component-tag">
<section class="forma-responsive-grid" aria-label="Responsive summary grid">
  <article class="forma-surface forma-span-2"><h2>Priority summary</h2><p>A priority region may span columns without changing source order.</p></article>
  <article class="forma-surface"><h2>Evidence</h2><p>Supporting information.</p></article>
  <article class="forma-surface"><h2>Actions</h2><p>Related actions remain reachable.</p></article>
</section>
</forma-responsive-grid>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Operations overview

A primary incident summary spans two columns; supporting regions fill the remaining tracks, and a full-width activity log closes the view. Source order is summary, on-call, deployments, activity.

Open incident: checkout latency

p95 latency is 2.4 s against an 800 ms objective since 09:12 UTC. Payments team is investigating a database lock.

On call

Mateo Alvarez until 18:00 UTC.

Deployments

3 today, 1 rolled back.

Recent activity

09:40 Rollback of payments-api 7.3.1 completed. 09:18 Incident declared. 09:12 Latency alert fired.

HTML · Operations overview Raw HTML for HTML · Operations overview
<forma-responsive-grid class="forma-component-tag">
  <section class="forma-responsive-grid" aria-label="Operations overview">
    <article class="forma-surface forma-span-2" aria-labelledby="responsive-grid-operations-overview-incident">
      <h2 id="responsive-grid-operations-overview-incident">Open incident: checkout latency</h2>
      <p>p95 latency is 2.4 s against an 800 ms objective since 09:12 UTC. Payments team is investigating a database lock.</p>
    </article>
    <article class="forma-surface" aria-labelledby="responsive-grid-operations-overview-oncall">
      <h2 id="responsive-grid-operations-overview-oncall">On call</h2>
      <p>Mateo Alvarez until 18:00 UTC.</p>
    </article>
    <article class="forma-surface" aria-labelledby="responsive-grid-operations-overview-deploys">
      <h2 id="responsive-grid-operations-overview-deploys">Deployments</h2>
      <p>3 today, 1 rolled back.</p>
    </article>
    <article class="forma-surface forma-span-full" aria-labelledby="responsive-grid-operations-overview-activity">
      <h2 id="responsive-grid-operations-overview-activity">Recent activity</h2>
      <p>09:40 Rollback of payments-api 7.3.1 completed. 09:18 Incident declared. 09:12 Latency alert fired.</p>
    </article>
  </section>
</forma-responsive-grid>

Click or tap the code once to select all of it, then copy.

Scenario

Compact report tiles

A report section with a 12rem minimum track and data-density="compact". More tiles fit per row and the gap tightens; the full-width note still spans the row at every width.

Revenue
$184,200
New accounts
312
Churned
14
Support tickets
1,048

Figures are provisional until the ledger closes on 5 October.

HTML · Compact report tiles Raw HTML for HTML · Compact report tiles
<forma-responsive-grid class="forma-component-tag">
  <section class="forma-responsive-grid" data-density="compact" style="--forma-responsive-grid-min: 12rem" aria-label="September report">
    <article class="forma-metric-card"><div class="forma-metric-card__label">Revenue</div><div class="forma-metric-card__value">$184,200</div></article>
    <article class="forma-metric-card"><div class="forma-metric-card__label">New accounts</div><div class="forma-metric-card__value">312</div></article>
    <article class="forma-metric-card"><div class="forma-metric-card__label">Churned</div><div class="forma-metric-card__value">14</div></article>
    <article class="forma-metric-card"><div class="forma-metric-card__label">Support tickets</div><div class="forma-metric-card__value">1,048</div></article>
    <p class="forma-span-full">Figures are provisional until the ledger closes on 5 October.</p>
  </section>
</forma-responsive-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 collapsed span

The operations layout at phone width. The two-column span collapses to full width, the minimum track becomes 100%, and every region stacks in source order.

Viewport width

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

What changes at narrow widths

  • At 48rem and below forma-span-2 becomes grid-column: 1 / -1, so the primary region never forces a second track.
  • At 30rem and below the minimum track is 100%, giving one column regardless of the configured minimum.
  • Regions stack in DOM order: the primary region is first because it is first in the source, not because of any reordering.
  • Long incident text wraps inside its region because grid children have min-inline-size: 0.
HTML · Mobile collapsed span Raw HTML for HTML · Mobile collapsed span
<forma-responsive-grid class="forma-component-tag">
  <section class="forma-responsive-grid" aria-label="Incident workspace">
    <article class="forma-surface forma-span-2" aria-labelledby="responsive-grid-mobile-collapsed-span-summary">
      <h2 id="responsive-grid-mobile-collapsed-span-summary">Checkout latency</h2>
      <p>Investigating a database lock on the orders table.</p>
    </article>
    <article class="forma-surface" aria-labelledby="responsive-grid-mobile-collapsed-span-owner">
      <h2 id="responsive-grid-mobile-collapsed-span-owner">Owner</h2>
      <p>Payments team</p>
    </article>
    <article class="forma-surface" aria-labelledby="responsive-grid-mobile-collapsed-span-next">
      <h2 id="responsive-grid-mobile-collapsed-span-next">Next update</h2>
      <p><time datetime="2026-09-30T10:30Z">10:30 UTC</time></p>
    </article>
  </section>
</forma-responsive-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
data-density.forma-responsive-gridrelaxed | standard | compact | analyticalabsent (1rem gap)Contextual density posture. Sets the gap to 1.5rem, 1rem, or 0.5rem (compact and analytical). Not a data-forma-* hook.
aria-label.forma-responsive-gridstring—Names the composed region when the grid element is a section.
aria-labelledbygrid itemsid of the item heading—Names each article by its visible heading.
style.forma-responsive-grid--forma-responsive-grid-min / --forma-responsive-grid-space—Per-instance override of the minimum track or gap.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-responsive-gridBlock class—Auto-fit grid container; its direct children get min-inline-size: 0.
[data-density]Attribute hook—Density posture. relaxed = 1.5rem, standard = 1rem, compact and analytical = 0.5rem gap; overrides --forma-responsive-grid-space.
--forma-responsive-grid-minCustom propertydefault 16remMinimum track width before a column drops. Default 16rem; forced to 100% at 30rem viewport width and below.
--forma-responsive-grid-spaceCustom propertydefault var(--forma-primitive-spacing-4, 1rem)Gap between tracks and rows. Default --forma-primitive-spacing-4 (1rem).
.forma-span-2Block class—Makes an item span two tracks. Becomes full width (1 / -1) at viewport widths of 48rem and below. Only use it where at least two tracks usually fit.
.forma-span-fullBlock class—Makes an item span every track at all widths.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through focusable content in source order. Spans never change focus order.

Form behavior

Not a form control.

States

Responsive grid states
StateHow it is expressedPresentation
Wideviewport above 48remItems fill auto-fit columns; forma-span-2 takes two tracks.
Mediumviewport at or below 48remforma-span-2 becomes full width; other items still auto-fit.
Narrowviewport at or below 30remMinimum track is 100%, so every item is full width and stacked.
Density posturedata-density attributeGap follows the posture.

Accessibility

Forma provides

  • Spans change width only; DOM, reading and focus order are never altered.
  • Children cannot force horizontal overflow because tracks are clamped and children have min-inline-size: 0.
  • Adds no roles or landmarks.

Your application supplies

  • Put the most important region first in the source; span is visual emphasis only and is not announced.
  • Give each region a heading so users can navigate by heading instead of by position.
  • State domain meaning such as severity in text; never encode it only in span or position.

Responsive behavior

  • Column count is container-driven through auto-fit, but the span collapse (48rem) and full-width minimum (30rem) are viewport media queries.
  • In a narrow pane on a wide screen, an forma-span-2 item can create an empty implicit track; use forma-span-full there or keep spans to wide regions.
  • forma-span-full spans every track at every width, useful for notes and footers of a section.
  • Long content wraps inside its track; wide tables should go inside Bounded overflow.

Motion

  • No animation: columns and spans change instantly when the width crosses a threshold.

Usage guidance

Do

  • Use at most one or two spanning regions so emphasis stays meaningful.
  • Set the minimum track from the narrowest readable width of a region's content.

Avoid

  • Using CSS order or grid placement to move a region visually; source order is the contract.
  • Spanning a region only to fill a gap; auto-fit already stretches items.

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.