Faults and recovery

Fault summary

<forma-fault-summary>

Focusable grouped presentation of unresolved faults after upstream fingerprinting and deduplication.

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

Purpose

A fault summary lists several unresolved Aegis faults in one programmatically focusable region: a count, a title, and one entry per already-grouped fault with its severity text, reference, occurrence count and, where relevant, a link to the affected region. Forma does not fingerprint, deduplicate or decide that two faults share a cause; Aegis lifecycle logic and the application supply the grouped entries and counts. After a failed submit or similar action the application can move focus to the summary so keyboard and screen-reader users land on one clear starting point.

Use when

  • A consequential action produced more than one unresolved fault and the user needs one place to start.
  • Repeated faults have been grouped upstream and should appear once with an occurrence count.
  • Each fault relates to a region on the page that the user can jump to.

Avoid when

  • There is only one fault and it belongs to a visible region: use Fault inline there.
  • The problems are user input validation errors: use Validation summary.
  • The condition affects the whole application: use Fault banner.
  • You would need Forma to collapse duplicates or compute counts; that logic stays in Aegis or the application.

Behavior to know

  • tabindex="-1" makes the region focusable by script without adding a tab stop.
  • Each entry shows severity as text in its metadata line; Critical entries are also bold.
  • Entries are an ordered list, so the order the application supplies (for example by severity or page position) is announced.
  • No live region by default: announcements happen through focus, not repeated assertive updates.

Basic example

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

Canonical

Minimal fault summary

Rendered from the canonical pattern file.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

2 unresolved faults

Some work needs your attention

Repeated occurrences are grouped by the application before rendering.

  1. Customer name could not be saved Error · AG-4F82C · occurred 3 times
  2. Synchronization is waiting for GitHub Warning · AG-91B7Q
HTML · Minimal fault summary Raw HTML for HTML · Minimal fault summary
<forma-fault-summary class="forma-component-tag">
<section class="forma-fault-summary" tabindex="-1" aria-labelledby="fault-summary-title">
  <div class="forma-fault-summary__heading">
    <div class="forma-fault-summary__marker" aria-hidden="true">!</div>
    <div>
      <p class="forma-fault__severity">2 unresolved faults</p>
      <h2 id="fault-summary-title">Some work needs your attention</h2>
      <p>Repeated occurrences are grouped by the application before rendering.</p>
    </div>
  </div>
  <ol class="forma-fault-summary__list">
    <li data-forma-severity="error">
      <a href="#customer-name">Customer name could not be saved</a>
      <span class="forma-fault-summary__meta">Error · AG-4F82C · occurred 3 times</span>
    </li>
    <li data-forma-severity="warning">
      <a href="#sync-status">Synchronization is waiting for GitHub</a>
      <span class="forma-fault-summary__meta">Warning · AG-91B7Q</span>
    </li>
  </ol>
</section>
</forma-fault-summary>

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

Examples

Scenario

After a failed submit

A summary above a short form after submission failed. Each link targets the affected field in the same page; the critical entry is bold as well as labelled Critical. The application focuses the summary once after the failed submit.

Live demo. 3 native actions work here and are verified by an outcome test.

3 unresolved faults

The claim was not submitted

  1. Payee account could not be verified Critical · AG-5ZE7K
  2. Receipt upload failed Error · AG-5CN0V · occurred 2 times
  3. Exchange rate is from yesterday Warning · AG-40RQN
