Layout primitives

Stack

<forma-stack>

Applies consistent vertical rhythm between semantic siblings.

Authoring tag
<forma-stack>
Behavior owner
Native CSS
Canonical source
patterns/stack.html

Purpose

A stack is the smallest composition primitive: it places independent children in one vertical column and owns only the space between them. Children keep their own semantics and internal spacing; the stack removes their block margins and inserts a single, predictable relationship instead. Use it inside forms, panels, cards and page regions whenever siblings should read as one ordered group. The data-density posture changes the gap for a whole region without touching the markup of its children.

Use when

  • Several independent siblings (headings, paragraphs, fields, panels) should be separated by one consistent vertical rhythm.
  • A settings panel, form section or card body needs its spacing set by the parent instead of by each child's margins.
  • A region needs a different density posture (relaxed for reading, compact for repeated expert work) without restyling its children.

Avoid when

  • Items should sit side by side and wrap: use Cluster.
  • Items form a two-dimensional collection of peers: use Grid or Responsive grid.
  • Long-form article text needs typographic rhythm between headings, lists and quotes: use Prose, which owns reading measure and heading spacing.
  • You need a visible boundary or background around the group: put the stack inside a Surface; the stack itself draws nothing.

Behavior to know

  • Children stay in source order; the stack never reorders, so reading, focus and visual order match.
  • Only direct children are spaced. Nested stacks set their own rhythm, which makes grouping by proximity explicit.
  • The stack draws no border, background or padding, so it adds no visual noise to a composition.

Basic example

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

Canonical

Minimal stack

Rendered from the canonical pattern file.

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.

Section title

Supporting context remains grouped with the heading.

Primary content

Stack owns only the vertical relationship between independent children.

HTML · Minimal stack Raw HTML for HTML · Minimal stack
<forma-stack class="forma-component-tag">
<section class="forma-stack" aria-label="Stack composition">
  <header><h2>Section title</h2><p>Supporting context remains grouped with the heading.</p></header>
  <article><h3>Primary content</h3><p>Stack owns only the vertical relationship between independent children.</p></article>
  <footer><button type="button">Continue</button></footer>
</section>
</forma-stack>

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

Examples

Scenario

Settings panel

A stack arranges a heading, two switches and a save action inside a surface. The stack owns the vertical relationship; each switch keeps its own internal layout.

Live demo. 2 native actions work here and are verified by an outcome test.

Workspace notifications

Choose which events send you an email. Changes apply to this workspace only.

HTML · Settings panel Raw HTML for HTML · Settings panel
<forma-stack class="forma-component-tag">
  <section class="forma-surface forma-stack" aria-labelledby="stack-settings-panel-title">
    <h2 id="stack-settings-panel-title">Workspace notifications</h2>
    <p>Choose which events send you an email. Changes apply to this workspace only.</p>
    <label class="forma-switch">
      <input class="forma-switch__input" type="checkbox" role="switch" name="stack-settings-panel-builds" value="on" checked>
      <span class="forma-switch__track" aria-hidden="true"></span>
      <span class="forma-switch__text"><span class="forma-switch__label">Failed builds</span></span>
    </label>
    <label class="forma-switch">
      <input class="forma-switch__input" type="checkbox" role="switch" name="stack-settings-panel-mentions" value="on">
      <span class="forma-switch__track" aria-hidden="true"></span>
      <span class="forma-switch__text"><span class="forma-switch__label">Mentions in review comments</span></span>
    </label>
  </section>
</forma-stack>

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

Scenario

Compact density for an expert form

The same kind of content under data-density="compact". The posture reduces the stack gap so more fields fit on screen for repeated data entry; field order, labels and target sizes do not change.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

Shipment details

HTML · Compact density for an expert form Raw HTML for HTML · Compact density for an expert form
<forma-stack class="forma-component-tag">
  <form class="forma-stack" data-density="compact" aria-labelledby="stack-compact-density-title">
    <h2 id="stack-compact-density-title">Shipment details</h2>
    <div class="forma-field">
      <label class="forma-field__label" for="stack-compact-density-reference">Reference</label>
      <input id="stack-compact-density-reference" name="reference" type="text" autocomplete="off">
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="stack-compact-density-carrier">Carrier</label>
      <input id="stack-compact-density-carrier" name="carrier" type="text">
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="stack-compact-density-weight">Weight (kg)</label>
      <input id="stack-compact-density-weight" name="weight" type="number" inputmode="decimal" min="0" step="0.1">
    </div>
    <div class="forma-cluster">
      <button type="submit">Save shipment</button>
      <button type="reset">Clear</button>
    </div>
  </form>
</forma-stack>

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

Scenario

Nested groups with relaxed outer rhythm

An outer relaxed stack separates two groups; each group is its own tighter stack. Proximity, not borders, tells the reader which heading owns which list.

Release 4.2 checklist

Before the release

Freeze the main branch and confirm the migration plan with the database owner.

Run the full regression suite against staging.

After the release

Watch error rates for one hour and post the summary in the release channel.

