Workspaces and shells

Preview surface

<forma-preview-surface>

A bounded review surface for consequential content before an application commits or publishes it.

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

Purpose

A preview surface frames exactly what will be sent, published, issued or committed, so the user can review it before an application-owned operation. It has a header naming what is previewed with optional view controls, a tinted canvas that visually separates the previewed material from the application around it, and a footer that states the commit status and holds the next step. The frame is presentation only: showing a preview never means the operation is authorized, and the footer must say in text that nothing has been committed yet.

Use when

  • A user is about to publish, send, issue or commit content that others will see, such as an invoice, an announcement or a release note.
  • The previewed material should be visually distinct from the editing interface around it.
  • The user may want to check the material at different presentation sizes before continuing.

Avoid when

Behavior to know

  • The canvas uses the secondary surface color and responsive padding; an article inside it is a centered page up to 42rem wide.
  • Header and footer are flex rows that stack their parts at 40rem and below.
  • The footer is the place for the commit status in words and the next legal action supplied by the application.

Basic example

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

Canonical

Minimal preview surface

Rendered from the canonical pattern file.

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.

Preview

Customer invoice

Preview content

Architecture assessment

This surface shows the exact material the user is expected to review before a consequential operation.

Not yet committed
HTML · Minimal preview surface Raw HTML for HTML · Minimal preview surface
<forma-preview-surface class="forma-component-tag">
<section class="forma-preview-surface" aria-labelledby="preview-title">
  <header class="forma-preview-surface__header">
    <div><span class="forma-status-lozenge">Preview</span><h3 id="preview-title">Customer invoice</h3></div>
    <div class="forma-preview-surface__controls"><button type="button">Desktop</button><button type="button">Mobile</button></div>
  </header>
  <div class="forma-preview-surface__canvas">
    <article>
      <p class="forma-record-header__type">Preview content</p>
      <h2>Architecture assessment</h2>
      <p>This surface shows the exact material the user is expected to review before a consequential operation.</p>
    </article>
  </div>
  <footer class="forma-preview-surface__footer"><span>Not yet committed</span><button type="button">Continue review</button></footer>
</section>
</forma-preview-surface>

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

Examples

Scenario

Announcement before sending

An email announcement previewed before it goes to every customer. The view controls are toggle buttons with aria-pressed, the footer states the audience and that nothing has been sent, and the send action is a separate application-owned button.

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.

Preview

Maintenance announcement

Scheduled maintenance on 14 October

Hello, the dashboard will be read-only from 02:00 to 03:30 UTC while we upgrade our database. No data will be lost.

Not sent · 4,210 recipients
HTML · Announcement before sending Raw HTML for HTML · Announcement before sending
<forma-preview-surface class="forma-component-tag">
  <section class="forma-preview-surface" aria-labelledby="preview-surface-announcement-title">
    <header class="forma-preview-surface__header">
      <div><span class="forma-status-lozenge">Preview</span><h3 id="preview-surface-announcement-title">Maintenance announcement</h3></div>
      <div class="forma-preview-surface__controls" role="group" aria-label="Preview width">
        <button type="button" aria-pressed="true">Desktop</button>
        <button type="button" aria-pressed="false">Mobile</button>
      </div>
    </header>
    <div class="forma-preview-surface__canvas">
      <article aria-labelledby="preview-surface-announcement-subject">
        <h2 id="preview-surface-announcement-subject">Scheduled maintenance on 14 October</h2>
        <p>Hello, the dashboard will be read-only from 02:00 to 03:30 UTC while we upgrade our database. No data will be lost.</p>
      </article>
    </div>
    <footer class="forma-preview-surface__footer">
      <span>Not sent · 4,210 recipients</span>
      <button type="button">Send announcement</button>
    </footer>
  </section>
</forma-preview-surface>

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

Scenario

Preview with a blocking problem

The preview renders, but the application has found a problem that blocks publishing. The footer says so in text and offers only the legal next step; there is no disabled Publish button that looks available.

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.

Cannot publish

Release notes 4.2

What's new in 4.2

Bulk export now supports CSV and Parquet. See the migration guide for [missing link].

Not published · 1 broken link must be fixed first
HTML · Preview with a blocking problem Raw HTML for HTML · Preview with a blocking problem
<forma-preview-surface class="forma-component-tag">
  <section class="forma-preview-surface" aria-labelledby="preview-surface-blocked-publish-title">
    <header class="forma-preview-surface__header">
      <div><span class="forma-status-lozenge" data-state="blocked">Cannot publish</span><h3 id="preview-surface-blocked-publish-title">Release notes 4.2</h3></div>
    </header>
    <div class="forma-preview-surface__canvas">
      <article aria-labelledby="preview-surface-blocked-publish-heading">
        <h2 id="preview-surface-blocked-publish-heading">What's new in 4.2</h2>
        <p>Bulk export now supports CSV and Parquet. See the migration guide for [missing link].</p>
      </article>
    </div>
    <footer class="forma-preview-surface__footer">
      <span>Not published · 1 broken link must be fixed first</span>
      <button type="button">Return to editor</button>
    </footer>
  </section>
