Faults and recovery

Fault

<forma-fault>

Common safe presentation shell for an Aegis Presentation.T without exposing raw fault diagnostics.

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

Purpose

The fault shell is the shared visual vocabulary of the Aegis fault family: a non-color marker, a visible severity label, a title, a safe user-facing message, a quotable reference and a region of recovery actions. It renders the fields of Aegis Presentation.T that the application has already mapped into markup. Forma never receives the raw fault, never chooses the severity or intent, and never decides which recovery actions exist; the application or Limen does that upstream and Forma only presents the result.

Use when

  • An adapter or nonstandard composition needs to show an Aegis presentation that does not map cleanly to one of the intent patterns.
  • A panel, card or side region shows the outcome of one failed operation together with its reference and the recovery actions Aegis supplied.
  • You are building a new intent-specific surface and want to reuse the marker, severity, title, message and reference vocabulary.

Avoid when

  • The Aegis intent is known: use Fault inline, Fault notification, Fault banner or Fault blocking, which add the placement, live-region and dialog semantics that intent requires.
  • The intent is Silent: render nothing visible. Persistence state, if the application chooses to show it, belongs in Diagnostic status.
  • Several unresolved faults must be listed together: use Fault summary with already-grouped entries.
  • The message is a general notice or validation problem with no Aegis fault behind it: use Alert or Validation message.
  • You need to show developer diagnostics such as stack traces or exception details: they never belong in a Forma fault surface.

Behavior to know

  • Severity is always written as text in forma-fault__severity and repeated structurally by the start border style: dotted for diagnostic, dashed for warning, solid for error, and a wider border plus outline for critical.
  • The marker is decorative (aria-hidden) and uses a glyph and a ring shape, never color alone.
  • Recovery buttons are plain native buttons annotated with data-forma-aegis-capability. The attribute describes intent; it is not authorization.
  • The shell never announces itself, steals focus or animates. Those behaviors belong to the intent-specific patterns and the application.

Basic example

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

Canonical

Minimal fault

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.

Error

Could not save changes

The update did not complete. Your current values are still available.

Reference AG-4F82C

HTML · Minimal fault Raw HTML for HTML · Minimal fault
<forma-fault class="forma-component-tag">
<section
  class="forma-fault"
  data-forma-intent="inline"
  data-forma-severity="error"
  aria-labelledby="fault-title"
  aria-describedby="fault-message">
  <div class="forma-fault__marker" aria-hidden="true">!</div>
  <div class="forma-fault__body">
    <p class="forma-fault__severity">Error</p>
    <h3 class="forma-fault__title" id="fault-title">Could not save changes</h3>
    <p class="forma-fault__message" id="fault-message">The update did not complete. Your current values are still available.</p>
    <p class="forma-fault-reference">Reference <code>AG-4F82C</code></p>
  </div>
  <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
    <button type="button" data-forma-aegis-capability="CanRetry">Try again</button>
  </div>
</section>
</forma-fault>

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

Examples

Scenario

Session expired with two recovery paths

A warning-severity fault in a record panel. Aegis supplied two capabilities, so two native buttons are rendered in the order given. The dashed start border repeats the Warning label structurally.

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.

Warning

Your session has expired

Sign in again to keep editing, or open the record read-only. Unsaved changes are kept on this device.

Reference AG-3JH71

HTML · Session expired with two recovery paths Raw HTML for HTML · Session expired with two recovery paths
<forma-fault class="forma-component-tag">
  <section class="forma-fault" data-forma-intent="inline" data-forma-severity="warning" aria-labelledby="fault-warning-two-actions-title" aria-describedby="fault-warning-two-actions-message">
    <div class="forma-fault__marker" aria-hidden="true">!</div>
    <div class="forma-fault__body">
      <p class="forma-fault__severity">Warning</p>
      <h3 class="forma-fault__title" id="fault-warning-two-actions-title">Your session has expired</h3>
      <p class="forma-fault__message" id="fault-warning-two-actions-message">Sign in again to keep editing, or open the record read-only. Unsaved changes are kept on this device.</p>
      <p class="forma-fault-reference">Reference <code>AG-3JH71</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="CanOpenReadOnly">Open read-only</button>
    </div>
  </section>
</forma-fault>

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

Scenario

Critical fault in a side panel

Critical severity widens the start border and adds an outline so the level stays distinguishable in grayscale and forced colors. Visual weight is not a substitute for the Critical text label, which remains first in the body.

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

Workspace data is out of date

This panel can no longer confirm the latest ledger totals. Reload to fetch a verified copy.

Reference AG-9QX4L

