Layout primitives

Split

<forma-split>

Marketing-layer two-part layout: a dominant primary region and a supporting region that wraps below when space runs out.

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

Purpose

A split puts a dominant primary region beside a supporting region on site pages: install steps beside requirements, a product explanation beside a code sample, a narrative beside a quote. The first child keeps at least 55% of the row and absorbs extra space; the last child prefers about a third of the row, between 18rem and 30rem. When both cannot fit, the supporting region wraps below the primary one. The switch is content-driven with no breakpoint, and the gap uses the site's fluid section spacing, so place it inside .forma-site.

Use when

  • A marketing or documentation page region has one main message and one supporting block.
  • The supporting block (requirements, a code sample, a quote, a form) should sit beside the main text on wide screens and below it on narrow ones.
  • The layout should reflow by the space available to it rather than by viewport breakpoints.

Avoid when

  • You are laying out an application view: use Switcher or Sidebar, which use application spacing.
  • Users must resize the two parts: use Resizable split pane.
  • The region is the page's opening statement: Hero has the same content-and-aside structure plus hero typography.
  • There are more than two parts: use Card grid or Grid.

Behavior to know

  • Only the first and last children are sized; use exactly two children.
  • Children align to the start of the cross axis, so a short aside does not stretch.
  • Stacked order is source order: the primary region is always above the supporting one when wrapped.

Basic example

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

Canonical

Minimal split

Rendered from the canonical pattern file.

Install

The primary region takes the available space. The supporting region wraps below it when the row runs out of room.

HTML · Minimal split Raw HTML for HTML · Minimal split
<forma-split class="forma-component-tag">
<div class="forma-site">
  <div class="forma-split">
    <div>
      <h2>Install</h2>
      <p>The primary region takes the available space. The supporting region wraps below it when the row runs out of room.</p>
    </div>
    <aside aria-label="Requirements">
      <h3>Requirements</h3>
      <p>Node 22 or later.</p>
    </aside>
  </div>
</div>
</forma-split>

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

Examples

Scenario

Product explanation with a code sample

Primary text explains the configuration; the supporting region is a code sample. On a wide page they sit side by side; as the page narrows the code wraps below the explanation.

Pin one version per site

Each site records the exact Forma release it uses in a lock file. Upgrades are explicit, reviewed and reversible.

forma.lock
forma 0.3.0
destination assets/forma
HTML · Product explanation with a code sample Raw HTML for HTML · Product explanation with a code sample
<forma-split class="forma-component-tag">
  <div class="forma-site">
    <div class="forma-split">
      <div>
        <h2>Pin one version per site</h2>
        <p>Each site records the exact Forma release it uses in a lock file. Upgrades are explicit, reviewed and reversible.</p>
      </div>
      <figure class="forma-code-figure">
        <figcaption id="split-product-code-sample-caption">forma.lock</figcaption>
        <pre class="forma-code" tabindex="0" aria-labelledby="split-product-code-sample-caption"><code>forma 0.3.0
destination assets/forma</code></pre>
      </figure>
    </div>
  </div>
</forma-split>

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

Scenario

Narrative with key facts

A customer story with a facts list as the supporting region. The facts keep a readable width between 18rem and 30rem while the story absorbs the remaining space.

How Fabrikam moved 40 sites in a weekend

The team migrated every regional site to the shared design system without changing a single URL, then retired four separate stylesheets.

HTML · Narrative with key facts Raw HTML for HTML · Narrative with key facts
<forma-split class="forma-component-tag">
  <div class="forma-site">
    <div class="forma-split">
      <article aria-labelledby="split-narrative-with-facts-title">
        <h2 id="split-narrative-with-facts-title">How Fabrikam moved 40 sites in a weekend</h2>
        <p>The team migrated every regional site to the shared design system without changing a single URL, then retired four separate stylesheets.</p>
      </article>
      <aside aria-labelledby="split-narrative-with-facts-facts">
        <h3 id="split-narrative-with-facts-facts">At a glance</h3>
        <dl class="forma-facts">
          <div class="forma-facts__item"><dt>40 sites</dt><dd>Migrated in two days</dd></div>
          <div class="forma-facts__item"><dt>4 stylesheets</dt><dd>Retired after launch</dd></div>
        </dl>
      </aside>
    </div>
  </div>
</forma-split>

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 wrapped split

The install layout at phone width. The primary region needs 55% of the row and the aside at least 18rem, so they cannot share a line and the aside wraps below.

Viewport width

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

What changes at narrow widths

  • Below roughly 44rem of available width the supporting region wraps onto its own line and both regions become full width.
  • The primary region's minimum is min(100%, 55%), so it never overflows a 320px screen.
  • The gap between the stacked regions is the fluid section spacing, which shrinks on small screens.
  • Order does not change on rotation; landscape tablets usually show both regions side by side.
HTML · Mobile wrapped split Raw HTML for HTML · Mobile wrapped split
<forma-split class="forma-component-tag">
  <div class="forma-site">
    <div class="forma-split">
      <div>
        <h2>Install</h2>
        <p>Run the installer once per site. It verifies every download against the release checksums.</p>
      </div>
      <aside aria-labelledby="split-mobile-wrapped-requirements">
        <h3 id="split-mobile-wrapped-requirements">Requirements</h3>
        <p>Bash 4 or later and a network connection to the release host.</p>
      </aside>
    </div>
  </div>
</forma-split>

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-labelledbyarticle / asideid of the region heading—Names each region by its heading.
tabindexpre.forma-code0—Makes a scrollable code block keyboard-scrollable in the code sample example.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-splitBlock class—Wrapping flex row. First child: flex: 999 1 0 with minimum min(100%, 55%). Last child: basis clamp(18rem, 32%, 30rem). Gap is half the fluid section space.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the primary region and then the supporting region, in source order.

Form behavior

Not a form control.

States

Split states
StateHow it is expressedPresentation
Side by siderow fits 55% plus the aside basis and gapPrimary region grows; supporting region stays between 18rem and 30rem.
Wrappedrow too narrowSupporting region moves below the primary region at full width.

Accessibility

Forma provides

  • Wrapping never reorders content; reading and focus order match the visual order.
  • Clamped minimums keep both regions inside a 320px viewport.
  • Adds no roles or landmarks.

Your application supplies

  • Put the primary message first in the source.
  • Label aside regions so their landmarks are distinguishable.
  • Make scrollable code or tables in the supporting region keyboard-focusable.

Responsive behavior

  • Content-driven wrap with no media queries; the switch depends on the split's own width.
  • Gap uses --forma-layout-section-space, a fluid token, so spacing scales with the viewport.
  • Place it inside .forma-site: its gap and the surrounding typography and tone come from the marketing role tokens.

Motion

  • No animation: regions wrap instantly.

Usage guidance

Do

  • Use exactly two children: primary first, supporting last.
  • Keep the supporting region short enough to read at 18rem.

Avoid

  • Adding a third child; middle children receive no sizing rules.
  • Using split inside application views; use Switcher there.

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.