Faults and recovery

Fault inline

<forma-fault-inline>

Operation-local Aegis fault presentation with reference and legal recovery actions.

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

Purpose

An inline fault presents an Aegis presentation whose intent is Inline: the failure belongs to one operation, field or region and is shown right next to it. It uses the Fault shell with the forma-fault--inline modifier, which tightens padding and uses the secondary surface so the fault reads as part of the affected area. It never announces itself globally or steals focus; instead the affected control or region points at it with aria-describedby, so the fault is read when the user reaches that control. The application renders it, supplies the recovery actions Aegis derived, and removes it when the fault resolves.

Use when

  • Aegis reports intent Inline for a failure tied to one save, upload, row or form section.
  • The user can recover in place, for example by retrying the operation next to the control that failed.
  • The affected control should describe the failure when it is focused, rather than the page announcing it.

Avoid when

  • The failure affects the whole page or application: use Fault banner.
  • The user must be told about something that happened elsewhere or in the background: use Fault notification.
  • The application cannot continue until a recovery action is taken: use Fault blocking.
  • The problem is a user input validation error, not an Aegis fault: use Validation message or Validation summary.
  • Several faults across a form need one entry point after a failed submit: use Fault summary and keep individual inline faults near their regions.

Behavior to know

  • Placed in source order immediately after, or inside, the affected region so reading order matches visual proximity.
  • Never focuses itself and carries no live-region role; the affected control's aria-describedby makes it discoverable.
  • Severity is visible text plus the start-border style; the marker is decorative.
  • Recovery actions are only the ones Aegis supplied, as native buttons with data-forma-aegis-capability.

Basic example

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

Canonical

Minimal fault inline

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

Profile was not saved.

Check your connection and try again.

Reference AG-4F82C

HTML · Minimal fault inline Raw HTML for HTML · Minimal fault inline
<forma-fault-inline class="forma-component-tag">
<div
  class="forma-fault forma-fault--inline"
  id="profile-save-fault"
  data-forma-intent="inline"
  data-forma-severity="error"
  aria-labelledby="profile-save-fault-title">
  <div class="forma-fault__marker" aria-hidden="true">!</div>
  <div class="forma-fault__body">
    <p class="forma-fault__severity">Error</p>
    <p class="forma-fault__title" id="profile-save-fault-title"><strong>Profile was not saved.</strong></p>
    <p class="forma-fault__message">Check your connection and try again.</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>
</div>
</forma-fault-inline>

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

Examples

Scenario

Field that failed to save

An autosaved field whose last save failed. The input lists the fault in aria-describedby after its own help text, so a screen reader announces the failure when the field is focused, without any global announcement.

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.

Receives invoices and payment reminders.

Error

Billing contact was not saved.

Your value is still in the field. Try again when you are back online.

Reference AG-7TT2Q

HTML · Field that failed to save Raw HTML for HTML · Field that failed to save
<forma-fault-inline class="forma-component-tag">
  <div class="forma-field">
    <label class="forma-field__label" for="fault-inline-field-save-input">Billing contact</label>
    <span class="forma-field__description" id="fault-inline-field-save-help">Receives invoices and payment reminders.</span>
    <input id="fault-inline-field-save-input" name="billing-contact" type="email" value="finance@example.com" aria-describedby="fault-inline-field-save-help fault-inline-field-save-fault">
  </div>
  <div class="forma-fault forma-fault--inline" role="group" id="fault-inline-field-save-fault" data-forma-intent="inline" data-forma-severity="error" aria-labelledby="fault-inline-field-save-title">
    <div class="forma-fault__marker" aria-hidden="true">!</div>
    <div class="forma-fault__body">
      <p class="forma-fault__severity">Error</p>
      <p class="forma-fault__title" id="fault-inline-field-save-title"><strong>Billing contact was not saved.</strong></p>
      <p class="forma-fault__message">Your value is still in the field. Try again when you are back online.</p>
      <p class="forma-fault-reference">Reference <code>AG-7TT2Q</code></p>
    </div>
    <div class="forma-recovery-actions" role="group" aria-label="Recovery actions for billing contact">
      <button type="button" data-forma-aegis-capability="CanRetry">Try again</button>
    </div>
  </div>
</forma-fault-inline>

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

Scenario

Import batch that could not be processed

A warning inside a batch detail region. Aegis supplied two capabilities, Process again and Set aside, which are rendered with their default labels. The region's aria-describedby points at the fault.

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.

Batch 2026-09-29-B

412 invoices received from the supplier feed.

