Data display

Provenance trail

<forma-provenance-trail>

Trace displayed output through source, aggregate, analysis, and presentation stages.

Authoring tag
<forma-provenance-trail>
Category
Data display
Behavior owner
Application content
Canonical source
patterns/provenance-trail.html

Purpose

A provenance trail explains how a displayed value was produced: an ordered list of stages from source data through aggregation and analysis to presentation, each with a kind label, a name and a small reference such as a version or hash. Forma draws a diamond marker for each stage and a connecting line, and sets the kind and reference in small monospace text. Every fact in the trail is supplied by the application; Forma does not verify or compute any of it.

Use when

  • A metric, score or report value must be traceable to its inputs and the transformations applied.
  • Reviewers need the version of each model, expression or definition used.
  • A value may be stale or partially derived and users should see which stage is affected.

Avoid when

Behavior to know

  • Bordered section with an h3 title and an unstyled ordered list.
  • Each stage is a small grid (kind, name, reference) with a rotated-square marker; a vertical line connects all but the last stage.
  • .forma-provenance-trail__kind and small share small monospace secondary text.
  • Markers are identical for every stage; stage kind is text.

Basic example

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

Canonical

Minimal provenance trail

Rendered from the canonical pattern file.

How this value was produced

  1. Source42 accepted responsesResult set hash 9D2…A7
  2. AggregateGovernance sectionScoring model v3
  3. AnalysisWeighted meanAnalysis expression v1
  4. PresentationMetric cardReport definition v4
HTML · Minimal provenance trail Raw HTML for HTML · Minimal provenance trail
<forma-provenance-trail class="forma-component-tag">
<section class="forma-provenance-trail" aria-labelledby="provenance-title">
  <h3 id="provenance-title">How this value was produced</h3>
  <ol>
    <li><span class="forma-provenance-trail__kind">Source</span><strong>42 accepted responses</strong><small>Result set hash 9D2…A7</small></li>
    <li><span class="forma-provenance-trail__kind">Aggregate</span><strong>Governance section</strong><small>Scoring model v3</small></li>
    <li><span class="forma-provenance-trail__kind">Analysis</span><strong>Weighted mean</strong><small>Analysis expression v1</small></li>
    <li><span class="forma-provenance-trail__kind">Presentation</span><strong>Metric card</strong><small>Report definition v4</small></li>
  </ol>
</section>
</forma-provenance-trail>

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

Examples

Scenario

Trail with a stale source

The source stage is older than its expected refresh. The trail says so in words on that stage, so the reader can see that the analysis and presentation are correct for stale input rather than wrong.

How “Customer satisfaction 4.2” was produced

  1. Source318 survey responsesImported 22 Sep 2026 · Stale: daily import has not run for 7 days
  2. AggregateResponses by regionGrouping rule v2
  3. AnalysisWeighted mean, 1–5 scaleAnalysis expression v3
  4. PresentationExecutive summary cardReport definition v6
HTML · Trail with a stale source Raw HTML for HTML · Trail with a stale source
<forma-provenance-trail class="forma-component-tag">
  <section class="forma-provenance-trail" aria-labelledby="provenance-trail-stale-source-title">
    <h3 id="provenance-trail-stale-source-title">How “Customer satisfaction 4.2” was produced</h3>
    <ol>
      <li><span class="forma-provenance-trail__kind">Source</span><strong>318 survey responses</strong><small>Imported 22 Sep 2026 · Stale: daily import has not run for 7 days</small></li>
      <li><span class="forma-provenance-trail__kind">Aggregate</span><strong>Responses by region</strong><small>Grouping rule v2</small></li>
      <li><span class="forma-provenance-trail__kind">Analysis</span><strong>Weighted mean, 1–5 scale</strong><small>Analysis expression v3</small></li>
      <li><span class="forma-provenance-trail__kind">Presentation</span><strong>Executive summary card</strong><small>Report definition v6</small></li>
    </ol>
  </section>
</forma-provenance-trail>

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

Scenario

Derivation with an unknown step

An imported figure whose transformation step was not recorded. The stage is still listed, with Unknown stated, so the chain does not appear complete when it is not.

