Faults and recovery

Fault details

<forma-fault-details>

Optional disclosure for explicitly approved and already-sanitized diagnostic values only.

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

Purpose

Fault details is a native details disclosure holding a short description list of diagnostic values that the application has explicitly approved for the current audience, such as the public reference, application name, recovery state, a user-visible dependency name or an approved timestamp. It is deliberately conservative and is not an escape hatch for raw fault data. Redaction and authorization happen before the data reaches Forma: the application builds a separate safe view model and renders only that. Stack traces, exception details, secrets, raw context values, breadcrumbs, snapshot locations, tokens and internal paths never belong here.

Use when

  • Support or power users benefit from a few extra, approved facts about a fault without cluttering the primary message.
  • The application already has an audience-specific safe view model for the fault.
  • The details should be available on request rather than always visible.

Avoid when

  • The only extra information is the reference: show it with Fault reference in the fault body instead.
  • The values have not been sanitized and approved for this audience: do not render them at all.
  • You need a general optional-content disclosure unrelated to faults: use Disclosure.
  • You need a structured key/value display that is always visible: use Key-value list.

Behavior to know

  • Native details/summary: the browser owns open state, keyboard toggling and the expanded state exposed to assistive technology.
  • The summary row has a 44px minimum height so it is a comfortable touch target.
  • Terms and values sit in two columns on wide screens and stack below 36rem; values break anywhere.
  • An optional boundary note reminds readers that only approved values appear.

Basic example

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

Canonical

Minimal fault details

Rendered from the canonical pattern file.

Live demo. 1 native action works here and is verified by an outcome test.

Safe diagnostic details
Reference
AG-4F82C
Application
Chrona
Recovery state
Retry available

Only explicitly approved, already-sanitized diagnostic values belong in this surface.

HTML · Minimal fault details Raw HTML for HTML · Minimal fault details
<forma-fault-details class="forma-component-tag">
<details class="forma-fault-details">
  <summary>Safe diagnostic details</summary>
  <div class="forma-fault-details__content">
    <dl class="forma-fault-details__list">
      <div><dt>Reference</dt><dd><code>AG-4F82C</code></dd></div>
      <div><dt>Application</dt><dd>Chrona</dd></div>
      <div><dt>Recovery state</dt><dd>Retry available</dd></div>
    </dl>
    <p class="forma-fault-details__boundary">Only explicitly approved, already-sanitized diagnostic values belong in this surface.</p>
  </div>
</details>
</forma-fault-details>

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

Examples

Scenario

Support view, open by default

A support agent's view where the application opens the disclosure initially with the open attribute. Every row comes from an approved safe view model; the dependency name is the user-visible service name, not an internal host.

Live demo. 1 native action works here and is verified by an outcome test.

Safe diagnostic details
Reference
AG-8LM3E
Application
Chrona
Affected service
Calendar sync
Recovery state
Waiting for sign-in
First seen

Only explicitly approved, already-sanitized diagnostic values are shown here.

HTML · Support view, open by default Raw HTML for HTML · Support view, open by default
<forma-fault-details class="forma-component-tag">
  <details class="forma-fault-details" open>
    <summary>Safe diagnostic details</summary>
    <div class="forma-fault-details__content">
      <dl class="forma-fault-details__list">
        <div><dt>Reference</dt><dd><code>AG-8LM3E</code></dd></div>
        <div><dt>Application</dt><dd>Chrona</dd></div>
        <div><dt>Affected service</dt><dd>Calendar sync</dd></div>
        <div><dt>Recovery state</dt><dd>Waiting for sign-in</dd></div>
        <div><dt>First seen</dt><dd><time datetime="2026-09-30T09:40:00Z">30 Sep 2026, 09:40 UTC</time></dd></div>
      </dl>
      <p class="forma-fault-details__boundary">Only explicitly approved, already-sanitized diagnostic values are shown here.</p>
    </div>
  </details>
</forma-fault-details>

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

Scenario

Collapsed details under an inline fault

The disclosure composed inside the body of an inline fault, after the reference. The fault's message and recovery action remain visible whether or not the details are expanded.

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

Report export failed.

Your report settings are saved. Try the export again.

Reference AG-2RT9M