HTML · Nested groups with relaxed outer rhythm Raw HTML for HTML · Nested groups with relaxed outer rhythm
<forma-stack class="forma-component-tag">
  <article class="forma-stack" data-density="relaxed" aria-labelledby="stack-nested-grouping-title">
    <h2 id="stack-nested-grouping-title">Release 4.2 checklist</h2>
    <section class="forma-stack" data-density="compact" aria-labelledby="stack-nested-grouping-before">
      <h3 id="stack-nested-grouping-before">Before the release</h3>
      <p>Freeze the main branch and confirm the migration plan with the database owner.</p>
      <p>Run the full regression suite against staging.</p>
    </section>
    <section class="forma-stack" data-density="compact" aria-labelledby="stack-nested-grouping-after">
      <h3 id="stack-nested-grouping-after">After the release</h3>
      <p>Watch error rates for one hour and post the summary in the release channel.</p>
    </section>
  </article>
</forma-stack>

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 account summary

A phone-width account summary. The stack is already a single column, so nothing recomposes; long values wrap inside each child.

Live demo. 1 native action works here and is verified by an outcome test.

Viewport width

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

What changes at narrow widths

  • A stack is one column at every width, so there is no breakpoint and nothing moves at 320px.
  • Long values such as the email address wrap inside their own element; the stack never causes horizontal page scroll.
  • The gap is fixed by the density posture, not by viewport width, so touch targets in the child components keep their own minimum sizes.
  • Rotating to landscape only widens the children; order and spacing stay the same.
HTML · Mobile account summary Raw HTML for HTML · Mobile account summary
<forma-stack class="forma-component-tag">
  <section class="forma-stack" aria-labelledby="stack-mobile-account-summary-title">
    <h2 id="stack-mobile-account-summary-title">Account</h2>
    <dl class="forma-key-value-list">
      <div><dt>Owner</dt><dd>Priya Raman</dd></div>
      <div><dt>Billing email</dt><dd>accounts-payable.northwind-logistics@example.com</dd></div>
      <div><dt>Plan</dt><dd>Team, billed annually</dd></div>
    </dl>
    <p>Invoices are issued on the first business day of each month.</p>
    <a href="#stack-mobile-account-summary-title">Manage billing</a>
  </section>
</forma-stack>

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.

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.

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-stackrelaxed | standard | compact | analyticalabsent (1rem gap)Contextual density posture. Sets the stack gap to 1.5rem (relaxed), 1rem (standard) or 0.5rem (compact, analytical). It is not a data-forma-* hook and never changes semantics, order or target size.
aria-labelledbysection / article / formid of the group heading—Names a stacked region when the element is a landmark or a named group. The stack itself adds no role.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-stackBlock class—Vertical flex column. Removes block margins from direct children and spaces them with a gap plus a leading margin on every child after the first.
[data-density]Attribute hook—Density posture on the stack element. relaxed = 1.5rem, standard = 1rem, compact and analytical = 0.5rem gap (spacing primitives, so skins rescale them).
--forma-stack-gapCustom property—Foundation-layer gap between children. Default --forma-primitive-spacing-4 (1rem). Ignored when data-density is set.
--forma-stack-spaceCustom propertydefault var(--forma-primitive-spacing-4, 1rem)Component-layer margin inserted before each child after the first. Default --forma-primitive-spacing-4 (1rem). It adds to the gap, so the visible space between children is gap plus this value.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through focusable children in source order, which is also the visual order.

Form behavior

Not a form control. A form or fieldset may itself be the stack; submission is unaffected.

States

Stack states
StateHow it is expressedPresentation
Default rhythmno data-densityGap from --forma-stack-gap plus the leading margin from --forma-stack-space.
Density posturedata-density="relaxed | standard | compact | analytical"Replaces the gap with the posture's spacing. The leading margin still applies.

Accessibility

Forma provides

  • Never reorders children, so DOM order, reading order and focus order stay identical.
  • Adds no role, landmark or hidden content; the semantics are entirely the children's.
  • Density postures change spacing only and never shrink child targets below their own minimums.

Your application supplies

  • Choose the semantic element for the group (section, form, fieldset, ul) and label it when it is a landmark or named group.
  • Do not rely on spacing alone to separate unrelated groups; add headings so grouping survives screen readers and forced colors.
  • Check compact and analytical postures at 200% text size; tighter spacing must not make adjacent groups ambiguous.

Responsive behavior

  • One column at every width with no breakpoints; children fill the stack's inline size.
  • Children keep their own wrapping and overflow behavior; the stack adds no minimum width and never causes horizontal scroll.
  • Spacing does not change with viewport width; change the posture with data-density when the context changes.
  • Skins that rescale the spacing primitives (compact, comfortable) rescale stack spacing too.

Motion

  • No animation: the stack is static layout. Children that animate (disclosures, alerts) keep their own motion, and inserted children appear without a layout transition.

Usage guidance

Do

  • Make the semantic container the stack (for example section class="forma-stack") instead of adding a wrapper div.
  • Use nested stacks with a tighter posture to express sub-groups by proximity.

Avoid

  • Adding margins to children to fine-tune spacing; the stack resets them. Nest another stack instead.
  • Using a stack to fake a list; use ul or ol and make that element the stack.
  • Using compact density on reading-focused or unfamiliar tasks where separation aids orientation.

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.