HTML · After a failed submit Raw HTML for HTML · After a failed submit
<forma-fault-summary class="forma-component-tag">
  <section class="forma-fault-summary" tabindex="-1" aria-labelledby="fault-summary-failed-submit-title">
    <div class="forma-fault-summary__heading">
      <div class="forma-fault-summary__marker" aria-hidden="true">!!</div>
      <div>
        <p class="forma-fault__severity">3 unresolved faults</p>
        <h2 id="fault-summary-failed-submit-title">The claim was not submitted</h2>
      </div>
    </div>
    <ol class="forma-fault-summary__list">
      <li data-forma-severity="critical">
        <a href="#fault-summary-failed-submit-payee">Payee account could not be verified</a>
        <span class="forma-fault-summary__meta">Critical · AG-5ZE7K</span>
      </li>
      <li data-forma-severity="error">
        <a href="#fault-summary-failed-submit-receipt">Receipt upload failed</a>
        <span class="forma-fault-summary__meta">Error · AG-5CN0V · occurred 2 times</span>
      </li>
      <li data-forma-severity="warning">
        <a href="#fault-summary-failed-submit-rate">Exchange rate is from yesterday</a>
        <span class="forma-fault-summary__meta">Warning · AG-40RQN</span>
      </li>
    </ol>
  </section>
  <div class="forma-stack" data-density="compact">
    <div class="forma-field">
      <label class="forma-field__label" for="fault-summary-failed-submit-payee">Payee account</label>
      <input id="fault-summary-failed-submit-payee" name="payee" type="text" value="Northwind Supplies Ltd">
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="fault-summary-failed-submit-receipt">Receipt</label>
      <input id="fault-summary-failed-submit-receipt" name="receipt" type="file">
    </div>
    <div class="forma-field">
      <label class="forma-field__label" for="fault-summary-failed-submit-rate">Exchange rate</label>
      <input id="fault-summary-failed-submit-rate" name="rate" type="text" inputmode="decimal" value="1.1642">
    </div>
  </div>
</forma-fault-summary>

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

Scenario

One grouped fault with many occurrences

Aegis grouped fourteen identical failures into one entry. The summary shows the count supplied upstream; Forma does not compute it. The entry has no affected region, so it is plain text instead of a link.

1 unresolved fault

Nightly export needs attention

Repeated occurrences are grouped by the application before rendering.

  1. Export to the reporting warehouse timed out Error · AG-2RT9M · occurred 14 times since 02:00 UTC
HTML · One grouped fault with many occurrences Raw HTML for HTML · One grouped fault with many occurrences
<forma-fault-summary class="forma-component-tag">
  <section class="forma-fault-summary" tabindex="-1" aria-labelledby="fault-summary-grouped-repeats-title">
    <div class="forma-fault-summary__heading">
      <div class="forma-fault-summary__marker" aria-hidden="true">!</div>
      <div>
        <p class="forma-fault__severity">1 unresolved fault</p>
        <h2 id="fault-summary-grouped-repeats-title">Nightly export needs attention</h2>
        <p>Repeated occurrences are grouped by the application before rendering.</p>
      </div>
    </div>
    <ol class="forma-fault-summary__list">
      <li data-forma-severity="error">
        <strong>Export to the reporting warehouse timed out</strong>
        <span class="forma-fault-summary__meta">Error · AG-2RT9M · occurred 14 times since 02:00 UTC</span>
      </li>
    </ol>
  </section>
</forma-fault-summary>

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

Fault summary on a phone

A summary with long entry titles and references at phone width.

Live demo. 2 native actions work here and are verified by an outcome test.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The summary is a single-column grid at every width; the marker and heading stay side by side and the heading text wraps.
  • Entry links wrap onto several lines and the monospace metadata line breaks anywhere, so long references never cause horizontal scrolling.
  • Links keep their full text as the touch target; leave vertical space between entries (the list uses a 0.65rem gap) rather than shrinking text.
  • Orientation changes only reflow text; list order and numbering stay the same.
HTML · Fault summary on a phone Raw HTML for HTML · Fault summary on a phone
<forma-fault-summary class="forma-component-tag">
  <section class="forma-fault-summary" tabindex="-1" aria-labelledby="fault-summary-mobile-summary-title">
    <div class="forma-fault-summary__heading">
      <div class="forma-fault-summary__marker" aria-hidden="true">!</div>
      <div>
        <p class="forma-fault__severity">2 unresolved faults</p>
        <h2 id="fault-summary-mobile-summary-title">Some changes were not saved</h2>
      </div>
    </div>
    <ol class="forma-fault-summary__list">
      <li data-forma-severity="error">
        <a href="#fault-summary-mobile-summary-title">Delivery instructions for the north warehouse loading dock could not be saved</a>
        <span class="forma-fault-summary__meta">Error · AG-4F82C-DELIVERY-NORTH · occurred 3 times</span>
      </li>
      <li data-forma-severity="warning">
        <a href="#fault-summary-mobile-summary-title">Synchronization is waiting for the carrier service</a>
        <span class="forma-fault-summary__meta">Warning · AG-91B7Q</span>
      </li>
    </ol>
  </section>