HTML · Critical fault in a side panel Raw HTML for HTML · Critical fault in a side panel
<forma-fault class="forma-component-tag">
  <section class="forma-fault" data-forma-intent="inline" data-forma-severity="critical" aria-labelledby="fault-critical-reload-title" aria-describedby="fault-critical-reload-message">
    <div class="forma-fault__marker" aria-hidden="true">!!</div>
    <div class="forma-fault__body">
      <p class="forma-fault__severity">Critical</p>
      <h3 class="forma-fault__title" id="fault-critical-reload-title">Workspace data is out of date</h3>
      <p class="forma-fault__message" id="fault-critical-reload-message">This panel can no longer confirm the latest ledger totals. Reload to fetch a verified copy.</p>
      <p class="forma-fault-reference">Reference <code>AG-9QX4L</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>
  </section>
</forma-fault>

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

Scenario

Diagnostic notice without recovery

Aegis supplied no recovery capability, so the recovery region is omitted entirely instead of showing a disabled or invented action. The dotted start border marks the Diagnostic level.

Diagnostic

Preview thumbnails were skipped

Two attachments are shown without previews. The files themselves are unaffected.

Reference AG-0M5TR

HTML · Diagnostic notice without recovery Raw HTML for HTML · Diagnostic notice without recovery
<forma-fault class="forma-component-tag">
  <section class="forma-fault" data-forma-intent="inline" data-forma-severity="diagnostic" aria-labelledby="fault-diagnostic-no-actions-title" aria-describedby="fault-diagnostic-no-actions-message">
    <div class="forma-fault__marker" aria-hidden="true">i</div>
    <div class="forma-fault__body">
      <p class="forma-fault__severity">Diagnostic</p>
      <h3 class="forma-fault__title" id="fault-diagnostic-no-actions-title">Preview thumbnails were skipped</h3>
      <p class="forma-fault__message" id="fault-diagnostic-no-actions-message">Two attachments are shown without previews. The files themselves are unaffected.</p>
      <p class="forma-fault-reference">Reference <code>AG-0M5TR</code></p>
    </div>
  </section>
</forma-fault>

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

Long title and reference on a phone

An error with a long translated title and a long reference at phone width. The actions column drops below the body and each button spans the 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 three-column grid becomes two columns (marker and body); the recovery region moves to its own full-width row underneath, keeping source reading order.
  • Each recovery button stretches to the full width and keeps its 2.75rem (44px) minimum height, so actions are easy to hit with a thumb.
  • The title wraps and the reference code breaks anywhere, so neither causes horizontal page scrolling at 320px.
  • Orientation changes only reflow the body text; the marker, severity label and action order do not change.
HTML · Long title and reference on a phone Raw HTML for HTML · Long title and reference on a phone
<forma-fault class="forma-component-tag">
  <section class="forma-fault" data-forma-intent="inline" data-forma-severity="error" aria-labelledby="fault-mobile-long-content-title" aria-describedby="fault-mobile-long-content-message">
    <div class="forma-fault__marker" aria-hidden="true">!</div>
    <div class="forma-fault__body">
      <p class="forma-fault__severity">Error</p>
      <h3 class="forma-fault__title" id="fault-mobile-long-content-title">Die Änderungen an den Rechnungsempfängern konnten nicht gespeichert werden</h3>
      <p class="forma-fault__message" id="fault-mobile-long-content-message">Ihre Eingaben sind weiterhin verfügbar.</p>
      <p class="forma-fault-reference">Reference <code>AG-4F82C-BILLING-RECIPIENTS-2026</code></p>
    </div>
    <div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
      <button type="button" data-forma-aegis-capability="CanRetry">Erneut versuchen</button>
      <button type="button" data-forma-aegis-capability="CanReload">Neu laden</button>
    </div>
  </section>
