Faults and recovery

Recovery actions

<forma-recovery-actions>

Native buttons annotated with Aegis capability identity; current authority is revalidated on activation.

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

Purpose

Recovery actions project the Aegis recovery capabilities of a fault into ordinary native buttons inside a labelled group. Each button carries data-forma-aegis-capability with the exact Aegis capability case name, such as CanRetry, so application or Limen code knows which typed recovery request the click represents. The attribute communicates intent only. It is not authority: stale DOM must never authorize an effect, so the application rechecks the current Aegis capability and Ordo/application state every time a button is activated. Forma decides neither which actions exist nor whether they are legal.

Use when

  • An Aegis presentation carries one or more recovery actions and you are rendering it in any fault surface.
  • You need the canonical labels (Try again, Sign in, Reload, Set aside, Process again, Open read-only, Reconnect diagnostics) or localized equivalents that keep the capability identity.
  • A dialog footer, banner or inline fault needs its recovery buttons to wrap and stack consistently.

Avoid when

  • The actions are ordinary commands unrelated to an Aegis fault: use Button or Command group.
  • You would need an action Aegis did not supply, such as Continue anyway or Ignore: do not render it.
  • The only action is dismissing a notification; the dismiss control belongs to Fault notification, not to the recovery group.

Behavior to know

  • Every action is a native button type="button", so keyboard activation, focus and accessible names come from the platform.
  • Button order is the order Aegis supplied; Forma does not rank or highlight a primary action.
  • Buttons wrap on wide screens and become full-width 44px rows on narrow screens.
  • The group is named with role="group" and aria-label so screen readers announce it as a set of recovery options.

Basic example

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

Canonical

Minimal recovery actions

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 recovery actions Raw HTML for HTML · Minimal recovery actions
<forma-recovery-actions class="forma-component-tag">
<div class="forma-recovery-actions" role="group" aria-label="Recovery actions">
  <button type="button" data-forma-aegis-capability="CanRetry">Try again</button>
  <button type="button" data-forma-aegis-capability="CanReauthenticate">Sign in</button>
  <button type="button" data-forma-aegis-capability="CanOpenReadOnly">Open read-only</button>
</div>
</forma-recovery-actions>

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

Examples

Scenario

Localized labels

French labels for three capabilities. The visible text changes; the capability identity in data-forma-aegis-capability does not, so application code maps clicks exactly as before.

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 · Localized labels Raw HTML for HTML · Localized labels
<forma-recovery-actions class="forma-component-tag">
  <div class="forma-recovery-actions" role="group" aria-label="Actions de récupération" lang="fr">
    <button type="button" data-forma-aegis-capability="CanRetry">Réessayer</button>
    <button type="button" data-forma-aegis-capability="CanReload">Recharger</button>
    <button type="button" data-forma-aegis-capability="CanRestoreSink">Reconnecter les diagnostics</button>
  </div>
</forma-recovery-actions>

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

Scenario

Recovery for a failed import

The group inside an inline fault for a data import. Aegis supplied Process again and Set aside; both keep their default labels. The group name includes the affected batch because several import faults can be on one page.

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

3 rows in timesheets-week-39.csv were not imported.

Reference AG-61KDA

HTML · Recovery for a failed import Raw HTML for HTML · Recovery for a failed import
<forma-recovery-actions class="forma-component-tag">
  <div class="forma-fault forma-fault--inline" role="group" data-forma-intent="inline" data-forma-severity="warning" aria-labelledby="recovery-actions-import-recovery-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="recovery-actions-import-recovery-title"><strong>3 rows in timesheets-week-39.csv were not imported.</strong></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 timesheets-week-39.csv">
      <button type="button" data-forma-aegis-capability="CanReprocess">Process again</button>
      <button type="button" data-forma-aegis-capability="CanQuarantine">Set aside</button>
    </div>
  </div>
</forma-recovery-actions>

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

Stacked actions on a phone

Three recovery actions at phone 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 group takes the full width and each button becomes a full-width row (flex-basis 100%).
  • Every button keeps a 2.75rem (44px) minimum height, so adjacent actions are separate touch targets with a 0.5rem gap.
  • Long or localized labels wrap inside the button instead of widening the page.
  • Order is preserved when stacking: the first capability Aegis supplied is still first.
HTML · Stacked actions on a phone Raw HTML for HTML · Stacked actions on a phone
<forma-recovery-actions class="forma-component-tag">
  <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>
    <button type="button" data-forma-aegis-capability="CanReload">Reload</button>
  </div>
</forma-recovery-actions>

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
role.forma-recovery-actionsgroup—Exposes the buttons as one named set.
aria-label.forma-recovery-actionsstring—Names the group, for example "Recovery actions". Include the affected object when several groups share a page.
typebuttonbutton—Required so a recovery button never submits an enclosing form.
data-forma-aegis-capabilitybuttonCanRetry | CanReauthenticate | CanReload | CanQuarantine | CanReprocess | CanOpenReadOnly | CanRestoreSink—The exact Aegis capability case name. Intent only, never authorization: the application revalidates the capability and domain state on every activation.
lang.forma-recovery-actions or buttonBCP 47 taginheritedSet when labels are in a different language from the page so they are pronounced correctly.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-recovery-actionsBlock class—Wrapping flex row with a 0.5rem gap. Direct child buttons get a 44px minimum height; below a 36rem viewport the row fills the width and each button becomes full width.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves between recovery buttons in source order.
Enter / SpaceActivates the focused button (native button behavior).
Events
EventDescription
clickNative click. Limen/application code reads data-forma-aegis-capability, revalidates the current Aegis capability and Ordo/application state, and only then issues the typed recovery request.

Form behavior

Buttons are type="button" and do not participate in form submission or reset.

States

Recovery actions states
StateHow it is expressedPresentation
Availablebutton renderedAegis supplied the capability for the current presentation; it may still be rejected on revalidation.
Focus:focus-visible on the buttonThe shared two-tone focus ring from Forma foundations.
Pressed:activeImmediate darker surface; the hit target does not move.
Absentbutton not renderedAegis did not supply the capability. Do not render a disabled placeholder.

Accessibility

Forma provides

  • Uses native buttons, so role, name, focus and keyboard activation come from the platform.
  • Guarantees a 44px minimum height for each direct child button and full-width stacking on narrow screens.
  • Keeps visible focus and button borders in forced-colors mode through the foundation button styles.

Your application supplies

  • Label each button with the Aegis default label or a faithful localization.
  • Name the group, and include the affected object when a page has several groups.
  • Revalidate on activation and report a rejected or failed recovery with an updated fault presentation.
  • Move focus sensibly after a recovery succeeds and the fault surface is removed.

Responsive behavior

  • A wrapping flex row: buttons flow onto new lines as space runs out; the group itself can shrink to zero minimum width.
  • Below a 36rem viewport the group is full width and every button is a full-width row.
  • Labels wrap inside buttons; nothing forces horizontal overflow at 320px.

Motion

  • No animation beyond the foundation button feedback: hover and release change the background color with a short perceptual transition, and press is immediate.
  • Under prefers-reduced-motion: reduce that transition collapses to 0.01ms. Motion never delays capability execution.

Usage guidance

Do

  • Keep capability identity exact and in the order Aegis supplied.
  • Treat every click as a request that may be refused by current state.

Avoid

  • Styling one recovery action as primary because it seems safest; Forma does not rank recovery options.
  • Adding Continue anyway, Ignore or similar bypass actions.
  • Relying on the presence of a button as proof that the action is still legal.

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.