Fault blocking
<forma-fault-blocking>
Native-dialog surface for Aegis Blocking intent with only application-supplied recovery actions.
- Authoring tag
<forma-fault-blocking>- Category
- Faults and recovery
- 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
dialogsemantics: 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.
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.
<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
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.
<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.
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.
<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.
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.
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.
<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.
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.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
id | dialog | unique id | — | Target for the invoker's commandfor, or for application code that calls showModal(). |
commandfor | invoker button | dialog id | — | Preview only: associates a native invoker with the dialog. Applications normally open the dialog from Limen when Aegis intent is Blocking. |
command | invoker button | show-modal | — | Opens the dialog modally without script. Never use a non-modal open for a blocking fault. |
aria-labelledby | dialog | id of the heading | — | Required. Gives the dialog its accessible name. |
aria-describedby | dialog | id of the message | — | Announces the safe message when the dialog opens. |
data-forma-severity | dialog | diagnostic | warning | error | critical | — | Records the Aegis severity. The dialog surface is not restyled by it; the visible severity text carries the level. |
data-forma-intent | dialog | blocking | — | Records the Aegis intent. Descriptive only. |
data-forma-motion-weight | dialog | light | standard | heavy | heavy | Presentation-only perceived mass for the open transition. Heavy is the default for this surface; never map it to severity. |
aria-hidden | .forma-fault-blocking__marker | true | — | Hides the decorative marker glyph. |
role | .forma-recovery-actions | group | — | Groups the recovery buttons in the dialog footer. |
aria-label | .forma-recovery-actions | string | — | Names the recovery group. |
type | button | button | — | Required on every button. |
data-forma-aegis-capability | recovery button | Aegis capability name | — | Exact Aegis capability identity; revalidated on activation. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-fault-blocking | Block 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__heading | Element class | — | Two-column grid placing the marker beside the severity label and heading. |
.forma-fault-blocking__marker | Element 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. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | While open modally, focus cycles among the recovery buttons (and any disclosure) inside the dialog; the page behind is inert. |
| Enter / Space | Activates the focused recovery button. |
| Escape | The 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. |
| Event | Description |
|---|---|
cancel | Native dialog event on Escape or another close request. The application decides whether closing is legal and prevents it when it is not. |
close | Native dialog event after the dialog closes. Use it to restore focus to a meaningful location. |
click | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Closed | no open attribute | Not rendered; only the application's trigger (or nothing) is visible. |
| Open modally | showModal() or command="show-modal"; [open] | Centered, dimmed and blurred backdrop, background inert, focus inside the dialog. |
| Cancel requested | native cancel event | The application decides; Forma adds no behavior. |
| Resolved | application closes the dialog | Closed 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 atmin(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: reducetranslate 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:
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.