Warning

7 invoices could not be read.

The rest of the batch was imported. You can process the 7 again or set them aside for review.

Reference AG-61KDA

HTML · Import batch that could not be processed Raw HTML for HTML · Import batch that could not be processed
<forma-fault-inline class="forma-component-tag">
  <section aria-labelledby="fault-inline-import-row-heading" aria-describedby="fault-inline-import-row-fault">
    <h3 id="fault-inline-import-row-heading">Batch 2026-09-29-B</h3>
    <p>412 invoices received from the supplier feed.</p>
    <div class="forma-fault forma-fault--inline" role="group" id="fault-inline-import-row-fault" data-forma-intent="inline" data-forma-severity="warning" aria-labelledby="fault-inline-import-row-title">
      <div class="forma-fault__marker" aria-hidden="true">!</div>
      <div class="forma-fault__body">
        <p class="forma-fault__severity">Warning</p>
        <p class="forma-fault__title" id="fault-inline-import-row-title"><strong>7 invoices could not be read.</strong></p>
        <p class="forma-fault__message">The rest of the batch was imported. You can process the 7 again or set them aside for review.</p>
        <p class="forma-fault-reference">Reference <code>AG-61KDA</code></p>
      </div>
      <div class="forma-recovery-actions" role="group" aria-label="Recovery actions for batch 2026-09-29-B">
        <button type="button" data-forma-aegis-capability="CanReprocess">Process again</button>
        <button type="button" data-forma-aegis-capability="CanQuarantine">Set aside</button>
      </div>
    </div>
  </section>
</forma-fault-inline>

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

Scenario

Failure with no legal recovery

Aegis supplied no recovery capability for this operation, so the recovery group is omitted. The message tells the user what remains true instead of offering an action that would be refused.

Error

Signature request was not sent.

The document is unchanged. An administrator has been notified.

Reference AG-2WPZ8

HTML · Failure with no legal recovery Raw HTML for HTML · Failure with no legal recovery
<forma-fault-inline class="forma-component-tag">
  <div class="forma-fault forma-fault--inline" role="group" data-forma-intent="inline" data-forma-severity="error" aria-labelledby="fault-inline-no-recovery-title">
    <div class="forma-fault__marker" aria-hidden="true">!</div>
    <div class="forma-fault__body">
      <p class="forma-fault__severity">Error</p>
      <p class="forma-fault__title" id="fault-inline-no-recovery-title"><strong>Signature request was not sent.</strong></p>
      <p class="forma-fault__message">The document is unchanged. An administrator has been notified.</p>
      <p class="forma-fault-reference">Reference <code>AG-2WPZ8</code></p>
    </div>
  </div>
</forma-fault-inline>

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

Upload failure on a phone

An upload fault inside a narrow form. The two recovery buttons stack at full width beneath the message.

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 marker and body share the first row and the recovery group moves to a full-width row underneath.
  • Each recovery button fills the width and keeps a 44px minimum height, so Try again and Sign in are separate, comfortable touch targets.
  • Title, message and reference wrap inside the body column; the reference code breaks anywhere instead of overflowing.
  • The fault stays directly after the affected region in both orientations; it is never moved to a separate mobile-only location.
HTML · Upload failure on a phone Raw HTML for HTML · Upload failure on a phone
<forma-fault-inline class="forma-component-tag">
  <div class="forma-fault forma-fault--inline" role="group" data-forma-intent="inline" data-forma-severity="error" aria-labelledby="fault-inline-mobile-upload-title">
    <div class="forma-fault__marker" aria-hidden="true">!</div>
    <div class="forma-fault__body">
      <p class="forma-fault__severity">Error</p>
      <p class="forma-fault__title" id="fault-inline-mobile-upload-title"><strong>receipt-scan-september.pdf did not upload.</strong></p>
      <p class="forma-fault__message">Your sign-in expired during the upload.</p>
      <p class="forma-fault-reference">Reference <code>AG-5CN0V</code></p>
    </div>
    <div class="forma-recovery-actions" role="group" aria-label="Recovery actions for receipt upload">
      <button type="button" data-forma-aegis-capability="CanRetry">Try again</button>
      <button type="button" data-forma-aegis-capability="CanReauthenticate">Sign in</button>
    </div>
  </div>