</forma-preview-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 invoice preview

At phone width the header and footer stack, the canvas padding shrinks and the previewed page fills the width.

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

  • At 40rem and below the header and footer switch to a stretched column, so the title, controls, status and action each take the full width.
  • Canvas and article padding use clamp() with 4vw, shrinking to 1rem each at 320px so the previewed content keeps most of the width.
  • Footer buttons keep the 2.75rem base height; stacked, they become full-width touch targets.
  • Very wide previewed content (tables, images) still needs its own Bounded overflow region inside the article.
HTML · Mobile invoice preview Raw HTML for HTML · Mobile invoice preview
<forma-preview-surface class="forma-component-tag">
  <section class="forma-preview-surface" aria-labelledby="preview-surface-mobile-title">
    <header class="forma-preview-surface__header">
      <div><span class="forma-status-lozenge">Preview</span><h3 id="preview-surface-mobile-title">Invoice INV-1042</h3></div>
    </header>
    <div class="forma-preview-surface__canvas">
      <article aria-labelledby="preview-surface-mobile-heading">
        <h2 id="preview-surface-mobile-heading">Acme Manufacturing</h2>
        <p>Consulting, September · $5,000.00 · due 4 October 2026</p>
      </article>
    </div>
    <footer class="forma-preview-surface__footer">
      <span>Not issued</span>
      <button type="button">Issue invoice</button>
    </footer>
  </section>
</forma-preview-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.

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.

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-labelledbyroot section, articleid of the preview title—Names the preview region by what is being previewed.
aria-pressedview control buttonstrue | false—Marks which preview width or mode is active. The application toggles it and changes the preview.
rolecontrols containergroup—Groups the view controls under one name.
aria-labelcontrols containerstring—Names the control group, for example "Preview width".
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-preview-surfaceBlock class—Root bordered region.
.forma-preview-surface__canvasElement class—Tinted, padded area that holds the previewed material. A direct article child is drawn as a centered page up to 42rem wide.
.forma-preview-surface__controlsElement class—Wrapping group of view controls in the header.
.forma-preview-surface__footerElement class—Commit status and next action; wraps and stacks at 40rem and below.
.forma-preview-surface__headerElement class—Title row with optional controls; a flex row that stacks at 40rem and below.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through header controls, any links inside the previewed content, then footer actions.
Enter / SpaceActivates the focused button. Native button behavior; the effect is application-owned.
Events
EventDescription
clickNative click on view controls and footer actions. The application changes the preview or performs the operation.

Form behavior

Not a form control. Footer actions may be submit buttons of an application form around the surface.

States

Preview surface states
StateHow it is expressedPresentation
Uncommittedfooter textThe footer states that the content has not yet been sent, published or issued.
Blockedstatus text and the actions the application rendersThe application explains the problem and offers only legal next steps.
View modearia-pressed on header controlsWhich presentation the preview is showing; application-owned.
Stacked chrome@media (max-width: 40rem)Header and footer items stack and stretch.

Accessibility

Forma provides

  • Separates previewed material from the application with a border, a tinted canvas and a page frame, not with color alone.
  • Keeps header and footer controls at the base 2.75rem height and stacks them on narrow screens.

Your application supplies

  • State the commit status in words in the footer, such as "Not sent" or "Not published".
  • Name the region by what is previewed and keep heading levels inside the previewed article sensible.
  • Do not show an action the user is not allowed to take; the preview never implies authorization.
  • If the preview can be out of date, say so and offer a refresh.

Responsive behavior

  • Header and footer are wrapping flex rows with space between; at 40rem and below they stack with align-items: stretch.
  • Canvas padding is clamp(1rem, 4vw, 3rem) and the article's padding clamp(1rem, 4vw, 2.5rem).
  • The previewed article is capped at 42rem and centered, approximating a document page.
  • Simulating a mobile width (the Mobile control) is application behavior; Forma does not resize the canvas.

Motion

  • No animation: the surface is static. Header and footer buttons use only the base perceptual hover and press color change.

Usage guidance

Do

  • Preview the exact output, generated by the same code path that will produce the committed version.
  • Name the audience or scope next to the action ("4,210 recipients").

Avoid

  • Styling the preview as if it were already published.
  • Putting the commit action in the header, where it can be mistaken for a view control.

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.