Faults and recovery

Diagnostic status

<forma-diagnostic-status>

Text-first presentation of synchronized, queued, unavailable, or failed diagnostic persistence state.

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

Purpose

Diagnostic status shows the Aegis persistence state: whether diagnostic reports are synchronized, queued locally (with a count), unavailable, or whether the last synchronization failed (with a safe reason). It is operational state, not a fault severity, so it has no severity label and never replaces a fault surface. The state is always written as text; the marker glyph and the heavier border for unavailable and failed states are secondary cues. The application maps Aegis PersistenceState to data-forma-state and supplies the wording.

Use when

  • The application explicitly chooses to show whether diagnostics are reaching their destination, for example in a status bar, settings page or support panel.
  • Aegis intent is Silent for a fault, but the user or an operator still benefits from seeing that reports are queued.
  • A support flow needs to confirm that diagnostics were delivered before asking the user to retry.

Avoid when

Behavior to know

  • Four states: synchronized, queued, unavailable and last-synchronization-failed, each written in text.
  • Unavailable and failed states use a 2px border in addition to their text.
  • Inline-level: it sits in a status bar or next to other content without taking the full width.
  • Carries role="status" so an application update to the text is announced politely.

Basic example

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

Canonical

Minimal diagnostic status

Rendered from the canonical pattern file.

Diagnostics queued 3 reports are waiting to synchronize.
HTML · Minimal diagnostic status Raw HTML for HTML · Minimal diagnostic status
<forma-diagnostic-status class="forma-component-tag">
<div class="forma-diagnostic-status" data-forma-state="queued" role="status">
  <span class="forma-diagnostic-status__marker" aria-hidden="true">↥</span>
  <span class="forma-diagnostic-status__body">
    <strong>Diagnostics queued</strong>
    <span>3 reports are waiting to synchronize.</span>
  </span>
</div>
</forma-diagnostic-status>

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

Examples

Scenario

All diagnostics delivered

The normal state in a support panel. No role is needed here because this status is rendered once with the panel and does not change while the user reads it.

Diagnostics synchronized Last report delivered at .
HTML · All diagnostics delivered Raw HTML for HTML · All diagnostics delivered
<forma-diagnostic-status class="forma-component-tag">
  <div class="forma-diagnostic-status" data-forma-state="synchronized">
    <span class="forma-diagnostic-status__marker" aria-hidden="true">✓</span>
    <span class="forma-diagnostic-status__body">
      <strong>Diagnostics synchronized</strong>
      <span>Last report delivered at <time datetime="2026-09-30T08:14:00Z">08:14 UTC</time>.</span>
    </span>
  </div>
</forma-diagnostic-status>

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

Scenario

Last synchronization failed

The failed state with a safe, user-facing reason supplied by the application. The heavier 2px border repeats the text cue. The reason is not an exception message.

Last synchronization failed The diagnostics service rejected the upload. 5 reports are kept on this device.
HTML · Last synchronization failed Raw HTML for HTML · Last synchronization failed
<forma-diagnostic-status class="forma-component-tag">
  <div class="forma-diagnostic-status" data-forma-state="last-synchronization-failed" role="status">
    <span class="forma-diagnostic-status__marker" aria-hidden="true">!</span>
    <span class="forma-diagnostic-status__body">
      <strong>Last synchronization failed</strong>
      <span>The diagnostics service rejected the upload. 5 reports are kept on this device.</span>
    </span>
  </div>
</forma-diagnostic-status>

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

Scenario

Diagnostics unavailable with a recovery action

The unavailable state next to the Reconnect diagnostics capability that Aegis supplied. The status and the recovery group are siblings; the status stays text-first and the button is an ordinary recovery action.

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.

Diagnostics unavailable Reports cannot be stored or sent right now.
HTML · Diagnostics unavailable with a recovery action Raw HTML for HTML · Diagnostics unavailable with a recovery action
<forma-diagnostic-status class="forma-component-tag">
  <div class="forma-cluster">
    <div class="forma-diagnostic-status" data-forma-state="unavailable" role="status">
      <span class="forma-diagnostic-status__marker" aria-hidden="true">×</span>
      <span class="forma-diagnostic-status__body">
        <strong>Diagnostics unavailable</strong>
        <span>Reports cannot be stored or sent right now.</span>
      </span>
    </div>
    <div class="forma-recovery-actions" role="group" aria-label="Diagnostics recovery">
      <button type="button" data-forma-aegis-capability="CanRestoreSink">Reconnect diagnostics</button>
    </div>
  </div>
