Faults and recovery

Fault blocking

<forma-fault-blocking>

Native-dialog surface for Aegis Blocking intent with only application-supplied recovery actions.

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

Purpose

A blocking fault presents an Aegis presentation whose intent is Blocking: the application cannot continue safely until one of the supplied recovery actions succeeds. It is a native dialog styled with forma-dialog and forma-fault-blocking, so a modal open gives the platform's focus containment, inert background and accessible dialog semantics. Forma cannot enforce a blocking policy with CSS. The application or Limen opens the dialog modally, chooses initial focus, decides whether a cancel request (Escape) is currently legal, revalidates every recovery action, and closes the dialog only after a legal transition changes the authoritative state.

Use when

  • Aegis reports intent Blocking, for example when state cannot be verified or a session cannot be restored.
  • Continuing would risk data loss or an unsafe action, and only specific recovery capabilities are legal.
  • The user must choose among recovery paths before doing anything else.

Avoid when

  • The user can keep working while the fault exists: use Fault banner or Fault notification.
  • The fault concerns one operation: use Fault inline.
  • You need a confirmation or ordinary modal task: use Dialog.
  • You would need a Continue anyway button to let users escape: that is not a blocking fault unless Aegis supplies a real capability meaning exactly that.

Behavior to know

  • Native dialog semantics: named by its title, described by its message, and modal only when the application calls showModal() or uses an invoker with command="show-modal".
  • Contains only the recovery actions Aegis supplied. There is no close button unless dismissal is currently legal.
  • Uses the heavy perceived motion weight by default because of the size of the surface and the commitment it asks for, not because of severity.
  • Respects viewport and dynamic viewport bounds on phones, scrolling internally when content is long.

Basic example

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

Canonical

Minimal fault blocking

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.

Critical

This application cannot continue safely

The current state cannot be verified. Use one of the recovery actions below before continuing.

Reference AG-7P2DX

HTML · Minimal fault blocking Raw HTML for HTML · Minimal fault blocking
<forma-fault-blocking class="forma-component-tag">
<button type="button" commandfor="blocking-fault-dialog" command="show-modal">Preview blocking fault</button>
<dialog
  class="forma-dialog forma-fault-blocking"
  id="blocking-fault-dialog"
  data-forma-intent="blocking"
  data-forma-severity="critical"
  data-forma-motion-weight="heavy"
  aria-labelledby="blocking-fault-title"
  aria-describedby="blocking-fault-message">
  <div class="forma-dialog__body">
    <div class="forma-fault-blocking__heading">
      <div class="forma-fault-blocking__marker" aria-hidden="true">!!</div>
      <div>
        <p class="forma-fault__severity">Critical</p>
        <h2 id="blocking-fault-title">This application cannot continue safely</h2>
      </div>
    </div>
    <p id="blocking-fault-message">The current state cannot be verified. Use one of the recovery actions below before continuing.</p>
    <p class="forma-fault-reference">Reference <code>AG-7P2DX</code></p>
  </div>
  <div class="forma-dialog__actions forma-recovery-actions" role="group" aria-label="Recovery actions">
    <button type="button" data-forma-aegis-capability="CanOpenReadOnly">Open read-only</button>
    <button type="button" data-forma-aegis-capability="CanReload">Reload</button>
  </div>
</dialog>
</forma-fault-blocking>

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

Examples

Scenario

Sign-in required to continue

An error-severity blocking fault with a single Aegis capability. The invoker uses the native command attributes to open the dialog modally for this preview; in an application Limen opens it when the Aegis intent is Blocking.

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.

Error

Your session ended

Sign in again to continue. The form you were completing is kept on this device.

Reference AG-3JH71

HTML · Sign-in required to continue Raw HTML for HTML · Sign-in required to continue
<forma-fault-blocking class="forma-component-tag">
  <button type="button" commandfor="fault-blocking-sign-in-required-dialog" command="show-modal">Preview sign-in fault</button>
  <dialog class="forma-dialog forma-fault-blocking" id="fault-blocking-sign-in-required-dialog" data-forma-intent="blocking" data-forma-severity="error" aria-labelledby="fault-blocking-sign-in-required-title" aria-describedby="fault-blocking-sign-in-required-message">
    <div class="forma-dialog__body">
      <div class="forma-fault-blocking__heading">
        <div class="forma-fault-blocking__marker" aria-hidden="true">!</div>
        <div>
          <p class="forma-fault__severity">Error</p>
          <h2 id="fault-blocking-sign-in-required-title">Your session ended</h2>
        </div>
      </div>
      <p id="fault-blocking-sign-in-required-message">Sign in again to continue. The form you were completing is kept on this device.</p>
      <p class="forma-fault-reference">Reference <code>AG-3JH71</code></p>
    </div>
    <div class="forma-dialog__actions forma-recovery-actions" role="group" aria-label="Recovery actions">
      <button type="button" data-forma-aegis-capability="CanReauthenticate">Sign in</button>
    </div>
  </dialog>
</forma-fault-blocking>

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

Scenario

Unverifiable local copy with safe details

