Feedback and status

Operation status

<forma-operation-status>

Presents pending, confirmed, failed, conflict, unknown, reconciling, stale, blocked, unavailable or insufficient outcomes with explanation and recovery actions.

Authoring tag
<forma-operation-status>
Behavior owner
Ordo / application
Canonical source
patterns/operation-status.html

Purpose

Operation status reports the outcome of one consequential operation, such as a save, payment or submission, when that outcome needs explaining. Forma renders a bordered block with a decorative symbol, a Status lozenge naming the state, a heading, an explanation of consequences, and an action row. The application or Ordo determines the state and which recovery actions are legal; Forma presents exactly what it is given and never upgrades unknown to failed or pending to confirmed.

Use when

  • An operation's outcome is not a simple success, for example it timed out and may or may not have happened.
  • Retrying naively could cause harm (a duplicate payment) and the user must reconcile first.
  • The application needs to show that an operation is pending, reconciling, blocked or unavailable, with the reason.

Avoid when

  • A plain success confirmation: use Toast or a short Alert.
  • Two versions of a record disagree and the user must compare them: use Conflict review.
  • Several distinct states must be shown side by side: use State survivability.
  • Work is still running with no outcome yet and no explanation needed: use Spinner or Progress bar.

Behavior to know

  • The lozenge text states the outcome; the heading explains it in a sentence; the paragraph says what is safe to do next.
  • Shares its grid and inline-start border with Alert, so it reads as feedback without depending on color.
  • Actions are supplied by the application and wrap in their own row.

Basic example

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

Canonical

Minimal operation status

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.

Unknown outcome

We cannot confirm whether the save completed

Reconcile the operation before retrying. Retrying immediately could create a duplicate effect.

HTML · Minimal operation status Raw HTML for HTML · Minimal operation status
<forma-operation-status class="forma-component-tag">
<section class="forma-operation-status" aria-labelledby="operation-title">
  <div class="forma-operation-status__symbol" aria-hidden="true">↻</div>
  <div>
    <span class="forma-status-lozenge" data-state="unknown">Unknown outcome</span>
    <h3 id="operation-title">We cannot confirm whether the save completed</h3>
    <p>Reconcile the operation before retrying. Retrying immediately could create a duplicate effect.</p>
  </div>
  <div class="forma-operation-status__actions">
    <button type="button">Reconcile</button>
    <button type="button">View details</button>
  </div>
</section>
</forma-operation-status>

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

Examples

Scenario

Payment declined

A confirmed failure. The lozenge says Failed, the text states that no money moved, and the only actions offered are the ones the application allows: update the card or choose another method.

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.

Failed

The card was declined

No payment was taken. Invoice INV-2291 remains open with 1,240.00 due.

HTML · Payment declined Raw HTML for HTML · Payment declined
<forma-operation-status class="forma-component-tag">
  <section class="forma-operation-status" aria-labelledby="operation-status-payment-failed-title">
    <div class="forma-operation-status__symbol" aria-hidden="true">×</div>
    <div>
      <span class="forma-status-lozenge" data-state="blocked">Failed</span>
      <h3 id="operation-status-payment-failed-title">The card was declined</h3>
      <p>No payment was taken. Invoice INV-2291 remains open with 1,240.00 due.</p>
    </div>
    <div class="forma-operation-status__actions">
      <button type="button">Update card</button>
      <button type="button">Pay another way</button>
    </div>
  </section>
</forma-operation-status>

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

Scenario

Reconciling after a timeout

The application is checking whether a timed-out transfer completed. A Spinner in the text column shows the check is running; there are no actions because retrying is not safe until reconciliation finishes.

Reconciling

Checking whether the transfer went through

The bank did not respond in time. We are confirming the outcome before allowing another attempt.

Contacting the bank

HTML · Reconciling after a timeout Raw HTML for HTML · Reconciling after a timeout
<forma-operation-status class="forma-component-tag">
  <section class="forma-operation-status" aria-labelledby="operation-status-reconciling-title">
    <div class="forma-operation-status__symbol" aria-hidden="true">↻</div>
    <div>
      <span class="forma-status-lozenge" data-state="unknown">Reconciling</span>
      <h3 id="operation-status-reconciling-title">Checking whether the transfer went through</h3>
      <p>The bank did not respond in time. We are confirming the outcome before allowing another attempt.</p>
      <p class="forma-spinner" role="status">
        <span class="forma-spinner__indicator" aria-hidden="true"></span>
        <span>Contacting the bank</span>
      </p>
    </div>
  </section>
</forma-operation-status>

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

Scenario

Blocked by a missing approval

The operation was not attempted because a prerequisite is missing. The lozenge says Blocked and the single action takes the user to request the approval.

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.

Blocked

Publishing needs a second approver

