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
The list is a history of events over time: use Timeline.
The chain supports a security conclusion with evidence ages and invariants: use Security evidence chain.
The path runs between entities in a system map: use Path summary.
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.
<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
Source318 survey responsesImported 22 Sep 2026 · Stale: daily import has not run for 7 days
<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.
<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.
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.
<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.
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
Attribute
On
Values
Default
Description
aria-labelledby
section.forma-provenance-trail
id of the h3
—
Names the trail after the value it explains.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-provenance-trail
Block 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__kind
Element class
—
Stage kind label (Source, Aggregate, Analysis, Presentation) in small monospace secondary text.
Keyboard interaction
Keys
Result
None
Static content; links inside stages are reached with Tab as usual.
Form behavior
Not a form control.
States
Provenance trail states
State
How it is expressed
Presentation
Stage
li in the trail's ol
Kind, name and reference with a marker and connector.
Final stage
:last-child
No connector below the marker.
Stale, unknown or partial stage
application text in the stage
Stated 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.