VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Recovery actions
<forma-recovery-actions>
Native buttons annotated with Aegis capability identity; current authority is revalidated on activation.
- Authoring tag
<forma-recovery-actions>- Category
- Faults and recovery
- 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"andaria-labelso 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.
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.
<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
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.
<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.
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
<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.
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.
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.
<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.
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 |
|---|---|---|---|---|
role | .forma-recovery-actions | group | — | Exposes the buttons as one named set. |
aria-label | .forma-recovery-actions | string | — | Names the group, for example "Recovery actions". Include the affected object when several groups share a page. |
type | button | button | — | Required so a recovery button never submits an enclosing form. |
data-forma-aegis-capability | button | CanRetry | 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 button | BCP 47 tag | inherited | Set when labels are in a different language from the page so they are pronounced correctly. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-recovery-actions | Block 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. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves between recovery buttons in source order. |
| Enter / Space | Activates the focused button (native button behavior). |
| Event | Description |
|---|---|
click | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Available | button rendered | Aegis supplied the capability for the current presentation; it may still be rejected on revalidation. |
| Focus | :focus-visible on the button | The shared two-tone focus ring from Forma foundations. |
| Pressed | :active | Immediate darker surface; the hit target does not move. |
| Absent | button not rendered | Aegis 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: reducethat 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.