Layout primitives

Rail

<forma-rail>

Supporting rail plus flexible primary region with start/end placement and single-column reflow.

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

Purpose

A rail is a two-column grid: a bounded supporting column between 12rem and 18rem wide and a primary column that takes the rest. data-side="end" moves the rail track to the inline end. At 48rem viewport width and below, both collapse to one column. Because grid auto-placement follows source order, the element written first always lands in the first track: author the rail first for a start rail and the primary content first for an end rail. The application owns what the rail contains (context, evidence, controls) and whether it is shown.

Use when

  • A supporting column (record context, evidence, inspector controls) should stay at a bounded width next to the primary work.
  • The layout needs a predictable single breakpoint rather than content-driven wrapping.
  • The supporting column belongs at the inline end, after the primary content in reading order.

Avoid when

  • The pair should switch by the container's own width: use Sidebar, which wraps intrinsically.
  • Both regions are peers: use Switcher.
  • One region is a focused work artifact with an inspector: Focus stage expresses that relationship directly.
  • Users need to resize the columns: use Split pane with application behavior.

Behavior to know

  • The rail track is minmax(12rem, 18rem); the primary track is minmax(50%, 1fr).
  • Both children get min-inline-size: 0, so long content wraps instead of widening a track.
  • Items align to the start of the block axis; a short rail does not stretch to the primary height.

Basic example

The smallest correct markup: the canonical pattern from patterns/rail.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 rail

Rendered from the canonical pattern file.

HTML · Minimal rail Raw HTML for HTML · Minimal rail
<forma-rail class="forma-component-tag">
<section class="forma-rail" aria-label="Content with supporting rail">
  <aside class="forma-surface"><h2>Context</h2><p>Supporting navigation, evidence, or controls.</p></aside>
  <main><h2>Primary work</h2><p>The primary region keeps semantic source order and absorbs remaining space.</p></main>
</section>
</forma-rail>

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

Examples

Scenario

Case record with context rail

A support case: a start rail with customer context and the conversation as primary content. The rail is first in the source, so it is read first and shown first when stacked.

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.

Case 48213: Label printer offline

The store reports that the label printer stopped responding after the overnight update. A remote restart did not help.

HTML · Case record with context rail Raw HTML for HTML · Case record with context rail
<forma-rail class="forma-component-tag">
  <div class="forma-rail">
    <aside class="forma-surface forma-stack" data-density="compact" aria-labelledby="rail-case-context-rail-customer">
      <h2 id="rail-case-context-rail-customer">Customer</h2>
      <dl class="forma-key-value-list">
        <div><dt>Account</dt><dd>Contoso Pharmacy</dd></div>
        <div><dt>Plan</dt><dd>Enterprise</dd></div>
        <div><dt>Open cases</dt><dd>2</dd></div>
      </dl>
    </aside>
    <article class="forma-stack" aria-labelledby="rail-case-context-rail-title">
      <h2 id="rail-case-context-rail-title">Case 48213: Label printer offline</h2>
      <p>The store reports that the label printer stopped responding after the overnight update. A remote restart did not help.</p>
      <div class="forma-cluster"><button type="button">Reply</button><button type="button">Escalate</button></div>
    </article>
  </div>
</forma-rail>

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

Scenario

End rail with evidence

data-side="end" places the rail at the inline end. The finding is written first in the source so it occupies the primary track; the evidence follows in both reading order and position.

Finding: expired TLS certificate

The certificate for api.example.com expired on 28 September. Clients that pin the chain will fail until it is replaced.

HTML · End rail with evidence Raw HTML for HTML · End rail with evidence
<forma-rail class="forma-component-tag">
  <div class="forma-rail" data-side="end">
    <article class="forma-stack" aria-labelledby="rail-end-rail-evidence-title">
      <h2 id="rail-end-rail-evidence-title">Finding: expired TLS certificate</h2>
      <p>The certificate for api.example.com expired on 28 September. Clients that pin the chain will fail until it is replaced.</p>
    </article>
    <aside class="forma-surface forma-stack" data-density="compact" aria-labelledby="rail-end-rail-evidence-sources">
      <h3 id="rail-end-rail-evidence-sources">Evidence</h3>
      <p>Scanner run 2026-09-29 04:00 UTC</p>
      <p>Certificate serial 0x4f2a…91</p>
    </aside>
  </div>
