Faults and recovery

Fault notification

<forma-fault-notification>

Persistent, dismissible notification surface for Aegis Notification intent; lifecycle remains application-owned.

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

Purpose

A fault notification presents an Aegis presentation whose intent is Notification: something failed that the user should know about even though they are not looking at the affected region, such as a background synchronization. It composes the toast surface (forma-toast) with the fault vocabulary: marker, visible severity, title, message, reference, Aegis-supplied recovery actions and an optional dismiss button. Forma runs no timers and owns no lifecycle. The application inserts the notification, decides whether it is dismissible, handles the dismiss click, throttles repeats and removes it when Aegis reports the fault resolved.

Use when

  • Aegis reports intent Notification for a failure outside the user's current focus, such as a background save, sync or export.
  • The user can continue working, but should be able to recover or quote the reference.
  • The application inserts a genuinely new notification and wants one polite announcement.

Avoid when

  • The fault belongs to a control or region on screen: use Fault inline next to it.
  • The condition persists for the whole page or application: use Fault banner.
  • Work cannot continue: use Fault blocking.
  • The message is a transient success or neutral confirmation rather than an Aegis fault: use Toast.
  • You need auto-dismissal for an actionable fault; Forma does not provide timers and actionable faults should persist.

Behavior to know

  • Persistent by default: nothing in Forma dismisses it, and actionable faults should stay until dismissed or resolved.
  • Uses role="status" only when the application inserts a new notification; rerenders of an existing one should not announce again.
  • The dismiss button is an ordinary native button; hover is never required to inspect, pause, dismiss or recover.
  • Enters with the standard perceived motion weight (a short fade and a small downward settle); motion never encodes severity.

Basic example

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

Canonical

Minimal fault notification

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 notification Raw HTML for HTML · Minimal fault notification
<forma-fault-notification class="forma-component-tag">
<aside
  class="forma-toast forma-fault-notification"
  role="status"
  data-forma-intent="notification"
  data-forma-severity="warning"
  data-forma-motion-weight="standard"
  data-forma-motion-entry
  aria-labelledby="fault-notification-title">
  <div class="forma-fault-notification__marker" aria-hidden="true">!</div>
  <div class="forma-fault-notification__body">
    <p class="forma-fault__severity">Warning</p>
    <h3 class="forma-toast__title" id="fault-notification-title">GitHub is temporarily unavailable</h3>
    <p>Your work is still local. You can retry the synchronization.</p>
    <p class="forma-fault-reference">Reference <code>AG-91B7Q</code></p>
    <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
      <button type="button" data-forma-aegis-capability="CanRetry">Try again</button>
    </div>
  </div>
  <button type="button" class="forma-fault-notification__dismiss" data-forma-action="dismiss" aria-label="Dismiss notification">Close</button>
</aside>
</forma-fault-notification>

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

Examples

Scenario

Background sync needs sign-in

An error raised by a background synchronization. Aegis supplied the Sign in capability. The dismiss button's accessible name starts with its visible label, so speech users can say "Dismiss".

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 · Background sync needs sign-in Raw HTML for HTML · Background sync needs sign-in
<forma-fault-notification class="forma-component-tag">
  <aside class="forma-toast forma-fault-notification" role="status" data-forma-intent="notification" data-forma-severity="error" data-forma-motion-weight="standard" data-forma-motion-entry aria-labelledby="fault-notification-reauthenticate-title">
    <div class="forma-fault-notification__marker" aria-hidden="true">!</div>
    <div class="forma-fault-notification__body">
      <p class="forma-fault__severity">Error</p>
      <h3 class="forma-toast__title" id="fault-notification-reauthenticate-title">Calendar sync stopped</h3>
      <p>Your sign-in to the calendar service expired. Events created since 09:40 are stored on this device.</p>
      <p class="forma-fault-reference">Reference <code>AG-8LM3E</code></p>
      <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
        <button type="button" data-forma-aegis-capability="CanReauthenticate">Sign in</button>
      </div>
    </div>
    <button type="button" class="forma-fault-notification__dismiss" data-forma-action="dismiss" aria-label="Dismiss calendar sync notification">Dismiss</button>
  </aside>
</forma-fault-notification>

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

Scenario

Restored notification without re-announcement

