Feedback and status

Freshness

<forma-freshness>

States when evidence or data was last verified, with a machine-readable time and an explicit current or stale label.

Authoring tag
<forma-freshness>
Behavior owner
Application state
Canonical source
patterns/freshness.html

Purpose

Freshness tells the user how old a piece of evidence or state is, so they do not mistake an old reading for the current situation. Forma renders a wrapping line with a bold label, a native time element carrying the exact timestamp in datetime, and a state label. The application supplies the time and decides whether it is current or stale under its own freshness policy; Forma does not compute age.

Use when

  • A value, balance, scan result or status was observed at a specific time and may have changed since.
  • The user is about to act on evidence and must know whether it is recent enough.
  • A dashboard or record header shows data refreshed on a schedule.

Avoid when

Behavior to know

  • Uses time with an ISO datetime, so the exact moment is available even when the visible text is relative or local.
  • The state is stated in words (Current, Stale, Never verified), never by color.
  • Label, time and state wrap as separate pieces on narrow screens.

Basic example

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

Canonical

Minimal freshness

Rendered from the canonical pattern file.

Last verified Current

HTML · Minimal freshness Raw HTML for HTML · Minimal freshness
<forma-freshness class="forma-component-tag">
<p class="forma-freshness"><span class="forma-freshness__label">Last verified</span> <time datetime="2026-09-26T04:30:00Z">04:30 UTC</time> <span class="forma-freshness__state">Current</span></p>
</forma-freshness>

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

Examples

Scenario

Stale balance

A balance whose last sync is older than the application's policy allows. The state is shown as an attention Status lozenge so it stands out in grayscale as well as color.

Balance last synced Stale: older than 24 hours

HTML · Stale balance Raw HTML for HTML · Stale balance
<forma-freshness class="forma-component-tag">
  <p class="forma-freshness">
    <span class="forma-freshness__label">Balance last synced</span>
    <time datetime="2026-09-28T14:05:00Z">28 Sep, 14:05 UTC</time>
    <span class="forma-status-lozenge" data-state="attention">Stale: older than 24 hours</span>
  </p>
</forma-freshness>

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

Scenario

Never verified

Evidence that has never been checked. There is no time to show, so the line says so explicitly with an unknown lozenge rather than leaving the time blank.

Backup restore test Never verified

HTML · Never verified Raw HTML for HTML · Never verified
<forma-freshness class="forma-component-tag">
  <p class="forma-freshness">
    <span class="forma-freshness__label">Backup restore test</span>
    <span class="forma-status-lozenge" data-state="unknown">Never verified</span>
  </p>
</forma-freshness>

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

Scenario

Freshness per value

Several values in a Key-value list, each with its own freshness line, because values refreshed at different times must not share one timestamp.

Credit limit
25,000.00 Verified Current
Credit score
712 Verified Stale
HTML · Freshness per value Raw HTML for HTML · Freshness per value
<forma-freshness class="forma-component-tag">
  <dl class="forma-key-value-list">
    <div>
      <dt>Credit limit</dt>
      <dd>25,000.00 <span class="forma-freshness"><span class="forma-freshness__label">Verified</span> <time datetime="2026-09-30T08:00:00Z">today, 08:00 UTC</time> <span class="forma-status-lozenge" data-state="ok">Current</span></span></dd>
    </div>
    <div>
      <dt>Credit score</dt>
      <dd>712 <span class="forma-freshness"><span class="forma-freshness__label">Verified</span> <time datetime="2026-06-02T10:30:00Z">2 Jun 2026</time> <span class="forma-status-lozenge" data-state="attention">Stale</span></span></dd>
    </div>
  </dl>
</forma-freshness>

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

Mobile scan age

A long label and state at phone width.

Viewport width

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

What changes at narrow widths

  • The line is a wrapping flex row: label, time and state move onto new lines when they do not fit.
  • Row gap is 0.25rem and column gap 0.5rem, so wrapped parts stay visually grouped.
  • Each part is kept whole; a lozenge never breaks mid-label, so keep state text short.
  • There are no touch targets; any Refresh action should be a separate button next to the line.
HTML · Mobile scan age Raw HTML for HTML · Mobile scan age
<forma-freshness class="forma-component-tag">
  <p class="forma-freshness">
    <span class="forma-freshness__label">Vulnerability scan of production containers</span>
    <time datetime="2026-09-30T03:15:00Z">today, 03:15 UTC</time>
    <span class="forma-status-lozenge" data-state="ok">Current</span>
  </p>
</forma-freshness>

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
datetimetimeISO 8601 date or date-time—The exact time the evidence was verified. Include a timezone offset or Z.
data-state.forma-status-lozengeok | attention | unknown | blocked—Glyph for the lozenge that names the freshness state.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-freshnessBlock class—Root wrapping flex row with baseline alignment and small gaps. It may be a paragraph or a span; either way it lays out as a block-level flex row.
.forma-freshness__labelElement class—Semibold label describing what the time refers to.
Keyboard interaction
KeysResult
—Not focusable or interactive.
Events
EventDescription
—None. The application re-renders the line when it re-verifies.

Form behavior

Not a form control.

States

Freshness states
StateHow it is expressedPresentation
Currentstate text Current, for example a lozenge with data-state="ok"Within the application's freshness policy.
Stalestate text Stale, for example a lozenge with data-state="attention"Older than the policy permits. The evidence is not proof of the current state.
Never verifiedno time element; state text Never verified with data-state="unknown"No observation exists. Distinct from stale.

Accessibility

Forma provides

  • Keeps the timestamp in a native time element with the exact value in datetime.
  • Presents label, time and state as text in reading order.

Your application supplies

  • Always state the time zone or use relative wording that cannot be misread.
  • Say the state in words; do not rely on formatting to mark stale data.
  • Update the line when the value is refreshed, including the state.
  • The canonical pattern's forma-freshness__state span is not styled by Forma; use a Status lozenge or plain text for the state.

Responsive behavior

  • Wrapping flex row; there are no breakpoints.
  • Can sit inside another value, such as a key-value definition, where it starts on its own line below the value.
  • Long labels wrap; lozenges and times stay whole.

Motion

  • No animation: freshness changes when the application re-renders the time and state.

Usage guidance

Do

  • Show freshness next to the value it qualifies.
  • Name what was verified ("Balance last synced"), not just "Updated".

Avoid

  • Hiding stale data's age behind a tooltip.
  • Showing a time for data that was never retrieved.

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.