Faults and recovery

Fault banner

<forma-fault-banner>

Persistent page/application banner for degraded or critical Aegis conditions.

Authoring tag
<forma-fault-banner>
Behavior owner
Application / Limen
Canonical source
patterns/fault-banner.html

Purpose

A fault banner presents an Aegis presentation whose intent is Banner: a condition that affects the whole page or application, such as degraded storage or a read-only mode, and that persists for as long as the application reports it. It composes the alert surface (forma-alert) with the fault vocabulary and stays in normal page flow at full width, usually at the top of the main content. The application inserts it once, keeps it while the condition holds, and removes it when Aegis reports the condition resolved. Visual weight reflects the Critical severity text; it is never inferred from placement.

Use when

  • Aegis reports intent Banner for a condition that affects everything on the page, not one control.
  • The application keeps working in a degraded state and the user needs a durable reminder plus the legal recovery actions.
  • The condition should remain visible while the user navigates within the affected area.

Avoid when

  • The fault is local to one operation or field: use Fault inline.
  • The fault happened in the background and can be dismissed: use Fault notification.
  • The application cannot continue safely: use Fault blocking.
  • The message is general page status or an announcement with no Aegis fault behind it: use Alert or Callout.

Behavior to know

  • Full-width, in-flow surface; it pushes content down instead of overlaying it.
  • Severity is visible text; Critical additionally thickens the top and bottom borders.
  • Animates only on first insertion (a short fade and settle), never on rerender.
  • Uses role="status" for the first insertion only; a persistent banner must not announce again on every render.

Basic example

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

Canonical

Minimal fault banner

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.

HTML · Minimal fault banner Raw HTML for HTML · Minimal fault banner
<forma-fault-banner class="forma-component-tag">
<aside
  class="forma-alert forma-fault-banner"
  role="status"
  data-forma-intent="banner"
  data-forma-severity="critical"
  data-forma-motion-weight="standard"
  data-forma-motion-entry
  aria-labelledby="fault-banner-title">
  <div class="forma-alert__icon forma-fault-banner__marker" aria-hidden="true">!!</div>
  <div class="forma-fault-banner__body">
    <p class="forma-fault__severity">Critical</p>
    <h2 class="forma-alert__title" id="fault-banner-title">Diagnostics storage is unavailable</h2>
    <p>The application is running in a degraded state. New diagnostics are queued locally.</p>
    <p class="forma-fault-reference">Reference <code>AG-22K8M</code></p>
  </div>
  <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
    <button type="button" data-forma-aegis-capability="CanRestoreSink">Reconnect diagnostics</button>
  </div>
</aside>
</forma-fault-banner>

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

Examples

Scenario

Degraded read-only mode

An error-severity banner above a workspace while the storage service is unavailable. Aegis supplied Reload as the only recovery action. Error severity keeps the standard 2px block borders.

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.

HTML · Degraded read-only mode Raw HTML for HTML · Degraded read-only mode
<forma-fault-banner class="forma-component-tag">
  <aside class="forma-alert forma-fault-banner" role="status" data-forma-intent="banner" data-forma-severity="error" data-forma-motion-entry aria-labelledby="fault-banner-read-only-mode-title">
    <div class="forma-alert__icon" aria-hidden="true">!</div>
    <div class="forma-fault-banner__body">
      <p class="forma-fault__severity">Error</p>
      <h2 class="forma-alert__title" id="fault-banner-read-only-mode-title">Changes cannot be saved right now</h2>
      <p>Document storage is unavailable. You can keep reading; editing is paused until storage returns.</p>
      <p class="forma-fault-reference">Reference <code>AG-6YH2D</code></p>
    </div>
    <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
      <button type="button" data-forma-aegis-capability="CanReload">Reload</button>
    </div>
  </aside>
</forma-fault-banner>

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

Scenario

Persisting warning after rerender

The same condition shown on the next page of the application. The banner has no role and no data-forma-motion-entry, so it neither re-announces nor animates. Aegis supplied no recovery action.

