Layout primitives

Surface

<forma-surface>

A bounded panel with secondary surface tone, border and padding for grouping related content without inventing semantics.

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

Purpose

A surface is a panel: secondary background, a subtle border and even padding around related content. It says "these things belong together" through enclosure while adding no role, heading or behavior; the element you put it on supplies the semantics (section, article, li, aside, form). Headings and paragraphs inside inherit the surface's text color so contrast stays correct on the secondary tone. Surfaces are the usual items of grids and the regions of sidebars and rails.

Use when

  • Related content needs a visible boundary to separate it from neighbors, such as a panel in a dashboard or a card in a grid.
  • Grouping must survive when proximity alone is ambiguous, for example in dense layouts.
  • A region needs padding and tone without becoming a component with its own behavior.

Avoid when

  • The panel is a marketing card with a title link and footer: use the card in Card grid.
  • The content is a callout that must name its kind (note, warning, decision): use Callout.
  • The panel announces a status or error: use Alert or Fault banner, which carry the right roles.
  • The panel previews consequential content before an action: use Preview surface.

Behavior to know

  • Tone, border and padding only; no radius, shadow or elevation.
  • min-inline-size: 0, so a surface can shrink inside grid and flex tracks and its content wraps.
  • In forced-colors mode the border becomes CanvasText, so the enclosure stays visible when backgrounds are removed.

Basic example

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

Canonical

Minimal surface

Rendered from the canonical pattern file.

Billing contact

Invoices are sent to the finance team on the first business day of each month.

HTML · Minimal surface Raw HTML for HTML · Minimal surface
<forma-surface class="forma-component-tag">
<section class="forma-surface" aria-labelledby="surface-title">
  <h2 id="surface-title">Billing contact</h2>
  <p>Invoices are sent to the finance team on the first business day of each month.</p>
</section>
</forma-surface>

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

Examples

Scenario

Billing summary panel

A surface on a section groups a heading, key facts and an action. The section supplies the landmark semantics and the surface supplies the boundary.

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.

Current plan

Plan
Team, 25 seats
Next invoice
, $1,250.00
Payment method
Visa ending 4242
HTML · Billing summary panel Raw HTML for HTML · Billing summary panel
<forma-surface class="forma-component-tag">
  <section class="forma-surface forma-stack" aria-labelledby="surface-billing-summary-title">
    <h2 id="surface-billing-summary-title">Current plan</h2>
    <dl class="forma-key-value-list">
      <div><dt>Plan</dt><dd>Team, 25 seats</dd></div>
      <div><dt>Next invoice</dt><dd><time datetime="2026-10-01">1 October 2026</time>, $1,250.00</dd></div>
      <div><dt>Payment method</dt><dd>Visa ending 4242</dd></div>
    </dl>
    <div class="forma-cluster"><button type="button">Change plan</button></div>
  </section>
</forma-surface>

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

Scenario

Compact panels in a dense list

Surfaces as list items with reduced padding (--forma-surface-space: 0.75rem). The border keeps adjacent items distinct even with a tight gap.

  • Expense report EX-4410 · Travel to Lisbon · $840.20
  • Purchase order PO-1188 · Laptop replacements · $6,300.00
  • Contract CN-207 · Cleaning services renewal · $12,000.00
HTML · Compact panels in a dense list Raw HTML for HTML · Compact panels in a dense list
<forma-surface class="forma-component-tag">
  <ul class="forma-stack" data-density="compact" aria-label="Pending approvals">
    <li class="forma-surface" style="--forma-surface-space: 0.75rem"><strong>Expense report EX-4410</strong> · Travel to Lisbon · $840.20</li>
    <li class="forma-surface" style="--forma-surface-space: 0.75rem"><strong>Purchase order PO-1188</strong> · Laptop replacements · $6,300.00</li>
    <li class="forma-surface" style="--forma-surface-space: 0.75rem"><strong>Contract CN-207</strong> · Cleaning services renewal · $12,000.00</li>
  </ul>
</forma-surface>

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

Scenario

Empty state inside a surface

A surface holding an empty result message and the action that resolves it. The panel keeps the empty region visibly bounded so it is not mistaken for missing page content.

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.