Safe diagnostic details
Export format
PDF
Recovery state
Retry available
HTML · Collapsed details under an inline fault Raw HTML for HTML · Collapsed details under an inline fault
<forma-fault-details class="forma-component-tag">
  <div class="forma-fault forma-fault--inline" role="group" data-forma-intent="inline" data-forma-severity="error" aria-labelledby="fault-details-inside-inline-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="fault-details-inside-inline-fault-title"><strong>Report export failed.</strong></p>
      <p class="forma-fault__message">Your report settings are saved. Try the export again.</p>
      <p class="forma-fault-reference">Reference <code>AG-2RT9M</code></p>
      <details class="forma-fault-details">
        <summary>Safe diagnostic details</summary>
        <div class="forma-fault-details__content">
          <dl class="forma-fault-details__list">
            <div><dt>Export format</dt><dd>PDF</dd></div>
            <div><dt>Recovery state</dt><dd>Retry available</dd></div>
          </dl>
        </div>
      </details>
    </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-details>

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 values on a phone

An expanded disclosure with long values at phone width.

Live demo. 1 native action works here and is 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

  • Below 36rem each term/value pair stacks into one column with the value directly under its term.
  • Values use overflow-wrap: anywhere, so long references and service names wrap instead of widening the page.
  • The summary row keeps a 44px minimum height and the whole row toggles the disclosure on tap.
  • Orientation changes only reflow the rows; the order of terms does not change.
HTML · Stacked values on a phone Raw HTML for HTML · Stacked values on a phone
<forma-fault-details class="forma-component-tag">
  <details class="forma-fault-details" open>
    <summary>Safe diagnostic details</summary>
    <div class="forma-fault-details__content">
      <dl class="forma-fault-details__list">
        <div><dt>Reference</dt><dd><code>AG-4F82C-BILLING-RECIPIENTS-2026-09-30</code></dd></div>
        <div><dt>Affected service</dt><dd>Customer billing recipients directory</dd></div>
        <div><dt>Recovery state</dt><dd>Retry available after sign-in</dd></div>
      </dl>
    </div>
  </details>
</forma-fault-details>

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.

Live demo. 1 native action works here and is verified by an outcome test.

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
opendetailsbooleanabsent (collapsed)Initial expanded state. The live state is owned by the browser; the user can always toggle it.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-fault-detailsBlock class—Root native details element with top and bottom borders.
.forma-fault-details__boundaryElement class—Optional small note stating that only approved, sanitized values appear.
.forma-fault-details__contentElement class—Wrapper for the expanded content with bottom padding.
.forma-fault-details__listElement class—Description list of approved term/value pairs; each pair is a div laid out as a two-column grid (terms at least 7rem) that stacks below 36rem.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus to and from the summary.
Enter / SpaceToggles the disclosure (native details behavior).
Events
EventDescription
toggleNative event fired by details when it opens or closes. Forma attaches nothing to it; any on-demand loading must still return only approved, sanitized values.

Form behavior

Not a form control.

States

Fault details states
StateHow it is expressedPresentation
Collapsedno open attributeOnly the summary row is visible.
Expandedopen / [open]The approved values and optional boundary note are shown.
Focus:focus-visible on summaryThe shared two-tone focus ring on the summary row.

Accessibility

Forma provides

  • Keeps the platform details/summary semantics, so the expanded state and keyboard toggling come from the browser.
  • Gives the summary a 44px minimum height and pointer cursor.
  • Uses description-list semantics so terms and values are announced as pairs.
  • Keeps borders and the boundary note visible as CanvasText in forced-colors mode.

Your application supplies

  • Build a separate audience-safe view model and render only its fields; never bind raw fault records.
  • Keep the reference, message and recovery actions outside the disclosure so they are never hidden.
  • Write a summary label that says what is inside ("Safe diagnostic details").
  • The summary uses a flex layout, which can suppress the native disclosure triangle; if your audience needs a visible expanded/collapsed cue, state it in the summary text or supporting copy.

Responsive behavior

  • Rows are a two-column grid (minmax(7rem, auto) minmax(0, 1fr)) on wide viewports.
  • Below a 36rem viewport each row stacks into one column with a small gap.
  • Values break anywhere, so long references and names never overflow at 320px.

Motion

  • No animation: the native details element opens and closes instantly. The component is not part of the physics motion set, so nothing slides or fades.

Usage guidance

Do

  • Keep the list short and meaningful to the audience.
  • Include the reference again inside the details when support staff read the expanded view.

Avoid

  • Rendering stack traces, exception details, secrets, tokens, internal paths, raw context or breadcrumbs.
  • Hiding recovery actions or the only copy of the reference inside the disclosure.
  • Using fault details as a general debugging panel.

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.