HTML · Persisting warning after rerender Raw HTML for HTML · Persisting warning after rerender
<forma-fault-banner class="forma-component-tag">
  <aside class="forma-alert forma-fault-banner" data-forma-intent="banner" data-forma-severity="warning" aria-labelledby="fault-banner-rerendered-warning-title">
    <div class="forma-alert__icon" aria-hidden="true">!</div>
    <div class="forma-fault-banner__body">
      <p class="forma-fault__severity">Warning</p>
      <h2 class="forma-alert__title" id="fault-banner-rerendered-warning-title">Payment confirmations are delayed</h2>
      <p>Orders are accepted normally. Confirmation emails may arrive up to an hour late.</p>
      <p class="forma-fault-reference">Reference <code>AG-40RQN</code></p>
    </div>
  </aside>
</forma-fault-banner>

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

Scenario

Critical condition with two recovery paths

Critical severity thickens the top and bottom borders to 3px. Two Aegis capabilities are offered in the order supplied; neither is a bypass.

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.

HTML · Critical condition with two recovery paths Raw HTML for HTML · Critical condition with two recovery paths
<forma-fault-banner class="forma-component-tag">
  <aside class="forma-alert forma-fault-banner" role="status" data-forma-intent="banner" data-forma-severity="critical" data-forma-motion-entry aria-labelledby="fault-banner-critical-two-actions-title">
    <div class="forma-alert__icon" aria-hidden="true">!!</div>
    <div class="forma-fault-banner__body">
      <p class="forma-fault__severity">Critical</p>
      <h2 class="forma-alert__title" id="fault-banner-critical-two-actions-title">Your permissions could not be verified</h2>
      <p>Actions that change records are disabled until your access is confirmed.</p>
      <p class="forma-fault-reference">Reference <code>AG-5ZE7K</code></p>
    </div>
    <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
      <button type="button" data-forma-aegis-capability="CanReauthenticate">Sign in</button>
      <button type="button" data-forma-aegis-capability="CanReload">Reload</button>
    </div>
  </aside>
</forma-fault-banner>

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

Diagnostics banner on a phone

A critical banner at the top of a phone layout, with its recovery action below the text.

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 36rem the three-column grid (icon, body, actions) becomes two columns; the recovery group moves to its own full-width row beneath the body without changing reading order.
  • The recovery button becomes full width with a 44px minimum height.
  • The banner stays in page flow at 100% width, so it scrolls away with content rather than covering it.
  • Long titles and references wrap; there is no horizontal scrolling at 320px in either orientation.
HTML · Diagnostics banner on a phone Raw HTML for HTML · Diagnostics banner on a phone
<forma-fault-banner class="forma-component-tag">
  <aside class="forma-alert forma-fault-banner" role="status" data-forma-intent="banner" data-forma-severity="critical" data-forma-motion-entry aria-labelledby="fault-banner-mobile-diagnostics-title">
    <div class="forma-alert__icon" aria-hidden="true">!!</div>
    <div class="forma-fault-banner__body">
      <p class="forma-fault__severity">Critical</p>
      <h2 class="forma-alert__title" id="fault-banner-mobile-diagnostics-title">Diagnostics storage is unavailable</h2>
      <p>New diagnostics are queued on this device.</p>
      <p class="forma-fault-reference">Reference <code>AG-22K8M</code></p>
    </div>
    <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
      <button type="button" data-forma-aegis-capability="CanRestoreSink">Reconnect diagnostics</button>
    </div>
  </aside>