A diagnostic notification re-rendered after navigation. It has no role=status because it was already announced when first inserted, no recovery actions because Aegis supplied none, and no data-forma-motion-entry so it does not animate again.

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 · Restored notification without re-announcement Raw HTML for HTML · Restored notification without re-announcement
<forma-fault-notification class="forma-component-tag">
  <aside class="forma-toast forma-fault-notification" data-forma-intent="notification" data-forma-severity="diagnostic" aria-labelledby="fault-notification-informational-rerender-title">
    <div class="forma-fault-notification__marker" aria-hidden="true">i</div>
    <div class="forma-fault-notification__body">
      <p class="forma-fault__severity">Diagnostic</p>
      <h3 class="forma-toast__title" id="fault-notification-informational-rerender-title">Search index is rebuilding</h3>
      <p>Results may miss documents added in the last few minutes.</p>
      <p class="forma-fault-reference">Reference <code>AG-1B9SW</code></p>
    </div>
    <button type="button" class="forma-fault-notification__dismiss" data-forma-action="dismiss" aria-label="Dismiss search index notification">Dismiss</button>
  </aside>
</forma-fault-notification>

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

Scenario

Critical notification that cannot be dismissed

Current application policy does not allow dismissal while diagnostics are disconnected, so no dismiss button is rendered. The only way forward is the Aegis-supplied recovery action or resolution upstream.

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 notification that cannot be dismissed Raw HTML for HTML · Critical notification that cannot be dismissed
<forma-fault-notification class="forma-component-tag">
  <aside class="forma-toast forma-fault-notification" role="status" data-forma-intent="notification" data-forma-severity="critical" data-forma-motion-entry aria-labelledby="fault-notification-not-dismissible-title">
    <div class="forma-fault-notification__marker" aria-hidden="true">!!</div>
    <div class="forma-fault-notification__body">
      <p class="forma-fault__severity">Critical</p>
      <h3 class="forma-toast__title" id="fault-notification-not-dismissible-title">Diagnostics are disconnected</h3>
      <p>New reports are held on this device until the diagnostics service is reachable.</p>
      <p class="forma-fault-reference">Reference <code>AG-22K8M</code></p>
      <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
        <button type="button" data-forma-aegis-capability="CanRestoreSink">Reconnect diagnostics</button>
      </div>
    </div>
  </aside>
</forma-fault-notification>

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

Sync failure on a phone

A warning notification at phone width with a recovery action and a dismiss control.

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 fixed to the bottom inline-end corner with a 1rem inset (respecting the safe-area inset) and is at most the viewport width minus 2rem, so it never causes horizontal scrolling.
  • Below 36rem the dismiss button moves from the side column to its own full-width row at the end, and the recovery buttons become full width; each keeps a 44px minimum height.
  • Long titles and reference codes wrap inside the body column.
  • Because the surface is fixed, it can cover page content at the bottom of short landscape viewports; the application should keep the notification count low and leave content scrollable beneath it.
HTML · Sync failure on a phone Raw HTML for HTML · Sync failure on a phone
<forma-fault-notification class="forma-component-tag">
  <aside class="forma-toast forma-fault-notification" role="status" data-forma-intent="notification" data-forma-severity="warning" data-forma-motion-entry aria-labelledby="fault-notification-mobile-sync-title">
    <div class="forma-fault-notification__marker" aria-hidden="true">!</div>
    <div class="forma-fault-notification__body">
      <p class="forma-fault__severity">Warning</p>
      <h3 class="forma-toast__title" id="fault-notification-mobile-sync-title">Photos are waiting to upload</h3>
      <p>12 photos from the site visit are stored on this phone.</p>
      <p class="forma-fault-reference">Reference <code>AG-91B7Q</code></p>
      <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
        <button type="button" data-forma-aegis-capability="CanRetry">Try again</button>
      </div>
    </div>
    <button type="button" class="forma-fault-notification__dismiss" data-forma-action="dismiss" aria-label="Dismiss photo upload notification">Dismiss</button>
  </aside>