</forma-fault-inline>

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
id.forma-faultunique id—Lets the affected control or region reference the fault with aria-describedby.
aria-describedbyaffected control or regionid of the .forma-fault—Associates the fault with the control it is about. Append it after any existing help-text id.
role.forma-fault / .forma-recovery-actionsgroup—A group role makes the fault container nameable with aria-labelledby; the recovery container is also a group.
aria-labelledby.forma-faultid of .forma-fault__title—Names the fault group by its title.
data-forma-severity.forma-faultdiagnostic | warning | error | criticalabsent (error style)Aegis severity; selects the start-border style. Always paired with visible text.
data-forma-intent.forma-faultinline—Records that Aegis chose the Inline intent. Descriptive only.
aria-hidden.forma-fault__markertrue—Hides the decorative marker glyph from assistive technology.
aria-label.forma-recovery-actionsstring—Names the recovery group; include the affected object when several inline faults are on one page.
typebuttonbutton—Required so recovery buttons inside a form never submit it.
data-forma-aegis-capabilitybuttonAegis capability name—Exact Aegis capability identity. Not authorization; revalidate on click.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-fault--inlineModifier class—Applied with forma-fault. Tighter 0.75rem padding and the secondary surface so the fault sits inside the affected region.
.forma-faultBlock class—The shared fault grid: marker, body and recovery columns with a severity-styled start border. See Fault.
.forma-fault__markerElement class—Decorative marker glyph in a ring.
.forma-fault__bodyElement class—Text column that wraps long content.
.forma-fault__severityElement class—Visible severity label.
.forma-fault__titleElement class—The Aegis title; in inline use a paragraph with strong text is typical so the page outline is not disturbed.
.forma-fault__messageElement class—Safe user-facing message.
[data-forma-severity]Attribute hook—Selects dotted (diagnostic), dashed (warning), solid (error) or wide-plus-outline (critical) start border.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the affected control and then the recovery buttons in source order. The fault never receives focus by itself.
Enter / SpaceActivates the focused recovery button (native button behavior).
Events
EventDescription
clickNative click on a recovery button. The application maps it to a typed recovery request after revalidating the capability.

Form behavior

The fault is not a form control. Recovery buttons are type="button" so they never submit the surrounding form; the affected input keeps its own value and validity.

States

Fault inline states
StateHow it is expressedPresentation
Presentrendered by the applicationThe fault is in the DOM next to the affected region, described by it, and silent until reached.
Severitydata-forma-severity plus visible textDiagnostic, Warning, Error or Critical, each with its own start-border style.
No recoveryomit .forma-recovery-actionsOnly the message and reference are shown.
Resolvedremoved by the applicationWhen Aegis reports the fault resolved, the application removes the fault and the aria-describedby reference together.

Accessibility

Forma provides

  • Provides visible severity text and a non-color border style for every severity.
  • Keeps recovery actions as native buttons with the shared focus ring and 44px minimum height.
  • Adds no live region and no focus movement, matching the Inline intent.
  • Keeps the border, marker and text visible in forced-colors mode.
  • On its secondary-surface background, severity, message and reference text use text.on-secondary-surface and links use text.primary, so every theme and brand meets WCAG AA 4.5:1 (FORMA-A11Y-002).

Your application supplies

  • Place the fault next to the affected region in source order and reference it from that control or region with aria-describedby.
  • Remove the aria-describedby reference when the fault is removed so the control is not described by a missing element.
  • Give the fault container a role (for example group) if you name it with aria-labelledby; a plain div cannot carry a name.
  • Render only Aegis-supplied actions and revalidate them on activation.
  • Do not also announce the same fault in a global live region.

Responsive behavior

  • Uses the Fault grid: marker, flexible body (minmax(0, 1fr)) and actions on wide viewports.
  • Below a 36rem viewport the recovery group moves to its own full-width row and every button becomes full width.
  • Text and reference codes wrap; nothing forces horizontal page overflow at 320px.
  • The breakpoint follows the viewport, not the container, so a fault in a narrow column on a wide screen keeps its side-by-side actions; keep such columns wide enough for the button labels.

Motion

  • No animation: the inline fault appears and disappears with the application's render, without entry motion, so it never draws the eye away from the task.
  • Recovery buttons use only the foundation hover/press background interpolation, which is reduced to 0.01ms under prefers-reduced-motion: reduce.

Usage guidance

Do

  • Keep the message about what happened and what remains true ("Your value is still in the field").
  • Name the recovery group after the affected object when a page can show several inline faults.
  • Keep the reference visible so the user can quote it to support.

Avoid

  • Moving focus to an inline fault when it appears.
  • Showing a disabled or invented recovery button when Aegis supplied none.
  • Using an inline fault for ordinary validation messages that have no Aegis fault behind them.

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.