Layout primitives

Priority stack

<forma-priority-stack>

Responsive composition where priority changes space allocation but never DOM or semantic order.

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

Purpose

A priority stack places a small number of regions in a wrapping row. Each region wants at least 18rem; the region marked data-priority="primary" grows twice as fast as the others, so it takes most of the extra width when there is room. When the row cannot fit the regions at their minimum, they wrap and eventually stack, always in source order. Priority is therefore expressed as space, not as position. The application decides which region is primary for the current task.

Use when

  • One task region should dominate while one or two supporting regions stay beside it on wide screens.
  • The layout must reflow by available space inside panes as well as pages.
  • The primary region may change with the task, and changing an attribute is preferable to changing structure.

Avoid when

  • Supporting context is a fixed-width column: use Rail or Sidebar.
  • The composition has many peer regions: use Responsive grid.
  • The primary region is a focused artifact with an inspector beside it: use Focus stage.

Behavior to know

  • Regions align to the start of the cross axis; a short region does not stretch to match a tall one.
  • The primary region's larger share is visual only; it is not announced and does not move.
  • Wrapping is container-driven; a viewport rule at 30rem forces every region to full width.

Basic example

The smallest correct markup: the canonical pattern from patterns/priority-stack.html inside its public tag. Copy this first, then adapt labels, names and state. This component owns a page's main landmark, so it renders in its own document below.

Canonical

Minimal priority stack

Rendered from the canonical pattern file.

HTML · Minimal priority stack Raw HTML for HTML · Minimal priority stack
<forma-priority-stack class="forma-component-tag">
<section class="forma-priority-stack" aria-label="Responsive priority composition">
  <main class="forma-surface" data-priority="primary"><h2>Primary task</h2><p>Receives more space when available and stacks first when space contracts.</p></main>
  <aside class="forma-surface"><h2>Supporting context</h2><p>Secondary context remains in semantic order.</p></aside>
</section>
</forma-priority-stack>

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

Examples

Scenario

Review workspace

A document under review is primary; the reviewer checklist supports it. On a wide screen the document gets roughly two thirds of the row. The document is first in the source, so it is also first when stacked.

Vendor agreement, draft 3

Section 7 now limits liability to twelve months of fees. Section 9 adds a 30-day termination notice for convenience.

HTML · Review workspace Raw HTML for HTML · Review workspace
<forma-priority-stack class="forma-component-tag">
  <div class="forma-priority-stack">
    <article class="forma-surface forma-stack" data-priority="primary" aria-labelledby="priority-stack-review-workspace-doc">
      <h2 id="priority-stack-review-workspace-doc">Vendor agreement, draft 3</h2>
      <p>Section 7 now limits liability to twelve months of fees. Section 9 adds a 30-day termination notice for convenience.</p>
    </article>
    <aside class="forma-surface forma-stack" data-density="compact" aria-labelledby="priority-stack-review-workspace-checklist">
      <h2 id="priority-stack-review-workspace-checklist">Review checklist</h2>
      <label class="forma-checkbox">
        <input class="forma-checkbox__input" type="checkbox" name="priority-stack-review-workspace-liability" value="done" checked>
        <span class="forma-checkbox__box" aria-hidden="true"></span>
        <span class="forma-checkbox__text"><span class="forma-checkbox__label">Liability cap reviewed</span></span>
      </label>
      <label class="forma-checkbox">
        <input class="forma-checkbox__input" type="checkbox" name="priority-stack-review-workspace-termination" value="done">
        <span class="forma-checkbox__box" aria-hidden="true"></span>
        <span class="forma-checkbox__text"><span class="forma-checkbox__label">Termination terms reviewed</span></span>
      </label>
    </aside>
  </div>
</forma-priority-stack>

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

Scenario

Alerts before the primary task

Two supporting regions and a primary region under data-density="compact". The alert summary is written first because it must be read first; the primary work area still gets the most space when the row fits.

Alerts

2 shipments delayed by weather.

Dispatch queue

18 orders ready to assign. Oldest waiting 42 minutes.

Drivers

11 available, 4 on break.