</forma-fault-summary>

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 links point to placeholder destinations that do not exist on this site. 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
tabindexsection.forma-fault-summary-1—Required. Lets the application move focus to the summary after a failed operation without adding a tab stop.
aria-labelledbysection.forma-fault-summaryid of the heading—Names the region so focus lands on a named landmark.
data-forma-severitylidiagnostic | warning | error | critical—Records each entry's Aegis severity. critical makes the entry bold; the severity must also be written in the metadata line.
hrefa#id of the affected region—Links an entry to the field or region it concerns. Omit the link when there is no affected region.
aria-hidden.forma-fault-summary__markertrue—Hides the decorative marker glyph.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-fault-summaryBlock class—Root section: a bordered grid with a strong 3px focus-visible outline and ring so programmatic focus is visible.
.forma-fault-summary__headingElement class—Two-column grid placing the marker beside the count, heading and optional note.
.forma-fault-summary__listElement class—Ordered list of grouped entries with a 0.65rem gap and visible numbering.
.forma-fault-summary__markerElement class—Decorative round marker glyph.
.forma-fault-summary__metaElement class—Monospace metadata line for severity, reference and occurrence count; breaks anywhere.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves between entry links. The summary itself is not in the tab order (tabindex=-1).
EnterFollows the focused link to the affected region (native link behavior). The target should be focusable or a form control so focus moves with it.
Events
EventDescription
—No Forma events. The application calls focus() on the summary after a failed submit; links use native navigation.

Form behavior

Not a form control. It can sit above a form and link to its fields.

States

Fault summary states
StateHow it is expressedPresentation
UnfocuseddefaultA bordered region listing the grouped faults.
Focused:focus-visible after application focus()3px outline with an outer focus ring; the region is announced by its name.
Critical entryli data-forma-severity="critical" plus textEntry text is bold in addition to the Critical label.
Grouped entryoccurrence text supplied by the applicationThe meta line states how many times the grouped fault occurred.

Accessibility

Forma provides

  • Provides a strong visible focus indicator for the region when it receives focus.
  • Writes severity as text in every entry and uses bold weight for Critical as a non-color cue.
  • Keeps the marker decorative and the list semantic, so entries are counted and ordered for assistive technology.
  • Keeps borders, marker and metadata text visible in forced-colors mode.

Your application supplies

  • Supply already-grouped entries and occurrence counts from Aegis; never deduplicate in markup.
  • Focus the summary once after a failed consequential action; do not add an assertive live region that repeats on every render.
  • Make link targets focusable (form controls, or elements with tabindex="-1") so focus follows navigation.
  • Update or remove entries as Aegis reports faults resolved, reopened or superseded.

Responsive behavior

  • A single-column grid at every width; the heading row keeps the marker in an intrinsic-width column.
  • Entry links and headings wrap; metadata uses overflow-wrap: anywhere so long references fit at 320px.
  • There are no breakpoints; the list numbering uses a 1.4rem inline-start padding that remains readable on phones.

Motion

  • No animation: the summary appears with the application's render and focus moves to it immediately.
  • Only native link and focus styling change state; nothing slides, fades or pulses.

Usage guidance

Do

  • State the count in the first line so users know how much work there is.
  • Order entries meaningfully, for example by severity or by position on the page.
  • Keep the reference in each entry so support can match it.

Avoid

  • Listing the same fault several times instead of an occurrence count.
  • Using role="alert" and re-rendering, which repeats the announcement.
  • Linking to regions that no longer exist after the fault resolves.

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.