</forma-fault-notification>

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-notificationstatusabsentUse only when the application inserts a genuinely new notification. Omit it when re-rendering an existing notification so it is not announced twice.
aria-labelledbyaside.forma-fault-notificationid of the title—Names the complementary region by the notification title.
data-forma-severityaside.forma-fault-notificationdiagnostic | warning | error | critical—Records the Aegis severity. The notification surface does not restyle by severity; the visible severity text is the cue.
data-forma-intentaside.forma-fault-notificationnotification—Records the Aegis intent. Descriptive only.
data-forma-motion-weightaside.forma-fault-notificationlight | standard | heavystandardPresentation-only perceived mass for the entry settle. Keep the standard default; never map it to severity.
data-forma-motion-entryaside.forma-fault-notificationbooleanabsentOpts into the entry fade and settle when the element is first rendered. Omit it when re-rendering an existing notification.
data-forma-action.forma-fault-notification__dismissdismiss—Marks the dismiss button for application code. Forma attaches no behavior to it.
aria-label.forma-fault-notification__dismiss / .forma-recovery-actionsstring—On the dismiss button, start with the visible label and add which notification it dismisses. On the recovery group, name the group.
aria-hidden.forma-fault-notification__markertrue—Hides the decorative marker glyph.
typebuttonbutton—Required on dismiss and recovery buttons.
data-forma-aegis-capabilityrecovery buttonAegis capability name—Exact Aegis capability identity; revalidated by the application on click.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-fault-notificationBlock class—Root, applied together with forma-toast. A marker/body/dismiss grid, 32rem wide at most, with a thick start border and shadow. It is always visible (it does not depend on :popover-open) and inherits the toast's fixed bottom inline-end placement.
.forma-fault-notification__bodyElement class—Text column for severity, title, message, reference and recovery actions.
.forma-fault-notification__dismissElement class—Native dismiss button in the end column; full-width row below 36rem.
.forma-fault-notification__markerElement class—Decorative round marker glyph.
[data-forma-motion-entry]Attribute hook—Enables the insertion transition: opacity from 0 and a 0.45rem downward settle, driven by @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.
Keyboard interaction
KeysResult
Tab / Shift+TabReaches recovery buttons and then the dismiss button in source order. Focus is not moved into the notification when it appears.
Enter / SpaceActivates the focused button. Dismissal happens only when application code handles the click.
EscapeNo built-in effect: the surface is not a popover or dialog. The application may add an Escape shortcut if its policy allows dismissal.
Events
EventDescription
clickNative click on a recovery or dismiss button. The application revalidates recovery capabilities and removes the notification itself on dismiss.

Form behavior

Not a form control. Buttons are type="button".

States

Fault notification states
StateHow it is expressedPresentation
Newly insertedrole="status" + data-forma-motion-entry on first renderAnnounced politely once and fades in with a small settle.
Re-renderedno role and no data-forma-motion-entrySame visual surface without a second announcement or animation.
Dismissible.forma-fault-notification__dismiss presentA native dismiss button in the end column; the application removes the element on click.
Not dismissibledismiss button omittedPersists until the application removes it after resolution.
Severitydata-forma-severity plus visible textSeverity is read from the text label; the notification surface itself does not change border style.

Accessibility

Forma provides

  • Shows severity as visible text and a decorative marker; color is never the only cue.
  • Keeps dismiss and recovery controls as native buttons with 44px minimum height and the shared focus ring.
  • Never starts timers, so actionable faults do not disappear before the user can act.
  • Collapses the entry transition to 0.01ms under reduced motion; in forced colors the surface uses Canvas/CanvasText and drops the shadow.

Your application supplies

  • Add role="status" only for a newly inserted notification, and do not duplicate the same message into another live region.
  • Make the dismiss button's accessible name include its visible text (for example "Dismiss …"), and handle the click to remove the element.
  • Decide dismissibility from current application policy; omit the dismiss button when dismissal is not allowed.
  • Stack or queue multiple notifications yourself; Forma places every notification at the same fixed corner.
  • If you choose timed dismissal for non-actionable information, keep a durable history and meet your timing-adjustable policy.

Responsive behavior

  • Width is min(32rem, 100vw - 2rem) and the toast base limits it further to min(26rem, 100vw - 2rem), so it always fits the viewport.
  • Placement comes from forma-toast: fixed to the bottom inline-end corner with a 1rem inset that respects safe-area insets.
  • Below a 36rem viewport the grid becomes two columns, the dismiss button stretches across its own row and recovery buttons become full width.
  • Text and reference codes wrap within the body column.

Motion

  • With data-forma-motion-entry, the notification fades in (perceptual duration, independent of mass) and settles 0.45rem downward into place with the damped inertial easing.
  • The default perceived weight is standard. data-forma-motion-weight changes only the settle duration; it never expresses severity.
  • Motion runs only on first render through @starting-style; re-rendered notifications without the attribute appear in place.
  • There is no exit animation from Forma: removal is immediate when the application removes the element.
  • Under prefers-reduced-motion: reduce all durations collapse to 0.01ms; the notification appears in its final position immediately.

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

  • Say what still works ("stored on this device") alongside what failed.
  • Keep the reference visible for support conversations.
  • Remove or update the notification when Aegis reports the fault resolved or superseded.

Avoid

  • Auto-dismissing a notification that carries recovery actions.
  • Re-announcing the same notification on every render.
  • Using a heavier motion weight to make a critical fault feel more urgent.

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.