HTML · Alerts before the primary task Raw HTML for HTML · Alerts before the primary task
<forma-priority-stack class="forma-component-tag">
  <div class="forma-priority-stack" data-density="compact">
    <section class="forma-surface" aria-labelledby="priority-stack-supporting-first-alerts">
      <h2 id="priority-stack-supporting-first-alerts">Alerts</h2>
      <p>2 shipments delayed by weather.</p>
    </section>
    <section class="forma-surface" data-priority="primary" aria-labelledby="priority-stack-supporting-first-queue">
      <h2 id="priority-stack-supporting-first-queue">Dispatch queue</h2>
      <p>18 orders ready to assign. Oldest waiting 42 minutes.</p>
    </section>
    <section class="forma-surface" aria-labelledby="priority-stack-supporting-first-drivers">
      <h2 id="priority-stack-supporting-first-drivers">Drivers</h2>
      <p>11 available, 4 on break.</p>
    </section>
  </div>
</forma-priority-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 stacked priority

The review workspace at phone width. Every region is full width and they stack in source order; the primary attribute has no visible effect because there is no extra space to share.

Viewport width

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

What changes at narrow widths

  • At 30rem and below --forma-priority-min becomes 100%, so each region takes its own full-width row.
  • Above that, regions wrap as soon as the row cannot hold every region at 18rem plus the gap.
  • Stacked order is source order; data-priority never moves a region to the top.
  • Checkbox rows in the supporting region keep their full target size at 320px.
HTML · Mobile stacked priority Raw HTML for HTML · Mobile stacked priority
<forma-priority-stack class="forma-component-tag">
  <div class="forma-priority-stack">
    <article class="forma-surface" data-priority="primary" aria-labelledby="priority-stack-mobile-stacked-priority-doc">
      <h2 id="priority-stack-mobile-stacked-priority-doc">Vendor agreement</h2>
      <p>Draft 3 is ready for legal review.</p>
    </article>
    <aside class="forma-surface" aria-labelledby="priority-stack-mobile-stacked-priority-notes">
      <h2 id="priority-stack-mobile-stacked-priority-notes">Notes</h2>
      <p>Finance approved the payment terms.</p>
    </aside>
  </div>
</forma-priority-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.

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-prioritydirect childprimaryabsentMarks the region that receives extra space (flex-grow 2). Not a data-forma-* hook; presentation only.
data-density.forma-priority-stackrelaxed | 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-labelledbyregionsid of the region heading—Names each region by its heading.
namecheckbox inputsstring—Form field names used in the review example.
checkedcheckbox inputsbooleanabsentInitial checked state in the review example.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-priority-stackBlock class—Wrapping flex row. Each child has basis --forma-priority-min and a minimum of min(100%, --forma-priority-min).
[data-density]Attribute hook—Density posture. relaxed = 1.5rem, standard = 1rem, compact and analytical = 0.5rem gap; overrides --forma-priority-space.
[data-priority]Attribute hook—primary on a direct child sets flex-grow to 2, so it takes a larger share of extra space.
--forma-priority-minCustom property—Preferred and minimum width of each region. Default 18rem; 100% at 30rem viewport width and below.
--forma-priority-spaceCustom property—Gap between regions. Default --forma-primitive-spacing-4 (1rem).
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through regions in source order, regardless of which is primary.

Form behavior

Not a form control.

States

Priority stack states
StateHow it is expressedPresentation
Shared rowrow fits all regions at --forma-priority-minPrimary region grows twice as fast as the others.
Wrappedrow too narrow for all regionsRegions wrap in source order; each line's regions share its width.
Stackedviewport at or below 30remEvery region is full width.
Density posturedata-density attributeGap follows the posture.

Accessibility

Forma provides

  • Priority changes space only; DOM, reading and focus order never change.
  • Region minimums are clamped to 100%, so nothing overflows a 320px viewport.
  • Adds no roles or landmarks.

Your application supplies

  • Put content that must be read first earlier in the source, whatever its priority.
  • State priority or urgency in text where it matters; the extra width is not perceivable to everyone.
  • Name each region with a heading.

Responsive behavior

  • Container-driven wrapping from the flex basis; the same markup adapts inside a pane or a full page.
  • At 30rem viewport width and below every region is forced to full width.
  • Regions with long content wrap internally; wide tables belong in Bounded overflow.

Motion

  • No animation: regions reflow instantly when space changes or the primary region is reassigned.

Usage guidance

Do

  • Mark exactly one region as primary.
  • Keep the stack to two or three regions.

Avoid

  • Reordering the DOM to move the primary region; set data-priority instead.
  • Using priority to express domain severity or permissions.

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.