</forma-diagnostic-status>

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

Queued reports on a phone

The queued state with a longer explanation at phone width.

Viewport width

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

What changes at narrow widths

  • The status is inline-flex and limited to 100% of its container, so on a phone it becomes as wide as the screen allows and the text column wraps.
  • The marker keeps a fixed 1.5rem column; only the text column reflows.
  • It has no interactive target of its own; any recovery button placed beside it follows the 44px recovery-action sizing.
  • Orientation changes only reflow the text.
HTML · Queued reports on a phone Raw HTML for HTML · Queued reports on a phone
<forma-diagnostic-status class="forma-component-tag">
  <div class="forma-diagnostic-status" data-forma-state="queued" role="status">
    <span class="forma-diagnostic-status__marker" aria-hidden="true">↥</span>
    <span class="forma-diagnostic-status__body">
      <strong>Diagnostics queued</strong>
      <span>12 reports are waiting and will be sent automatically when this phone is back online.</span>
    </span>
  </div>
</forma-diagnostic-status>

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.

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-state.forma-diagnostic-statussynchronized | queued | unavailable | last-synchronization-failed—The Aegis persistence state. unavailable and last-synchronization-failed get a 2px border; the text must still state the state.
role.forma-diagnostic-statusstatusabsentUse when the application updates the status in place so changes are announced politely. Omit for a static one-time render.
aria-hidden.forma-diagnostic-status__markertrue—Hides the decorative glyph.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-diagnostic-statusBlock class—Root: an inline-flex row with a 1px border on the secondary surface, limited to its container's width.
.forma-diagnostic-status__bodyElement class—Grid holding the state (strong text) and the supporting detail line.
.forma-diagnostic-status__markerElement class—Decorative glyph column, 1.5rem minimum width, monospace and bold.
[data-forma-state]Attribute hook"last-synchronization-failed", "unavailable"The values unavailable and last-synchronization-failed increase the border to 2px; synchronized and queued keep 1px.
Keyboard interaction
KeysResult
—Not interactive. It is never focusable; any related recovery button is a separate native button.
Events
EventDescription
—No events. The application updates the text and data-forma-state when Aegis persistence state changes.

Form behavior

Not a form control.

States

Diagnostic status states
StateHow it is expressedPresentation
Synchronizeddata-forma-state="synchronized"Reports are delivered. 1px border.
Queueddata-forma-state="queued" with a count in textReports are held locally and waiting. 1px border.
Unavailabledata-forma-state="unavailable"Diagnostics cannot be stored or sent. 2px border.
Last synchronization faileddata-forma-state="last-synchronization-failed" with a safe reasonThe most recent attempt failed. 2px border.

Accessibility

Forma provides

  • Requires the state to be written as text; the glyph is decorative and the border weight is an extra non-color cue.
  • Uses Canvas/CanvasText for border, surface and detail text in forced-colors mode.

Your application supplies

  • Write the state in words ("Diagnostics queued"), including the count for queued reports.
  • Use role="status" only when you update the element in place, and avoid updating it so often that it becomes noisy.
  • Keep the failure reason safe and user-facing; never place raw exception text in it.
  • Do not present persistence state as a fault severity.

Responsive behavior

  • Intrinsic sizing: inline-flex, never wider than its container (max-inline-size: 100%).
  • The text column wraps; the marker keeps its 1.5rem minimum width.
  • No breakpoints. Place it in a Cluster with related actions so they wrap together on narrow screens.

Motion

  • No animation: state changes replace the text and border immediately. Nothing spins or pulses to show queued or failed states.

Usage guidance

Do

  • Show the queued count so users know reports are not lost.
  • Pair unavailable or failed states with the Reconnect diagnostics action only when Aegis supplies CanRestoreSink.

Avoid

  • Showing diagnostic status as a substitute for presenting a fault.
  • Color-only indicators such as a colored dot without text.

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.