Policies above risk level 3 require approval from someone other than the author. Nothing has been published.

HTML · Blocked by a missing approval Raw HTML for HTML · Blocked by a missing approval
<forma-operation-status class="forma-component-tag">
  <section class="forma-operation-status" aria-labelledby="operation-status-blocked-by-permission-title">
    <div class="forma-operation-status__symbol" aria-hidden="true">!</div>
    <div>
      <span class="forma-status-lozenge" data-state="blocked">Blocked</span>
      <h3 id="operation-status-blocked-by-permission-title">Publishing needs a second approver</h3>
      <p>Policies above risk level 3 require approval from someone other than the author. Nothing has been published.</p>
    </div>
    <div class="forma-operation-status__actions">
      <button type="button">Request approval</button>
    </div>
  </section>
</forma-operation-status>

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 unknown outcome

The canonical unknown-outcome state 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

  • Below 40rem the three-column grid becomes one column: symbol, text, then actions.
  • Each action button becomes full width, giving large touch targets and preventing side-by-side mis-taps.
  • The heading and explanation wrap freely; nothing scrolls horizontally at 320px.
  • The lozenge stays on its own line above the heading in both orientations.
HTML · Mobile unknown outcome Raw HTML for HTML · Mobile unknown outcome
<forma-operation-status class="forma-component-tag">
  <section class="forma-operation-status" aria-labelledby="operation-status-mobile-unknown-save-title">
    <div class="forma-operation-status__symbol" aria-hidden="true">?</div>
    <div>
      <span class="forma-status-lozenge" data-state="unknown">Unknown outcome</span>
      <h3 id="operation-status-mobile-unknown-save-title">We cannot confirm the timesheet was submitted</h3>
      <p>The connection dropped during submission. Check the submission log before submitting again.</p>
    </div>
    <div class="forma-operation-status__actions">
      <button type="button">Check submission log</button>
      <button type="button">View details</button>
    </div>
  </section>
</forma-operation-status>

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-labelledbysection.forma-operation-statusid of the heading—Names the region by its heading.
aria-hidden.forma-operation-status__symboltrue—Hides the decorative symbol; the lozenge and heading carry the state.
data-state.forma-status-lozengeok | attention | unknown | blocked—Glyph for the lozenge that names the outcome. See Status lozenge.
rolean inner status elementstatus—Optional. Use a status region (for example a Spinner) for text that changes while the operation is reconciling.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-operation-statusBlock class—Root grid: symbol column, text column and action column, bordered with a thick inline-start border.
.forma-operation-status__actionsElement class—Wrapping flex row of application-supplied recovery actions. Buttons become full width below 40rem.
.forma-operation-status__symbolElement class—Bordered 2rem square holding a text glyph. Decorative.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the recovery actions. The region is not focusable.
Enter / SpaceActivates the focused action (native button behavior).
Events
EventDescription
clickNative click on action buttons. The application or Ordo performs and authorizes the action.

Form behavior

Not a form control.

States

Operation status states
StateHow it is expressedPresentation
Pendinglozenge text Pending, data-state="attention"Submitted but not yet confirmed by the authority.
Confirmedlozenge text Confirmed, data-state="ok"The authority confirmed the outcome.
Failedlozenge text Failed, data-state="blocked"The authority confirmed the operation did not happen.
Unknown / reconcilinglozenge text Unknown or Reconciling, data-state="unknown"The outcome is not established. Distinct from failed: retrying may duplicate the effect.
Conflict / stalelozenge text Conflict or Stale, data-state="attention"The operation was based on out-of-date information.
Blocked / unavailable / insufficientlozenge text naming the reason, data-state="blocked"The operation cannot proceed; the text says why and what would unblock it.

Accessibility

Forma provides

  • Expresses the state in text (lozenge and heading) with shape cues, independent of color.
  • Keeps the symbol decorative and actions as native buttons.
  • Uses a structural inline-start border that survives grayscale.

Your application supplies

  • Name the state exactly; do not collapse unknown into failed or pending into confirmed.
  • Offer only actions the authority allows in the current state; explain when none are available.
  • Insert or update a status region if the change must be announced; the section itself is not a live region.
  • Choose a heading level that fits the page outline.

Responsive behavior

  • Grid of auto minmax(0, 1fr) auto; the text column absorbs remaining width and wraps.
  • Below 40rem the grid is one column and every action button is full width.
  • The action row wraps before that breakpoint when actions are long.

Motion

  • No animation on the operation status itself. An embedded Spinner keeps its own cadence and stops when marked idle.

Usage guidance

Do

  • Say what did and did not happen, and what is safe to do next.
  • Replace the status as soon as the authority reports a new state.

Avoid

  • Offering Retry on an unknown outcome unless the operation is idempotent.
  • Using a generic "Something went wrong" when the application knows more.

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.