</forma-fault-banner>

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
roleaside.forma-fault-bannerstatusabsentUse for the first insertion only. Omit it when the same banner is re-rendered so it does not announce again.
aria-labelledbyaside.forma-fault-bannerid of .forma-alert__title—Names the complementary region by the banner title.
data-forma-severityaside.forma-fault-bannerdiagnostic | warning | error | critical—Aegis severity. critical thickens the block borders; always paired with visible severity text.
data-forma-intentaside.forma-fault-bannerbanner—Records the Aegis intent. Descriptive only.
data-forma-motion-entryaside.forma-fault-bannerbooleanabsentOpts into the insertion fade and settle. Add it only on the first render.
data-forma-motion-weightaside.forma-fault-bannerlight | standard | heavystandardPresentation-only perceived mass for the entry settle. Keep the standard default; it never reflects severity.
aria-hidden.forma-alert__icontrue—Hides the decorative marker glyph.
aria-label.forma-recovery-actionsstring—Names the recovery group.
typebuttonbutton—Required on recovery buttons.
data-forma-aegis-capabilitybuttonAegis capability name—Exact Aegis capability identity; the application revalidates it on click.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-fault-bannerBlock class—Root, applied together with forma-alert. A full-width icon/body/actions grid with 1px inline borders and 2px block borders.
.forma-fault-banner__bodyElement class—Text column for severity, title, message and reference; shrinks to zero minimum width so text wraps.
[data-forma-motion-entry]Attribute hook—Enables the one-time insertion transition: opacity from 0 and a 0.3rem downward settle via @starting-style.
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Selects the light, standard (default) or heavy physics preset for the settle duration. Presentation only.
[data-forma-severity]Attribute hook"critical"The value critical increases the block (top and bottom) border width from 2px to 3px.
Keyboard interaction
KeysResult
Tab / Shift+TabReaches the recovery buttons in source order. The banner never takes focus when it appears.
Enter / SpaceActivates the focused recovery button (native button behavior).
Events
EventDescription
clickNative click on a recovery button, which the application revalidates and translates into a typed recovery request.

Form behavior

Not a form control. Recovery buttons are type="button".

States

Fault banner states
StateHow it is expressedPresentation
Insertedrole="status" + data-forma-motion-entry on first renderAnnounced once and settles into place.
Persistingno role and no data-forma-motion-entry on later rendersVisually identical, silent and static.
Criticaldata-forma-severity="critical" plus the text Critical3px top and bottom borders in addition to the text label.
Other severitiesdata-forma-severity="diagnostic|warning|error" plus textStandard 2px block borders; the text label carries the level.
No recoveryomit .forma-recovery-actionsOnly the explanation and reference are shown.

Accessibility

Forma provides

  • Provides visible severity text and a decorative icon marker; border thickness for Critical is an additional non-color cue.
  • Keeps recovery buttons native, focus-visible and at least 44px tall.
  • Keeps borders, icon and text visible in forced-colors mode (Canvas/CanvasText, no shadow).
  • Limits motion to a single insertion transition that collapses under reduced motion.

Your application supplies

  • Insert the banner once with role="status"; re-render it without the role so it does not announce repeatedly.
  • Place it at the top of the affected content in source order, and keep it while the condition persists.
  • Supply only Aegis recovery actions and revalidate them on click; never add a bypass.
  • Remove it when Aegis reports the condition resolved or superseded.

Responsive behavior

  • The banner is inline-size: 100% in page flow; it never overlays content.
  • The grid is icon, flexible body and actions; below a 36rem viewport the actions move to a full-width row under the body.
  • Recovery buttons become full width at the same breakpoint; each keeps a 44px minimum height.
  • Titles, messages and reference codes wrap without horizontal overflow at 320px.

Motion

  • With data-forma-motion-entry, the banner fades in and settles 0.3rem downward on first render (perceptual opacity plus damped inertial translate).
  • Standard perceived weight is the default; weight never encodes severity.
  • Because @starting-style applies only when the element first appears, re-rendered banners without the attribute do not animate.
  • Under prefers-reduced-motion: reduce durations collapse to 0.01ms and the banner appears in place.

Motion weights

Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:

lightpresentation only
standardpresentation only
heavypresentation only

Usage guidance

Do

  • Explain what still works and what is paused.
  • Keep one banner per condition; update its text when Aegis updates the presentation.
  • Show the reference so users can quote it.

Avoid

  • Stacking several banners for the same underlying condition.
  • Re-adding role="status" or data-forma-motion-entry on every render.
  • Offering Continue anyway or other actions Aegis did not supply.

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.