Layout primitives

Section

<forma-section>

Vertical page-section spacing primitive; inside the marketing shell it also carries tone and child rhythm.

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

Purpose

A section separates the major regions of a page with consistent block padding. In an application page it is simply padding-block (3rem by default) plus a leading margin between its direct children. Inside the marketing shell (.forma-site) it uses the site's fluid section spacing instead, and with data-forma-tone it becomes a full tonal band (surface, elevated or inverse) with inner padding, so text, links and rules switch to colors that are contrast-safe on that background. The element should be a real section with a heading, because the section is how readers and assistive technology find the page's parts.

Use when

  • A page has several major regions that should be separated by the same vertical rhythm.
  • A marketing page needs a tonal band (for example an inverse call-out region) whose text colors adapt automatically.
  • Children of a region should be spaced by the site's standard stack rhythm.

Avoid when

  • You only need spacing between siblings inside a panel: use Stack.
  • The region needs a boundary and panel padding inside an application view: use Surface.
  • The region is the page's opening statement: use Hero. The closing conversion region is Call to action.
  • The heading row needs an eyebrow, supporting text and an aside action: put a Section heading inside the section.

Behavior to know

  • Outside .forma-site: padding-block: var(--forma-section-space, 3rem).
  • Inside .forma-site: half the fluid section space as block padding; a toned section gets margin plus inner padding on all sides.
  • Direct children after the first get --forma-layout-stack-space as a top margin; a child directly after .forma-section-heading gets none, because the heading already owns that space.

Basic example

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

Canonical

Minimal section

Rendered from the canonical pattern file.

Recent activity

Sections separate page regions with a consistent block rhythm.

HTML · Minimal section Raw HTML for HTML · Minimal section
<forma-section class="forma-component-tag">
<section class="forma-section" aria-labelledby="section-title">
  <h2 id="section-title">Recent activity</h2>
  <p>Sections separate page regions with a consistent block rhythm.</p>
</section>
</forma-section>

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

Examples

Scenario

Surface-toned band on a marketing page

A section with data-forma-tone="surface" inside the site shell. The band gets inner padding and the secondary background; links and muted text switch to colors validated for that tone.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Security

Your data stays in your region

Every workspace chooses a data region at creation. Backups never leave it.

Read the data residency overview

HTML · Surface-toned band on a marketing page Raw HTML for HTML · Surface-toned band on a marketing page
<forma-section class="forma-component-tag">
  <div class="forma-site">
    <section class="forma-section" data-forma-tone="surface" aria-labelledby="section-toned-band-title">
      <header class="forma-section-heading">
        <div class="forma-section-heading__text">
          <p class="forma-eyebrow">Security</p>
          <h2 id="section-toned-band-title">Your data stays in your region</h2>
          <p>Every workspace chooses a data region at creation. Backups never leave it.</p>
        </div>
      </header>
      <p><a href="#data-residency">Read the data residency overview</a></p>
    </section>
  </div>
</forma-section>

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

Scenario

Inverse band for a key statement

An inverse-toned section used once on a page for a statement that should stand apart. Heading, text and link colors all switch to the inverse role tokens.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Built for audits, not just demos

Every change to permissions, retention and billing is recorded with who made it and why.

See what the audit trail records

HTML · Inverse band for a key statement Raw HTML for HTML · Inverse band for a key statement
<forma-section class="forma-component-tag">
  <div class="forma-site">
    <section class="forma-section" data-forma-tone="inverse" aria-labelledby="section-inverse-band-title">
      <h2 id="section-inverse-band-title">Built for audits, not just demos</h2>
      <p>Every change to permissions, retention and billing is recorded with who made it and why.</p>
      <p><a href="#audit-trail">See what the audit trail records</a></p>
    </section>
  </div>
</forma-section>

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

Scenario

Application page regions

Two consecutive sections in an application settings page, outside the marketing shell, with a tighter block padding set through --forma-section-space.

General

Workspace name, default language and time zone.

Delete workspace

Deleting a workspace removes all projects after a 30-day recovery period.

