Feedback and status

Start-up screen

<forma-startup>

The first thing a script- or WebAssembly-driven application shows: its identity, indeterminate activity and a meaningful status, rendered from the initial HTML before any runtime exists, with slow, failed, timed-out and no-script states.

Authoring tag
<forma-startup>
Behavior owner
Application state
Canonical source
patterns/startup.html

Purpose

A start-up screen covers the time between the first HTML arriving and the application's own runtime taking over. It is authored in the initial HTML and needs only Forma CSS, so it is visible while a WebAssembly or script bundle is still downloading. It shows the application's identity, an indeterminate activity indicator with a status sentence that says what is starting, and a note that appears by itself if the start is slow. The host page's loader marks a failed or timed-out start and the screen replaces the activity with an explanation and a recovery action. The application removes the screen, or sets hidden, once it has mounted.

Use when

  • An application renders its interface from WebAssembly or a script bundle, leaving the page blank until it runs.
  • Start-up can be slow on some connections or devices and the person needs to know the page is working.

Avoid when

  • The page is server-rendered and usable as it arrives: show its content instead.
  • Loading data inside a running application: use Skeleton for a region or Spinner for an action, and keep the shell.
  • Work with measurable progress: use Progress bar. The start-up screen never shows a percentage it does not have.

Behavior to know

  • Zero runtime: identity, indicator and status render from HTML and CSS alone. Use an inline SVG mark so the identity needs no request either.
  • The status sentence names the application and the work, never the word Loading alone.
  • The slow-start note is revealed after --forma-startup-slow-after (default 8s) without script, and at once when the host sets data-forma-state="slow".
  • Failed and timed-out states remove the indicator and show the problem with a recovery action, so nothing spins forever.
  • With scripting turned off, the screen says what the application needs instead of starting.

Basic example

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

Canonical

Minimal start-up screen

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.

Northwind Ledger

Starting Northwind Ledger: preparing your workspace

Still starting. A slow connection can take up to a minute.

Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.

HTML · Minimal start-up screen Raw HTML for HTML · Minimal start-up screen
<forma-startup class="forma-component-tag">
<div class="forma-startup" id="app-startup" data-forma-state="starting">
  <span class="forma-app-identity" data-forma-size="64">
    <span class="forma-app-identity__mark">
      <svg viewBox="0 0 32 32" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M6 0h20a6 6 0 0 1 6 6v20a6 6 0 0 1-6 6H6a6 6 0 0 1-6-6V6a6 6 0 0 1 6-6Zm10 8-8 14h16Z"/></svg>
    </span>
    <span class="forma-app-identity__name">Northwind Ledger</span>
  </span>
  <div class="forma-startup__status" role="status">
    <p class="forma-spinner">
      <span class="forma-spinner__indicator" aria-hidden="true"></span>
      <span class="forma-spinner__label">Starting Northwind Ledger: preparing your workspace</span>
    </p>
    <p class="forma-startup__slow">Still starting. A slow connection can take up to a minute.</p>
  </div>
  <div class="forma-startup__problem" role="alert">
    <p class="forma-startup__problem-title">Northwind Ledger could not start.</p>
    <p>Your work is not affected. Reload the page to try again.</p>
    <a class="forma-button" href="">Reload</a>
  </div>
  <p class="forma-startup__noscript">Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.</p>
</div>
</forma-startup>

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

Examples

Scenario

Slow connection: still starting

The host marked the start as slow (data-forma-state="slow"), so the "still starting" note is visible at once. Without the attribute the same note appears by itself after --forma-startup-slow-after (8 seconds), with no script. Setting the attribute makes the announcement dependable, because the note then changes inside the status region.

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.

Northwind Ledger

Starting Northwind Ledger: preparing your workspace

Still starting. A slow connection can take up to a minute.

Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.

HTML · Slow connection: still starting Raw HTML for HTML · Slow connection: still starting
<forma-startup class="forma-component-tag">
  <div class="forma-startup" data-forma-extent="region" data-forma-state="slow">
    <span class="forma-app-identity" data-forma-size="64">
      <span class="forma-app-identity__mark">
        <svg viewBox="0 0 32 32" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M6 0h20a6 6 0 0 1 6 6v20a6 6 0 0 1-6 6H6a6 6 0 0 1-6-6V6a6 6 0 0 1 6-6Zm10 8-8 14h16Z"/></svg>
      </span>
      <span class="forma-app-identity__name">Northwind Ledger</span>
    </span>
    <div class="forma-startup__status" role="status">
      <p class="forma-spinner">
        <span class="forma-spinner__indicator" aria-hidden="true"></span>
        <span class="forma-spinner__label">Starting Northwind Ledger: preparing your workspace</span>
      </p>
      <p class="forma-startup__slow">Still starting. A slow connection can take up to a minute.</p>
    </div>
    <div class="forma-startup__problem" role="alert">
      <p class="forma-startup__problem-title">Northwind Ledger could not start.</p>
      <p>A required file did not load. Your work is not affected.</p>
      <div class="forma-actions">
        <a class="forma-button" href="#startup-slow">Reload</a>
      </div>
    </div>
    <p class="forma-startup__noscript">Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.</p>
  </div>