</forma-rail>

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 rail

The case layout at phone width. The grid becomes one column and the rail sits above the primary content because it comes first in the source.

Viewport width

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

What changes at narrow widths

  • At 48rem viewport width and below the grid has a single minmax(0, 1fr) column for both start and end rails.
  • Stacked order is source order; an end rail written after the content appears below it.
  • The rail's 12rem minimum no longer applies once stacked, so it takes the full width at 320px.
  • Tablets in portrait (up to 768px) are also single column; landscape tablets usually show both tracks.
HTML · Mobile collapsed rail Raw HTML for HTML · Mobile collapsed rail
<forma-rail class="forma-component-tag">
  <div class="forma-rail">
    <aside class="forma-surface" aria-labelledby="rail-mobile-collapsed-rail-customer">
      <h2 id="rail-mobile-collapsed-rail-customer">Customer</h2>
      <p>Contoso Pharmacy · Enterprise</p>
    </aside>
    <article class="forma-stack" aria-labelledby="rail-mobile-collapsed-rail-title">
      <h2 id="rail-mobile-collapsed-rail-title">Case 48213</h2>
      <p>Label printer offline after the overnight update.</p>
    </article>
  </div>
</forma-rail>

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-labelledbyrail and primary regionsid of the region heading—Names aside and article regions by their visible headings.
data-side.forma-railendabsent (start)Moves the rail track to the inline end. Author the primary content first in the source when using it.
data-densitynested .forma-stackcompact—Used on stacks inside the rail; it does not affect the rail grid.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-railBlock class—Two-column grid of a bounded rail track and a flexible primary track.
[data-side]Attribute hook"end"end swaps the track order to primary then rail. It changes track sizes only; items are still placed in source order.
--forma-rail-content-minCustom propertydefault 50%Minimum of the primary track. Default 50%.
--forma-rail-measureCustom propertydefault minmax(12rem, 18rem)Rail track size. Default minmax(12rem, 18rem).
--forma-rail-spaceCustom propertydefault var(--forma-primitive-spacing-5, 1.5rem)Gap between the tracks. Default --forma-primitive-spacing-5 (1.5rem).
Keyboard interaction
KeysResult
Tab / Shift+TabFollows source order, which is also the visual order for correctly authored start and end rails.

Form behavior

Not a form control.

States

Rail states
StateHow it is expressedPresentation
Start railno data-sideRail track first, primary track second.
End raildata-side="end"Primary track first, rail track second.
Stackedviewport at or below 48remOne column; children stack in source order.

Accessibility

Forma provides

  • Uses source-order auto-placement only, so reading, focus and visual order stay aligned when authored as documented.
  • Adds no landmarks or roles.
  • Children cannot widen tracks beyond the viewport because they have min-inline-size: 0.

Your application supplies

  • Match source order to the chosen side: rail first for start, primary first for end.
  • Label the aside so its landmark is distinguishable from others on the page.
  • Keep essential actions in the primary region; a rail may be far from the content when stacked.

Responsive behavior

  • Viewport breakpoint at 48rem collapses both variants to one column.
  • Above 48rem the rail is 12rem–18rem wide; in a narrow pane on a wide screen the tracks can be tight, so prefer Sidebar inside panes.
  • Long content wraps within its track.
  • Wide tables in the primary region belong inside Bounded overflow.

Motion

  • No animation: the grid changes between two and one columns instantly.

Usage guidance

Do

  • Keep rail content supportive and scannable: context, evidence, related controls.
  • Use data-side="end" when the supporting material should be read after the primary content.

Avoid

  • Using data-side="end" with the rail written first; it would land in the wide primary track.
  • Hiding required information only in the rail.

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.