Faults and recovery

Fault reference

<forma-fault-reference>

Short quotable Aegis reference with an optional application-owned copy action.

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

Purpose

The fault reference shows the short reference Aegis generates for a fault, such as AG-4F82C, as ordinary selectable text that can be read aloud and quoted to support. It is the only identifier a user needs; it is never replaced by a stack trace, exception type, repository path, token or correlation payload. A copy button may sit beside it, but Forma attaches no behavior: copying to the clipboard, and confirming that it happened, belong to Limen or application code.

Use when

  • Any fault surface shows an Aegis presentation that has a reference.
  • Support conversations need a short identifier the user can read out or paste.
  • You want a copy convenience next to the reference and your application implements it.

Avoid when

  • You need to show an internal identifier, correlation payload or other developer-only value: it does not belong in the user-facing reference.
  • You need a general-purpose identifier display for records or entities: use Identifier & critical value.
  • You need several approved diagnostic values: put them in Fault details and keep the reference visible outside it.

Behavior to know

  • A wrapping flex row: label, code and optional button, with a 0.4rem gap.
  • The code is bold primary text on a secondary-colored label and breaks anywhere, so long references never overflow.
  • The optional copy button has 44px minimum width and height.
  • Selecting the reference with a pointer or keyboard works without the copy button.

Basic example

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

Canonical

Minimal fault reference

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.

Reference AG-4F82C

HTML · Minimal fault reference Raw HTML for HTML · Minimal fault reference
<forma-fault-reference class="forma-component-tag">
<p class="forma-fault-reference">
  <span>Reference</span>
  <code>AG-4F82C</code>
  <button type="button" data-forma-action="copy-reference" aria-label="Copy fault reference AG-4F82C">Copy</button>
</p>
</forma-fault-reference>

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

Examples

Scenario

Reference without a copy action

The minimum form inside a support note. The reference is plain selectable text; no button is rendered because this application does not implement copying.

If this keeps happening, contact support and quote the reference below.

Reference AG-91B7Q

HTML · Reference without a copy action Raw HTML for HTML · Reference without a copy action
<forma-fault-reference class="forma-component-tag">
  <p>If this keeps happening, contact support and quote the reference below.</p>
  <p class="forma-fault-reference">Reference <code>AG-91B7Q</code></p>
</forma-fault-reference>

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

Scenario

Localized label with copy action

A Spanish label and copy button. The copy button's accessible name contains its visible text and the reference, so it is unambiguous when several references are on a page. Clipboard behavior is supplied by the application.

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.

Referencia AG-6YH2D

HTML · Localized label with copy action Raw HTML for HTML · Localized label with copy action
<forma-fault-reference class="forma-component-tag">
  <p class="forma-fault-reference" lang="es">
    <span>Referencia</span>
    <code>AG-6YH2D</code>
    <button type="button" data-forma-action="copy-reference" aria-label="Copiar referencia AG-6YH2D">Copiar</button>
  </p>
</forma-fault-reference>

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

Long reference on a phone

An unusually long reference with a copy button 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

  • The row wraps: the label, code and button flow onto separate lines when they do not fit, instead of overflowing.
  • The code breaks anywhere, so a long reference splits across lines at 320px rather than causing horizontal scrolling.
  • The copy button keeps a 44 by 44px minimum target and never shrinks with the text.
  • Long-press text selection on the code still works on touch devices, so the reference can be copied even without the button.
HTML · Long reference on a phone Raw HTML for HTML · Long reference on a phone
<forma-fault-reference class="forma-component-tag">
  <p class="forma-fault-reference">
    <span>Reference</span>
    <code>AG-4F82C-BILLING-RECIPIENTS-2026-09-30</code>
    <button type="button" data-forma-action="copy-reference" aria-label="Copy fault reference AG-4F82C-BILLING-RECIPIENTS-2026-09-30">Copy</button>
  </p>
</forma-fault-reference>

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
data-forma-actionbuttoncopy-reference—Marks the copy button for application code. Forma attaches no clipboard behavior.
aria-labelbuttonstring—Start with the visible label and include the reference, for example "Copy fault reference AG-4F82C".
typebuttonbutton—Required so the copy button never submits a form.
lang.forma-fault-referenceBCP 47 taginheritedSet when the label is localized differently from the page.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-fault-referenceBlock class—Root paragraph: a wrapping flex row in small secondary text. Its code child is bold primary text that breaks anywhere; a direct button child gets a 44 by 44px minimum size.
Keyboard interaction
KeysResult
Tab / Shift+TabReaches the copy button when present. The reference text itself is not focusable.
Enter / SpaceActivates the copy button; the application performs the copy.
Events
EventDescription
clickNative click on the copy button. Application code writes the reference to the clipboard and may confirm success through its own status message.

Form behavior

Not a form control.

States

Fault reference states
StateHow it is expressedPresentation
Text onlyno buttonLabel and code only; users select the text to copy it.
With copy actionbutton data-forma-action="copy-reference"A native button beside the code; behavior supplied by the application.
Long referencecontentThe code wraps anywhere inside the row.

Accessibility

Forma provides

  • Keeps the reference as real text that screen readers read and users can select.
  • Gives the copy button a 44 by 44px minimum target and the shared focus ring.
  • Renders the label and code as CanvasText in forced-colors mode so neither disappears.

Your application supplies

  • Show only the short Aegis reference; never substitute internal identifiers or diagnostic payloads.
  • Implement copying in application code and confirm it with a status message if you show one, without moving focus.
  • Give the copy button an accessible name that contains its visible text and identifies the reference.
  • Hide the copy button when copying is unavailable rather than showing a button that does nothing.

Responsive behavior

  • Intrinsic sizing: a wrapping flex row that never exceeds its container.
  • The code uses overflow-wrap: anywhere, so long references break across lines at 320px.
  • The copy button keeps its 44px minimum size and wraps to its own line if needed. There are no breakpoints.

Motion

  • No animation: the reference is static text. The optional copy button uses only the foundation hover/press background interpolation, reduced to 0.01ms under prefers-reduced-motion: reduce.

Usage guidance

Do

  • Label the reference so users know what to quote ("Reference", or a localized equivalent).
  • Keep the reference visible on every fault surface, not only inside expanded details.

Avoid

  • Truncating the reference with an ellipsis.
  • Replacing the reference with a long correlation identifier or other developer-only material.
  • Rendering a copy button with no application behavior behind it.

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.