HTML · Application page regions Raw HTML for HTML · Application page regions
<forma-section class="forma-component-tag">
  <div>
    <section class="forma-section" style="--forma-section-space: 1.5rem" aria-labelledby="section-application-sections-general">
      <h2 id="section-application-sections-general">General</h2>
      <p>Workspace name, default language and time zone.</p>
    </section>
    <section class="forma-section" style="--forma-section-space: 1.5rem" aria-labelledby="section-application-sections-danger">
      <h2 id="section-application-sections-danger">Delete workspace</h2>
      <p>Deleting a workspace removes all projects after a 30-day recovery period.</p>
    </section>
  </div>
</forma-section>

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 marketing sections

A plain section followed by a toned section at phone width. The fluid section spacing shrinks with the viewport, so bands stay separated without wasting the screen.

Viewport width

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

What changes at narrow widths

  • Inside .forma-site section spacing comes from fluid tokens, so padding and band margins are smaller at 320px than on desktop.
  • Toned bands keep inner padding on all sides, so text never touches the band edge on narrow screens.
  • Headings wrap and are limited to a short measure by the shell typography; nothing overflows horizontally.
  • Order and tone are the same in portrait and landscape.
HTML · Mobile marketing sections Raw HTML for HTML · Mobile marketing sections
<forma-section class="forma-component-tag">
  <div class="forma-site">
    <section class="forma-section" aria-labelledby="section-mobile-sections-how">
      <h2 id="section-mobile-sections-how">How it works</h2>
      <p>Connect your repository, choose a template and publish.</p>
    </section>
    <section class="forma-section" data-forma-tone="elevated" aria-labelledby="section-mobile-sections-pricing">
      <h2 id="section-mobile-sections-pricing">Pricing</h2>
      <p>Free for public projects. Team plans start at $8 per seat.</p>
    </section>
  </div>
</forma-section>

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-labelledbysection.forma-sectionid of the section heading—Names the section so it is exposed as a region landmark. Always label sections.
data-forma-tonesection.forma-sectionpage | surface | elevated | inverseabsent (page)Marketing surface tone. Non-page tones inside .forma-site add band padding and switch text, link and rule colors.
stylesection.forma-section--forma-section-space: <length>—Per-instance block padding outside the marketing shell.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-sectionBlock class—Page region with block padding. Inside .forma-site it uses fluid layout spacing and child rhythm.
[data-forma-tone]Attribute hook—Surface tone. Inside .forma-site, any tone except page gives the section margin, inner padding, a tone background and tone text colors; in forced colors it also gets a 1px CanvasText border.
--forma-section-spaceCustom property—Block padding outside the marketing shell. Default --forma-primitive-spacing-7 (3rem). Ignored inside .forma-site, which uses --forma-layout-section-space.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through focusable content in source order. Sections themselves are not focusable.

Form behavior

Not a form control.

States

Section states
StateHow it is expressedPresentation
Application sectionoutside .forma-siteBlock padding from --forma-section-space.
Marketing sectioninside .forma-siteFluid block padding; children spaced by the layout stack space.
Toned banddata-forma-tone="surface | elevated | inverse" inside .forma-siteBackground and text colors from the tone, plus inner padding and outer margin.
Forced colors@media (forced-colors: active)Toned sections draw a CanvasText border because the tone background is removed.

Accessibility

Forma provides

  • Tones set text, heading, link and rule colors validated against their background.
  • Toned bands keep a visible border in forced-colors mode.
  • Spacing only; no roles are added and order is never changed.

Your application supplies

  • Use a section element with a visible heading and aria-labelledby so the region is navigable.
  • Keep heading levels consistent across sections (usually h2).
  • Use the inverse tone sparingly; it draws strong attention.

Responsive behavior

  • Inside .forma-site, spacing uses fluid tokens that scale with viewport width.
  • Outside the shell, spacing is fixed at --forma-section-space.
  • Sections are full width of their parent; constrain content with Container or Measure.
  • The child rhythm (.forma-section > * + *) is defined in the marketing layer but not scoped to .forma-site, so it also applies in application pages that load all.css.

Motion

  • No animation: sections and tones are static.

Usage guidance

Do

  • Alternate page and surface tones to separate adjacent bands when content types change.
  • Put a Section heading first when the section needs an eyebrow or an aside action.

Avoid

  • Adding a tone to every section; the contrast between bands stops meaning anything.
  • Using sections as generic wrappers without headings.

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.