A critical blocking fault offering three Aegis capabilities. Approved, already-sanitized details sit in a collapsed disclosure inside the dialog body; nothing developer-only is rendered.

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.

Critical

This project cannot be opened for editing

The copy stored on this device does not match the last verified version. Open it read-only, set it aside, or reload the verified version.

Reference AG-7P2DX

Safe diagnostic details
Project
Harbor renovation
Last verified
HTML · Unverifiable local copy with safe details Raw HTML for HTML · Unverifiable local copy with safe details
<forma-fault-blocking class="forma-component-tag">
  <button type="button" commandfor="fault-blocking-corrupt-local-copy-dialog" command="show-modal">Preview local copy fault</button>
  <dialog class="forma-dialog forma-fault-blocking" id="fault-blocking-corrupt-local-copy-dialog" data-forma-intent="blocking" data-forma-severity="critical" data-forma-motion-weight="heavy" aria-labelledby="fault-blocking-corrupt-local-copy-title" aria-describedby="fault-blocking-corrupt-local-copy-message">
    <div class="forma-dialog__body">
      <div class="forma-fault-blocking__heading">
        <div class="forma-fault-blocking__marker" aria-hidden="true">!!</div>
        <div>
          <p class="forma-fault__severity">Critical</p>
          <h2 id="fault-blocking-corrupt-local-copy-title">This project cannot be opened for editing</h2>
        </div>
      </div>
      <p id="fault-blocking-corrupt-local-copy-message">The copy stored on this device does not match the last verified version. Open it read-only, set it aside, or reload the verified version.</p>
      <p class="forma-fault-reference">Reference <code>AG-7P2DX</code></p>
      <details class="forma-fault-details">
        <summary>Safe diagnostic details</summary>
        <div class="forma-fault-details__content">
          <dl class="forma-fault-details__list">
            <div><dt>Project</dt><dd>Harbor renovation</dd></div>
            <div><dt>Last verified</dt><dd><time datetime="2026-09-29T16:12:00Z">29 Sep 2026, 16:12 UTC</time></dd></div>
          </dl>
        </div>
      </details>
    </div>
    <div class="forma-dialog__actions forma-recovery-actions" role="group" aria-label="Recovery actions">
      <button type="button" data-forma-aegis-capability="CanOpenReadOnly">Open read-only</button>
      <button type="button" data-forma-aegis-capability="CanQuarantine">Set aside</button>
      <button type="button" data-forma-aegis-capability="CanReload">Reload</button>
    </div>
  </dialog>
</forma-fault-blocking>

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

Blocking fault on a phone

A critical blocking fault opened at phone width, with two recovery actions stacked full 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 36rem the dialog is the viewport width minus 1rem and at most the dynamic viewport height minus 1rem, so it never extends under browser toolbars.
  • The dialog body scrolls internally when the message and details exceed the height; the page behind stays inert.
  • Recovery buttons stack as full-width rows with a 44px minimum height, in the order Aegis supplied them.
  • In landscape the height limit shrinks the dialog and the body scrolls; no content moves off screen horizontally.
HTML · Blocking fault on a phone Raw HTML for HTML · Blocking fault on a phone
<forma-fault-blocking class="forma-component-tag">
  <button type="button" commandfor="fault-blocking-mobile-reload-dialog" command="show-modal">Preview blocking fault</button>
  <dialog class="forma-dialog forma-fault-blocking" id="fault-blocking-mobile-reload-dialog" data-forma-intent="blocking" data-forma-severity="critical" aria-labelledby="fault-blocking-mobile-reload-title" aria-describedby="fault-blocking-mobile-reload-message">
    <div class="forma-dialog__body">
      <div class="forma-fault-blocking__heading">
        <div class="forma-fault-blocking__marker" aria-hidden="true">!!</div>
        <div>
          <p class="forma-fault__severity">Critical</p>
          <h2 id="fault-blocking-mobile-reload-title">This inspection cannot continue safely</h2>
        </div>
      </div>
      <p id="fault-blocking-mobile-reload-message">The checklist version on this phone is out of date. Reload to get the current version, or open your answers read-only.</p>
      <p class="forma-fault-reference">Reference <code>AG-8C1WF</code></p>
    </div>
    <div class="forma-dialog__actions forma-recovery-actions" role="group" aria-label="Recovery actions">
      <button type="button" data-forma-aegis-capability="CanReload">Reload</button>
      <button type="button" data-forma-aegis-capability="CanOpenReadOnly">Open read-only</button>
    </div>
  </dialog>