Scheduled reports

No reports are scheduled. Scheduled reports are emailed to you as PDF files.

HTML · Empty state inside a surface Raw HTML for HTML · Empty state inside a surface
<forma-surface class="forma-component-tag">
  <section class="forma-surface forma-stack" aria-labelledby="surface-nested-content-title">
    <h2 id="surface-nested-content-title">Scheduled reports</h2>
    <p>No reports are scheduled. Scheduled reports are emailed to you as PDF files.</p>
    <div class="forma-cluster"><button type="button">Schedule a report</button></div>
  </section>
</forma-surface>

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 panel

A surface at phone width with a long unbroken reference value. The panel fills the column and the value wraps inside the padding.

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.

What changes at narrow widths

  • The surface is as wide as its parent; padding stays at 1.5rem on every side, leaving the rest for content.
  • Long unbroken values wrap because Forma sets overflow-wrap: anywhere on text and the surface has min-inline-size: 0.
  • Actions inside keep their own minimum target sizes; the surface never compresses them.
  • Orientation changes only widen the panel.
HTML · Mobile panel Raw HTML for HTML · Mobile panel
<forma-surface class="forma-component-tag">
  <section class="forma-surface forma-stack" aria-labelledby="surface-mobile-panel-title">
    <h2 id="surface-mobile-panel-title">Webhook endpoint</h2>
    <p>https://hooks.example.com/services/T024BE7LD/B06Q8K3N1RX/9f8a7b6c5d4e3f2a1b0c</p>
    <div class="forma-cluster"><button type="button">Send test event</button></div>
  </section>
</forma-surface>

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 / articleid of the panel heading—Names a surface that is a landmark or named region.
aria-labelliststring—Names a list of surfaces.
style.forma-surface--forma-surface-space: <length>—Per-instance padding override.
data-densitysurrounding .forma-stackcompact—Used on the stack that spaces surfaces in the dense list example; it does not change surface padding.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-surfaceBlock class—Panel with secondary surface background, on-secondary text color, subtle 1px border and padding. Headings and paragraphs inside inherit its color.
--forma-surface-accent-text-colorCustom propertydefault var(--forma-color-text-primary, #161616)Color of links and accent labels inside a secondary surface. Every rule that paints the secondary surface sets it to --forma-color-text-primary and rebinds secondary and muted text to --forma-color-text-on-secondary-surface, because accent and secondary text are not AA-validated on that surface. Outside one, they use their accent role.
--forma-surface-spaceCustom property—Padding on all sides. Default --forma-primitive-spacing-5 (1.5rem).

Form behavior

Not a form control. A form can be a surface.

No keyboard interaction beyond the browser defaults for the elements in the markup.

States

Surface states
StateHow it is expressedPresentation
Default.forma-surfaceSecondary tone, subtle border, 1.5rem padding.
Forced colors@media (forced-colors: active)Border becomes CanvasText and the background resolves to Canvas, so the boundary stays visible.

Accessibility

Forma provides

  • Sets text color for the secondary surface so headings and body text keep their contrast.
  • Keeps the enclosure visible in forced-colors mode through a CanvasText border.
  • Adds no role; semantics come from the element it is applied to.

Your application supplies

  • Apply the surface to a semantic element (section, article, li, aside) and label regions with headings.
  • Do not use surface tone alone to convey status or selection.
  • Check contrast of any colored content placed on the secondary tone. Default links use the accent color, which measures about 4.4:1 on the default secondary surface, below the 4.5:1 text minimum; prefer buttons or restyle link color through a theme until this is resolved.

Responsive behavior

  • Fluid: fills its parent's inline size; no breakpoints.
  • min-inline-size: 0 lets surfaces shrink inside grids and flex rows, so long content wraps instead of overflowing.
  • Padding does not change with width; reduce --forma-surface-space for dense contexts.

Motion

  • No animation: the surface is static.

Usage guidance

Do

  • Use surfaces to separate peer panels in grids, rails and sidebars.
  • Combine with Stack to space the content inside.

Avoid

  • Nesting surfaces inside surfaces; the same tone and border stop reading as separate groups.
  • Using a surface where a card, callout or alert already carries the meaning.

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.