Provenance of “Carbon intensity 212 g/kWh”

  1. SourceGrid operator hourly feedFeed hash 4be1…90cf
  2. DerivationUnknownTransformation not recorded by the importer
  3. PresentationSustainability dashboardReport definition v2
HTML · Derivation with an unknown step Raw HTML for HTML · Derivation with an unknown step
<forma-provenance-trail class="forma-component-tag">
  <section class="forma-provenance-trail" aria-labelledby="provenance-trail-unknown-stage-title">
    <h3 id="provenance-trail-unknown-stage-title">Provenance of “Carbon intensity 212 g/kWh”</h3>
    <ol>
      <li><span class="forma-provenance-trail__kind">Source</span><strong>Grid operator hourly feed</strong><small>Feed hash <span class="forma-identifier">4be1…90cf</span></small></li>
      <li><span class="forma-provenance-trail__kind">Derivation</span><strong>Unknown</strong><small>Transformation not recorded by the importer</small></li>
      <li><span class="forma-provenance-trail__kind">Presentation</span><strong>Sustainability dashboard</strong><small>Report definition v2</small></li>
    </ol>
  </section>
</forma-provenance-trail>

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 provenance trail

A four-stage trail at phone width. The marker column is fixed and all text wraps beside it.

Viewport width

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

What changes at narrow widths

  • The trail has no breakpoints: each stage keeps a 2rem inline-start gutter for the marker and connector, and text wraps in the remaining width.
  • Long references such as hashes should use Identifier & critical value so they break at any character at 320px.
  • The connecting line is a pseudo-element sized to each stage, so it stays attached when text wraps onto several lines.
  • The trail is not interactive; any links to stage details keep their own touch targets.
HTML · Mobile provenance trail Raw HTML for HTML · Mobile provenance trail
<forma-provenance-trail class="forma-component-tag">
  <section class="forma-provenance-trail" aria-labelledby="provenance-trail-mobile-provenance-title">
    <h3 id="provenance-trail-mobile-provenance-title">How this score was produced</h3>
    <ol>
      <li><span class="forma-provenance-trail__kind">Source</span><strong>42 accepted assessments</strong><small>Result set <span class="forma-identifier">9D2F4C1A7E0B83F5</span></small></li>
      <li><span class="forma-provenance-trail__kind">Aggregate</span><strong>Governance section</strong><small>Scoring model v3</small></li>
      <li><span class="forma-provenance-trail__kind">Analysis</span><strong>Weighted mean</strong><small>Analysis expression v1</small></li>
      <li><span class="forma-provenance-trail__kind">Presentation</span><strong>Metric card</strong><small>Report definition v4</small></li>
    </ol>
  </section>
</forma-provenance-trail>

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
aria-labelledbysection.forma-provenance-trailid of the h3—Names the trail after the value it explains.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-provenance-trailBlock class—Bordered, padded section. Styles its h3, its unstyled ol, each li stage (grid with a diamond marker and connector) and small references.
.forma-provenance-trail__kindElement class—Stage kind label (Source, Aggregate, Analysis, Presentation) in small monospace secondary text.
Keyboard interaction
KeysResult
NoneStatic content; links inside stages are reached with Tab as usual.

Form behavior

Not a form control.

States

Provenance trail states
StateHow it is expressedPresentation
Stageli in the trail's olKind, name and reference with a marker and connector.
Final stage:last-childNo connector below the marker.
Stale, unknown or partial stageapplication text in the stageStated in words; no special styling.

Accessibility

Forma provides

  • Uses an ordered list so the stage order and count are announced.
  • Draws markers and connectors with pseudo-elements, so decoration is never read aloud.
  • Keeps stage kind as visible text rather than marker shape or color.

Your application supplies

  • Name the trail after the displayed value it explains.
  • Include every stage, including unknown ones, so the chain does not look complete when it is not.
  • State staleness and versions as text; link to stage details if users need them.

Responsive behavior

  • No breakpoints; a fixed 2rem marker gutter and wrapping text work from 320px up.
  • The section has no fixed width and fits its container.

Motion

  • No animation: the trail is static.

Usage guidance

Do

  • Order stages from source to presentation.
  • Give each stage a version or reference users can look up.

Avoid

  • Collapsing stages to make the chain look simpler than it is.
  • Using the trail as a verification result; it describes derivation, not correctness.

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.