</forma-fault>

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
data-forma-severity.forma-faultdiagnostic | warning | error | criticalabsent (solid error-style border)The Aegis severity, lowercased. Changes the start-border style; it must always be paired with the visible severity text.
data-forma-intent.forma-faultinline | notification | banner | blocking—Records the Aegis intent the application mapped. Descriptive only; Forma CSS does not style it.
aria-labelledby.forma-faultid of .forma-fault__title—Names the fault region by its title.
aria-describedby.forma-faultid of .forma-fault__message—Associates the safe user-facing message as the region's description.
aria-hidden.forma-fault__markertrue—Required. The marker glyph repeats the severity visually and must not be read aloud.
role.forma-recovery-actionsgroup—Groups the recovery buttons so assistive technology announces them together.
aria-label.forma-recovery-actionsstring—Names the recovery group, for example "Recovery actions".
typebuttonbutton—Required on every recovery button so it never submits an enclosing form.
data-forma-aegis-capabilitybuttonAegis capability case name, e.g. CanRetry—The exact Aegis capability the button represents. Describes intent to application code; it is not authority and must be revalidated on activation.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-faultBlock class—Root. A three-column grid (marker, body, recovery actions) with a thick start border and a primary surface.
.forma-fault__bodyElement class—Text column for severity, title, message and reference. It shrinks to zero minimum width so long content wraps.
.forma-fault__markerElement class—Decorative round marker holding a short glyph such as ! or !!. Shape and glyph, not color, carry the cue.
.forma-fault__messageElement class—The safe user-facing message from Aegis.
.forma-fault__severityElement class—Visible severity label in small uppercase monospace. Always present.
.forma-fault__titleElement class—The Aegis title. Use a heading or a paragraph with strong text depending on the surrounding outline.
.forma-fault--inlineModifier class—Operation-local variant used by Fault inline: tighter padding and the secondary surface so it reads as part of the affected region.
[data-forma-severity]Attribute hook"critical", "diagnostic", "warning"diagnostic gives a dotted start border, warning dashed, critical a wider border plus an offset outline; error (or absent) keeps the solid default.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves between recovery buttons. The fault region itself is not focusable and never takes focus when it appears.
Enter / SpaceActivates the focused recovery button (native button behavior).
Events
EventDescription
clickNative click on a recovery button. Application or Limen code reads data-forma-aegis-capability, revalidates the capability and application state, then issues a typed recovery request.

Form behavior

Not a form control. Recovery buttons use type="button" and never submit or reset an enclosing form.

States

Fault states
StateHow it is expressedPresentation
Diagnosticdata-forma-severity="diagnostic" plus the text DiagnosticDotted start border. Lowest severity; often no recovery actions.
Warningdata-forma-severity="warning" plus the text WarningDashed start border.
Errordata-forma-severity="error" plus the text ErrorSolid 0.35rem start border (the default).
Criticaldata-forma-severity="critical" plus the text CriticalSolid 0.55rem start border and a 1px outline offset by 2px.
No recovery availableomit the .forma-recovery-actions groupThe grid keeps its layout; nothing is shown in the action column. Do not render disabled placeholder actions.

Accessibility

Forma provides

  • Expresses every severity as visible text plus a border style, so severity never depends on color.
  • Keeps recovery controls as native buttons with the shared visible focus ring and a 44px minimum height.
  • In forced-colors mode the border, marker ring, severity text and reference switch to CanvasText on Canvas and stay visible.
  • Adds no live region, focus movement or animation, so rerendering the shell does not produce duplicate announcements.

Your application supplies

  • Supply the visible severity label, title, message and reference from Aegis Presentation.T; never bind raw fault fields, stack traces or exception details.
  • Render only the recovery actions Aegis supplied, with exact capability names, and revalidate capability and domain state on every click.
  • Give the section an accessible name with aria-labelledby, or use a non-landmark wrapper when several faults would create many identically named regions.
  • Choose a heading level that fits the surrounding outline for the title.
  • Decide whether the fault is announced; if it must be, use the intent-specific pattern that owns that behavior.

Responsive behavior

  • The root is a grid of auto minmax(0, 1fr) auto; the body column absorbs remaining width and long text wraps inside it.
  • Below a 36rem viewport the grid becomes two columns and the recovery group moves to a full-width row beneath the body, preserving source order.
  • At the same breakpoint the recovery group takes the full width and each button becomes full width with a 44px minimum height.
  • Reference codes break anywhere, so long references never force horizontal scrolling at 320px.
  • The breakpoint is a viewport media query, not a container query: a fault inside a narrow sidebar on a wide screen keeps the three-column layout.

Motion

  • No animation: the shell is a persistent, static surface and does not animate on insertion or rerender.
  • Recovery buttons inherit the foundation hover and press feedback, a short perceptual background-color change that never moves the hit target and collapses to 0.01ms under prefers-reduced-motion: reduce.
  • Entry motion, where an intent requires it, lives in Fault notification, Fault banner and Fault blocking; motion weight never encodes severity.

Usage guidance

Do

  • Prefer the intent-specific pattern whenever the Aegis intent is known; use the shell for adapters and custom compositions.
  • Keep the severity text, marker, title, message and reference in that order so every fault reads the same way.
  • Use the default Aegis labels (Try again, Sign in, Reload, …) or localize them without changing the capability name.

Avoid

  • Inventing actions such as Continue anyway or Ignore that Aegis did not supply.
  • Choosing severity from visual weight or color, or omitting the severity text because the border already shows it.
  • Placing developer-only diagnostics, internal paths or tokens anywhere in the shell.

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.