</forma-startup>

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

Scenario

Runtime failed to load

The host caught a failed download and set data-forma-state="failed". The activity indicator and status are removed so nothing keeps spinning, and the alert explains the failure and offers a reload. Do not offer retry or cancel actions the application cannot perform safely.

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.

Northwind Ledger

Starting Northwind Ledger: preparing your workspace

Still starting. A slow connection can take up to a minute.

Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.

HTML · Runtime failed to load Raw HTML for HTML · Runtime failed to load
<forma-startup class="forma-component-tag">
  <div class="forma-startup" data-forma-extent="region" data-forma-state="failed">
    <span class="forma-app-identity" data-forma-size="64">
      <span class="forma-app-identity__mark">
        <svg viewBox="0 0 32 32" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M6 0h20a6 6 0 0 1 6 6v20a6 6 0 0 1-6 6H6a6 6 0 0 1-6-6V6a6 6 0 0 1 6-6Zm10 8-8 14h16Z"/></svg>
      </span>
      <span class="forma-app-identity__name">Northwind Ledger</span>
    </span>
    <div class="forma-startup__status" role="status">
      <p class="forma-spinner">
        <span class="forma-spinner__indicator" aria-hidden="true"></span>
        <span class="forma-spinner__label">Starting Northwind Ledger: preparing your workspace</span>
      </p>
      <p class="forma-startup__slow">Still starting. A slow connection can take up to a minute.</p>
    </div>
    <div class="forma-startup__problem" role="alert">
      <p class="forma-startup__problem-title">Northwind Ledger could not start.</p>
      <p>A required file did not load. Your work is not affected.</p>
      <div class="forma-actions">
        <a class="forma-button" href="#startup-failed">Reload</a>
      </div>
    </div>
    <p class="forma-startup__noscript">Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.</p>
  </div>
</forma-startup>

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

Scenario

Start timed out

The host gave up after its own deadline and set data-forma-state="timed-out". It is presented like a failure but says the application ran out of time, which tells the person that reloading may work.

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.

Northwind Ledger

Starting Northwind Ledger: preparing your workspace

Still starting. A slow connection can take up to a minute.

Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.

HTML · Start timed out Raw HTML for HTML · Start timed out
<forma-startup class="forma-component-tag">
  <div class="forma-startup" data-forma-extent="region" data-forma-state="timed-out">
    <span class="forma-app-identity" data-forma-size="64">
      <span class="forma-app-identity__mark">
        <svg viewBox="0 0 32 32" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M6 0h20a6 6 0 0 1 6 6v20a6 6 0 0 1-6 6H6a6 6 0 0 1-6-6V6a6 6 0 0 1 6-6Zm10 8-8 14h16Z"/></svg>
      </span>
      <span class="forma-app-identity__name">Northwind Ledger</span>
    </span>
    <div class="forma-startup__status" role="status">
      <p class="forma-spinner">
        <span class="forma-spinner__indicator" aria-hidden="true"></span>
        <span class="forma-spinner__label">Starting Northwind Ledger: preparing your workspace</span>
      </p>
      <p class="forma-startup__slow">Still starting. A slow connection can take up to a minute.</p>
    </div>
    <div class="forma-startup__problem" role="alert">
      <p class="forma-startup__problem-title">Northwind Ledger is taking too long to start.</p>
      <p>The application did not finish loading in 60 seconds. Your work is not affected.</p>
      <div class="forma-actions">
        <a class="forma-button" href="#startup-timed-out">Reload</a>
      </div>
    </div>
    <p class="forma-startup__noscript">Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.</p>
  </div>
</forma-startup>

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

Phone start-up

The start-up surface at phone 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

  • The identity, status and actions stack in one centered column capped at 36rem, so nothing scrolls sideways at 320 pixels.
  • The 64 pixel mark keeps its size; long application names wrap below it.
  • The reload action is a full-size link button when a failure is shown.
HTML · Phone start-up Raw HTML for HTML · Phone start-up
<forma-startup class="forma-component-tag">
  <div class="forma-startup" data-forma-extent="region" data-forma-state="starting">
    <span class="forma-app-identity" data-forma-size="64">
      <span class="forma-app-identity__mark">
        <svg viewBox="0 0 32 32" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M6 0h20a6 6 0 0 1 6 6v20a6 6 0 0 1-6 6H6a6 6 0 0 1-6-6V6a6 6 0 0 1 6-6Zm10 8-8 14h16Z"/></svg>
      </span>
      <span class="forma-app-identity__name">Northwind Ledger</span>
    </span>
    <div class="forma-startup__status" role="status">
      <p class="forma-spinner">
        <span class="forma-spinner__indicator" aria-hidden="true"></span>
        <span class="forma-spinner__label">Starting Northwind Ledger: preparing your workspace</span>
      </p>
      <p class="forma-startup__slow">Still starting. A slow connection can take up to a minute.</p>
    </div>
    <div class="forma-startup__problem" role="alert">
      <p class="forma-startup__problem-title">Northwind Ledger could not start.</p>
      <p>A required file did not load. Your work is not affected.</p>
      <div class="forma-actions">
        <a class="forma-button" href="#startup-starting">Reload</a>
      </div>
    </div>
    <p class="forma-startup__noscript">Northwind Ledger needs JavaScript and WebAssembly. Turn them on in your browser settings, then reload this page.</p>
  </div>