</forma-fault-blocking>

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
iddialogunique id—Target for the invoker's commandfor, or for application code that calls showModal().
commandforinvoker buttondialog id—Preview only: associates a native invoker with the dialog. Applications normally open the dialog from Limen when Aegis intent is Blocking.
commandinvoker buttonshow-modal—Opens the dialog modally without script. Never use a non-modal open for a blocking fault.
aria-labelledbydialogid of the heading—Required. Gives the dialog its accessible name.
aria-describedbydialogid of the message—Announces the safe message when the dialog opens.
data-forma-severitydialogdiagnostic | warning | error | critical—Records the Aegis severity. The dialog surface is not restyled by it; the visible severity text carries the level.
data-forma-intentdialogblocking—Records the Aegis intent. Descriptive only.
data-forma-motion-weightdialoglight | standard | heavyheavyPresentation-only perceived mass for the open transition. Heavy is the default for this surface; never map it to severity.
aria-hidden.forma-fault-blocking__markertrue—Hides the decorative marker glyph.
role.forma-recovery-actionsgroup—Groups the recovery buttons in the dialog footer.
aria-label.forma-recovery-actionsstring—Names the recovery group.
typebuttonbutton—Required on every button.
data-forma-aegis-capabilityrecovery buttonAegis capability name—Exact Aegis capability identity; revalidated on activation.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-fault-blockingBlock class—Applied with forma-dialog on the native dialog. Widens the dialog to min(42rem, 100vw - 2rem) and limits its height to min(90dvh, 100dvh - 2rem).
.forma-fault-blocking__headingElement class—Two-column grid placing the marker beside the severity label and heading.
.forma-fault-blocking__markerElement class—Decorative round marker glyph (for example !!).
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Selects the light, standard or heavy physics preset; heavy is the default when the attribute is absent.
Keyboard interaction
KeysResult
Tab / Shift+TabWhile open modally, focus cycles among the recovery buttons (and any disclosure) inside the dialog; the page behind is inert.
Enter / SpaceActivates the focused recovery button.
EscapeThe browser fires cancel and, by default, closes a modal dialog. When dismissal is not legal the application must handle cancel and keep the dialog open.
Events
EventDescription
cancelNative dialog event on Escape or another close request. The application decides whether closing is legal and prevents it when it is not.
closeNative dialog event after the dialog closes. Use it to restore focus to a meaningful location.
clickNative click on a recovery button, revalidated and translated into a typed recovery request by the application.

Form behavior

Not a form. Buttons are type="button"; do not use method="dialog" forms to close a blocking fault, because closing must follow a legal state change.

States

Fault blocking states
StateHow it is expressedPresentation
Closedno open attributeNot rendered; only the application's trigger (or nothing) is visible.
Open modallyshowModal() or command="show-modal"; [open]Centered, dimmed and blurred backdrop, background inert, focus inside the dialog.
Cancel requestednative cancel eventThe application decides; Forma adds no behavior.
Resolvedapplication closes the dialogClosed after a legal transition; the application restores focus.

Accessibility

Forma provides

  • Uses native dialog semantics, so a modal open provides focus containment, an inert background and the dialog role.
  • Shows severity as visible text next to a decorative marker.
  • Keeps recovery buttons native, focus-visible and at least 44px tall; they stack full width on narrow screens.
  • Keeps the dialog border and marker visible in forced-colors mode and removes spatial motion under reduced motion.

Your application supplies

  • Open the dialog modally (showModal) when Aegis intent is Blocking and choose initial focus among the legal recovery buttons.
  • Handle cancel/close requests according to current policy; do not let Escape silently bypass a blocking fault.
  • Render only current legal recovery actions; never add Continue anyway.
  • Close only after a legal transition and restore focus to a meaningful place.
  • Keep diagnostic details, if any, in Fault details with already-sanitized values.

Responsive behavior

  • Width is min(42rem, 100vw - 2rem); height is capped at min(90dvh, 100dvh - 2rem) and the dialog scrolls when content is taller.
  • Below 36rem the dialog becomes the viewport width minus 1rem and at most 100dvh - 1rem, centered with auto margins.
  • Recovery buttons in the footer wrap on wide screens and stack as full-width rows below 36rem.
  • Headings, messages and references wrap; the marker column keeps its intrinsic width.

Motion

  • Opening uses the shared dialog transition: the surface settles from a 0.75rem offset and 0.985 scale while the backdrop dims and blurs with a mass-independent perceptual fade.
  • The default perceived weight is heavy because of surface size and commitment, not severity; exit uses the same duration and easing as entry.
  • Motion never delays focus, the modal state, or recovery actions; the native open state is authoritative.
  • Under prefers-reduced-motion: reduce translate and scale are removed, the backdrop blur is dropped and durations collapse to 0.01ms.

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

Critical

This application cannot continue safely

The current state cannot be verified. Use one of the recovery actions below before continuing.

Reference AG-7P2DX

standardpresentation only

Critical

This application cannot continue safely

The current state cannot be verified. Use one of the recovery actions below before continuing.

Reference AG-7P2DX

heavypresentation only

Critical

This application cannot continue safely

The current state cannot be verified. Use one of the recovery actions below before continuing.

Reference AG-7P2DX

Usage guidance

Do

  • Explain what cannot continue and what each recovery path does.
  • Keep the reference visible for support.
  • Order recovery actions as Aegis supplies them, and localize labels without changing capability names.

Avoid

  • Adding a close or cancel button that bypasses the blocking condition.
  • Opening the dialog non-modally, which removes focus containment.
  • Using motion weight or color as the only indicator of severity.

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.