Production · Extended localized content for verification and layout resilience
12 services, all reporting.
Staging
12 services, 1 deploying.
Development
9 services, 3 idle.
Grid
<forma-grid>
Foundation auto-fit grid that fills columns by a minimum track width and collapses to one column without media queries.
- Authoring tag
<forma-grid>- Category
- Layout primitives
- Behavior owner
- Native CSS
- Canonical source
patterns/grid.html
Purpose
The foundation grid lays out peer items in as many equal columns as fit, given a minimum track width. When the container narrows, columns drop one at a time until a single column remains; no media query is involved, so the grid reflows by the space it actually has, whether it sits in a full page, a sidebar or a dialog. It is the default choice for collections of comparable things: environments, plans, summary panels, option cards.
Use when
- A collection of peer items should align into columns and reflow by available width.
- The number of items varies with data and the column count should follow from the space, not be fixed.
- A dashboard region needs equal-weight panels that stay readable at any container width.
Avoid when
- One item needs to span columns for emphasis: use Responsive grid, which adds span helpers and narrow-screen collapse rules.
- An editorial layout needs deliberately uneven spans on a fixed four-column rhythm: use Mosaic.
- Items are metrics in an operational dashboard with its own conventions: use Dashboard grid.
- Data has rows and columns that must be compared cell by cell: use a table in Bounded overflow or Data grid.
Behavior to know
- Columns come from
repeat(auto-fit, minmax(min(100%, var(--forma-grid-min)), 1fr)), so a track is never wider than the container. - Items fill rows in source order; the grid never reorders them.
- The grid draws nothing; pair it with Surface items when each cell needs a boundary.
Basic example
The smallest correct markup: the canonical pattern from patterns/grid.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal grid
Rendered from the canonical pattern file.
Production
12 services, all reporting.
Staging
12 services, 1 deploying.
Development
9 services, 3 idle.
<forma-grid class="forma-component-tag">
<ul class="forma-grid" aria-label="Environments" role="list">
<li class="forma-surface"><h3>Production</h3><p>12 services, all reporting.</p></li>
<li class="forma-surface"><h3>Staging</h3><p>12 services, 1 deploying.</p></li>
<li class="forma-surface"><h3>Development</h3><p>9 services, 3 idle.</p></li>
</ul>
</forma-grid>
Click or tap the code once to select all of it, then copy.
Examples
Plan comparison
Three plan panels with a wider minimum track (--forma-grid-min: 18rem) so each panel keeps a readable measure. The panels sit in three columns on a wide screen and drop to fewer columns as the container narrows.
Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.
-
Starter
Up to 5 people, community support, 10 GB storage.
-
Team
Up to 50 people, business-hours support, 1 TB storage and audit log export.
-
Enterprise
Unlimited people, single sign-on, dedicated support and data residency options.
<forma-grid class="forma-component-tag">
<ul class="forma-grid" role="list" aria-label="Plans" style="--forma-grid-min: 18rem">
<li class="forma-surface forma-stack" data-density="compact">
<h2>Starter</h2>
<p>Up to 5 people, community support, 10 GB storage.</p>
<button type="button">Choose Starter</button>
</li>
<li class="forma-surface forma-stack" data-density="compact">
<h2>Team</h2>
<p>Up to 50 people, business-hours support, 1 TB storage and audit log export.</p>
<button type="button">Choose Team</button>
</li>
<li class="forma-surface forma-stack" data-density="compact">
<h2>Enterprise</h2>
<p>Unlimited people, single sign-on, dedicated support and data residency options.</p>
<button type="button">Talk to sales</button>
</li>
</ul>
</forma-grid>
Click or tap the code once to select all of it, then copy.
Analytical monitoring tiles
Six service tiles under data-density="analytical" with a narrow minimum track. The tighter gap keeps more tiles in view for monitoring; each tile still states its status in text.
API gateway
Healthy
Auth
Healthy
Billing
Degraded
Search
Healthy
Exports
No data
Webhooks
Paused
<forma-grid class="forma-component-tag">
<ul class="forma-grid" role="list" aria-label="Service health" data-density="analytical" style="--forma-grid-min: 11rem">
<li class="forma-surface"><h2>API gateway</h2><p><span class="forma-status-lozenge" data-state="ok">Healthy</span></p></li>
<li class="forma-surface"><h2>Auth</h2><p><span class="forma-status-lozenge" data-state="ok">Healthy</span></p></li>
<li class="forma-surface"><h2>Billing</h2><p><span class="forma-status-lozenge" data-state="attention">Degraded</span></p></li>
<li class="forma-surface"><h2>Search</h2><p><span class="forma-status-lozenge" data-state="ok">Healthy</span></p></li>
<li class="forma-surface"><h2>Exports</h2><p><span class="forma-status-lozenge" data-state="unknown">No data</span></p></li>
<li class="forma-surface"><h2>Webhooks</h2><p><span class="forma-status-lozenge" data-state="blocked">Paused</span></p></li>
</ul>
</forma-grid>
Click or tap the code once to select all of it, then copy.
Single result
A grid holding one item. auto-fit collapses the empty tracks, so the lone item stretches across the row instead of sitting in a narrow first column.
Production (eu-west)
Only one environment matches the filter "eu".
<forma-grid class="forma-component-tag">
<ul class="forma-grid" role="list" aria-label="Matching environments">
<li class="forma-surface"><h2>Production (eu-west)</h2><p>Only one environment matches the filter "eu".</p></li>
</ul>
</forma-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 environment list
Four environment panels at phone width. Because the minimum track is larger than half the screen, the grid is a single column.
What changes at narrow widths
- With the default 16rem minimum, 320px and 390px screens fit only one track, so items stack in source order.
min(100%, var(--forma-grid-min))keeps a track from ever exceeding the container, so there is no horizontal scroll even when the minimum is wider than the screen.- In landscape on a phone two columns may fit; the change is driven by available width, not device type.
- Each item is full width, so links and buttons inside keep generous touch areas.
<forma-grid class="forma-component-tag">
<ul class="forma-grid" role="list" aria-label="Environments on this account">
<li class="forma-surface"><h2>Production</h2><p>12 services, all reporting.</p></li>
<li class="forma-surface"><h2>Staging</h2><p>12 services, 1 deploying.</p></li>
<li class="forma-surface"><h2>Preview</h2><p>4 short-lived environments from open pull requests.</p></li>
<li class="forma-surface"><h2>Development</h2><p>9 services, 3 idle.</p></li>
</ul>
</forma-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 |
|---|---|---|---|---|
role | ul.forma-grid | list | — | Restores list semantics that some browsers drop when list styling is removed. Keep it when the grid is a ul or ol. |
aria-label | .forma-grid | string | — | Names the collection so screen-reader users know what the list contains. |
data-density | .forma-grid | relaxed | standard | compact | analytical | absent (1rem gap) | Contextual density posture. Sets the gap to 1.5rem, 1rem, or 0.5rem (compact and analytical). Not a data-forma-* hook; it changes spacing only. |
style | .forma-grid | --forma-grid-min / --forma-grid-gap | — | Per-instance override of the minimum track width or the gap. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-grid | Block class | — | Auto-fit grid of equal columns sized by a minimum track width. |
[data-density] | Attribute hook | — | Density posture on the grid. relaxed = 1.5rem, standard = 1rem, compact and analytical = 0.5rem gap. Overrides --forma-grid-gap. |
--forma-grid-gap | Custom property | — | Gap between rows and columns. Default --forma-primitive-spacing-4 (1rem). |
--forma-grid-min | Custom property | — | Minimum track width before a column is dropped. Default 16rem. Clamped to 100% of the container. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through focusable content row by row in source order. The grid is not an ARIA grid and has no arrow-key navigation. |
Form behavior
Not a form control.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Multi-column | container wider than two minimum tracks | Items fill as many equal columns as fit. |
| Single column | container narrower than two minimum tracks | Items stack at full width in source order. |
| Density posture | data-density attribute | Gap follows the posture instead of --forma-grid-gap. |
Accessibility
Forma provides
- Placement follows source order, so reading and focus order match the visual rows.
- Tracks never exceed the container, so the grid itself does not cause horizontal scrolling at 320px or 400% zoom.
- Adds no role;
.forma-gridon a list keeps list semantics when role="list" is present.
Your application supplies
- Use a list (ul or ol with role="list") when the items are a collection, and name it with aria-label.
- Give each item a heading or other text so identity does not depend on its column position.
- Do not use role="grid" for this layout; it is not an interactive data grid.
Responsive behavior
- Container-driven: the column count is computed from the grid's own inline size, so the same grid reflows correctly inside a narrow sidebar on a wide screen.
- No media queries. At phone widths the default 16rem minimum yields one column.
- auto-fit collapses empty tracks, so a short collection stretches its items to fill the row.
- Items inherit
min-inline-sizefrom their own styles; Surface setsmin-inline-size: 0, so long words wrap instead of widening the track.
Motion
- No animation: columns reflow instantly when the width changes.
Usage guidance
Do
- Set
--forma-grid-minfrom the content: the narrowest width at which one item is still readable. - Use
data-densityrather than a custom gap when the whole region's posture changes.
Avoid
- Encoding priority or rank through column position; screen readers hear only source order.
- Setting a fixed column count; let the minimum track decide.
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.