</forma-startup>

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
data-forma-state.forma-startupstarting | slow | failed | timed-outstartingSet by the host page's loader. slow shows the slow-start note at once; failed and timed-out replace the status with the problem region.
data-forma-extent.forma-startupregionabsent (fills the viewport)Sizes the screen to a 16rem region instead of the full viewport, for an embedded application or a documentation preview.
role.forma-startup__statusstatus—Polite live region that holds the activity sentence and the slow-start note.
role.forma-startup__problemalert—Announces the failure or timeout when the host writes or reveals it.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-startupBlock class—Root: a centered single column filling the viewport (or a region) on the primary surface.
.forma-startup__noscriptElement class—Shown instead of the status when scripting is unavailable (the scripting: none media query).
.forma-startup__problemElement class—Failure or timeout explanation and recovery action; shown only in the failed and timed-out states.
.forma-startup__problem-titleElement class—The bold first line of the problem region.
.forma-startup__slowElement class—The slow-start note. Space is reserved for it, so its appearance does not move the layout.
.forma-startup__statusElement class—The live status: an Spinner with the activity sentence and the slow-start note.
[data-forma-extent]Attribute hook"region"Viewport or region sizing.
[data-forma-state]Attribute hook"failed", "slow", "timed-out"The host-owned state selector.
[hidden]Attribute hook—.forma-startup[hidden] restores display: none, which the root's grid display would otherwise override. Set it, or remove the element, once the application has mounted.
--forma-startup-slow-afterCustom propertydefault 8sDelay before the slow-start note appears without host help. Default 8s.
Keyboard interaction
KeysResult
TabNothing is focusable while starting; focus is not trapped. In failed and timed-out states Tab reaches the recovery action.
EnterActivates the recovery action.
Events
EventDescription
—None. The host page's loader sets data-forma-state, and the application removes or hides the screen when it mounts.

Form behavior

Not a form control.

States

Start-up screen states
StateHow it is expressedPresentation
Startingdata-forma-state="starting" or absentIdentity, spinning indicator and the status sentence.
Slowdata-forma-state="slow", or --forma-startup-slow-after elapsedThe slow-start note appears below the status sentence in reserved space.
Faileddata-forma-state="failed"Status and indicator are removed; the alert explains the failure and offers recovery.
Timed outdata-forma-state="timed-out"As failed, with wording that says the start ran out of time.
No scripting@media (scripting: none)Status and problem are removed; the no-script message says what to turn on.
Reduced motionprefers-reduced-motion: reduceThe indicator is a static ring; the status sentence still identifies the activity and the slow-start note still appears.
Mountedelement removed or hiddenThe application replaces the screen.

Accessibility

Forma provides

  • Puts the activity sentence and slow-start note in one polite status region, so a slow start is announced once rather than on every animation frame.
  • Removes the indicator in failed and timed-out states, so animation never contradicts the failure.
  • Shows a static indicator under reduced motion while the text keeps identifying the activity.
  • Traps no focus; the only focusable element appears with the recovery action.

Your application supplies

  • Name the application and the work in the status sentence (Starting Northwind Ledger: preparing your workspace), not Loading alone.
  • Set data-forma-state from the loader on a real failure or your own deadline; write the problem text into the alert when you reveal it so it is announced.
  • Offer only recovery actions the application can perform safely; reload is usually the only one before the runtime exists.
  • Remove or hide the screen once the application has mounted and move focus to the application's main heading if focus was on the page body.

Responsive behavior

  • A single centered column capped at 36rem; it never scrolls sideways at 320 pixels.
  • Fills the small viewport height (100svh) so mobile browser chrome does not cut off the status.
  • data-forma-extent="region" sizes it for embedded use.

Motion

  • The indicator is the shared Spinner cadence: one constant-velocity turn per --forma-motion-cadence-rotation-period.
  • The slow-start note is a discrete reveal after a delay, not motion; it is not removed by reduced motion.
  • No progress percentage, stage list or estimated time is ever animated.

Usage guidance

Do

  • Put the screen in the initial HTML of the page the runtime mounts into, so it paints with the first frame.
  • Use the same identity as the shell header, so the person sees one application from first paint to mounted interface.

Avoid

  • Fake progress bars or stages that do not report real work.
  • Leaving the indicator running after the loader has failed or given up.

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.